Code Index (cix) — Semantic Code Search & Navigation

You have access to cix, a semantic code index that understands the codebase via embeddings + AST parsing. The right reflex is "cix when you don't have a pointer; grep when you do."

When to use which

Reach for cix first when:

• The starting point is open-ended ("how does indexing work?", "find the authentication middleware", "where is the main entry point?")
• You need cross-file navigation (definitions / references / callers)
• You're searching by meaning, not by an exact string ("JWT validation" should find verifyToken even without that phrase)
• You're exploring an unfamiliar package or codebase

Skip cix, use Read / Grep / Glob directly when:

• A failing test or stack trace already names the file and function — just Read it
• You're chasing an exact literal: a specific error message, a config key, a commit-message phrase, an import path
• You're inside dependencies (node_modules, vendor, .venv) — they aren't indexed
• You're editing a non-code file (Dockerfile, yaml, lockfile)

If cix returns nothing relevant after one well-formed query, fall back to grep — don't loop on cix.

Pick the cheapest tool that answers the question

When you already know a symbol's name, reach for cix def / cix refs before cix search. They return metadata only (file, line, signature, call sites) — no source bodies — so they cost roughly an order of magnitude fewer tokens. Measured on one real symbol in this codebase:

So cix search is ~28× the bytes of cix def and ~6× cix refs for the same target. Rule of thumb:

• Know the name, want "where is it defined / who calls it" → cix def / cix refs. Cheap, precise, no source noise.
• Don't know the name, searching by meaning → cix search.
• Only escalate to cix search for a known symbol when you actually need to read the surrounding implementation, not merely locate it.

Commands Reference

Semantic Search — find code by meaning

cix search "authentication middleware"
cix search "database connection retry logic"
cix search "error handling in payment flow" --limit 20
cix search "config parsing" --in ./internal/config/
cix search "API routes" --lang go
cix search "main entry point" --exclude bench/fixtures --exclude legacy

Flags:

• --in <path> — restrict to file or directory (can repeat)
• --exclude <path> — drop a directory or substring from results (can repeat)
• --lang <language> — filter by language (can repeat)
• --limit <n> — max files returned (CLI default: 10) — output is grouped per file with all matches inside, so 10 files ≈ many snippets. For agent use, prefer --limit 5: five files is enough for most lookups and keeps the result compact. This is a usage recommendation, not a change to the CLI default — bump it back up when you genuinely need broader exploration.
• --min-score <f> — minimum relevance 0.0–1.0 (default: 0.4)

Go to Definition — find where a symbol is defined

cix definitions HandleRequest
cix def AuthMiddleware --kind function
cix def Config --file ./internal/config.go

Aliases: definitions, def, goto. Flags: --kind, --file, --limit.

Find References — find where a symbol is used

cix references HandleRequest
cix refs AuthMiddleware --limit 50
cix usages UserService --file ./internal/api/

Aliases: references, refs, usages. Flags: --file, --limit.

Symbol Search — find symbols by name

cix symbols handleRequest
cix symbols User --kind class
cix symbols Auth --kind function --kind method

Flags: --kind (function/class/method/type, repeatable), --limit.

File Search — find files by path pattern

cix files "config"
cix files "middleware" --limit 20

Read Files & List Directories — EXTERNAL repos only

cix file internal/httpapi/server.go -n github.com/owner/repo@main   # whole file
cix file README.md --lines 1:40 -n github.com/owner/repo@main       # line range
cix tree -n github.com/owner/repo@main                              # repo root, one level
cix tree internal/httpapi -n github.com/owner/repo@main             # a subdir

Reads file contents / the file tree from the server's checkout of an external (GitHub-backed) repo — for inspecting repos you don't have locally (workspace / external projects). Only for OTHER repos: for the current / local project use native Read/Grep/ls (faster, no server round-trip); on a local project these return an error saying so. --lines is 1-based inclusive.

Project Overview

cix summary        # languages, top dirs, key symbols
cix status         # indexing status + file watcher status
cix list           # all indexed projects

Indexing

cix init [path]         # register + index + start watcher
cix reindex             # incremental
cix reindex --full      # full reindex
cix cancel              # cancel an in-flight indexing run
cix watch               # start file-change auto-reindex daemon
cix watch stop          # stop daemon

The watcher auto-reindexes on file change — manual reindex is rarely needed. cix status shows whether the watcher is running and the last-sync timestamp.

Servers — talk to more than one cix backend

cix can be configured with several named servers (e.g. a local box and a remote corporate server). One is the default; every command targets the default unless you pass --server <alias>.

cix config show                                # lists servers; * marks the default
cix --server corporate search "rate limiter"   # run any command against a named server
cix search "rate limiter" --server corporate   # --server is global; either position works

Servers are managed through cix config (persisted in ~/.cix/config.yaml):

cix config set server.corporate.url https://cix.corp.internal
cix config set server.corporate.key <bearer-token>
cix config set default_server corporate        # change which server is the default
cix config unset server.corporate              # remove a server
cix config unset server.corporate.key          # clear just its key

The legacy single-server keys still work and operate on the default server, so existing setups keep working unchanged: cix config set api.url <url> / cix config set api.key <key>. The --api-url / --api-key flags override the selected server's URL/key for a single invocation.

Agent rule: use the default server (no flag) unless the user names a specific server. Only add --server <alias> when the task explicitly targets that named backend; never guess an alias — run cix config show to see the configured names if unsure.

Workspaces — cross-repo search + management

A workspace groups several indexed repos into one corpus for cross-project search. List / describe / search:

cix ws                                   # list workspaces
cix ws "<name>"                          # describe (repos + status)
cix ws "<name>" search "<query>"         # hybrid cross-repo search

Manage (owner/admin):

cix ws create "<name>" [--description "…"]   # create
cix ws "<name>" add <project…>               # link an indexed project (local or external)
cix ws "<name>" remove <project…>            # unlink
cix ws "<name>" rename "<new>"               # rename
cix ws "<name>" update [--name "<new>"] [--description "…"]
cix ws "<name>" delete [-y]                  # delete (prompts; -y skips)

add/remove take a project's absolute path, host_path (github.com/owner/repo@main), or 16-hex path_hash (