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 (see cix list); no arg defaults to the current directory. add links an already-indexed project — it does not clone (to clone a new GitHub repo into a workspace, use the dashboard). delete drops the workspace + its links, not the projects.

For the full cross-project research workflow — which repos to trust, how to read the hybrid bm25/dense scores — use the dedicated cix-workspace skill (/cix-workspace <task>).

Search quality — what scores mean

Default --min-score 0.4 is calibrated for the production embedding model (CodeRankEmbed-Q8 with path-aware preamble). Rough landscape:

If a query returns nothing, lower the floor explicitly: --min-score 0.2 for very specific or long-tail queries. Don't drop below 0.2 — results below that are noise.

Writing better queries — leverage path-aware embedding

Each chunk is embedded with its file path, language, and symbol name in the preamble. This means mentioning a file/dir/symbol you already know about boosts ranking:

# Generic
cix search "validation"
# Better — pins the search to the auth area
cix search "validation in auth middleware"
# Even better when you know the symbol
cix search "ValidateToken" --kind function

Natural-language queries that name the kind of thing and where it lives outperform single-word queries.

Usage Patterns

Exploring unfamiliar code (cix's strongest case)

cix summary                              # project structure, top dirs
cix search "main entry point server"     # find where it starts
cix search "database connection setup"   # find DB wiring
cix search "request handler" --in ./api  # narrow to API

Tracing a symbol end-to-end

cix def HandleRequest        # where is it defined?
cix refs HandleRequest       # who calls it?
cix search "HandleRequest error handling"   # how are errors handled?

Chasing a known target (often grep is enough)

# Stack trace says "internal/auth/middleware.go:42 — invalid token"
# → just Read that file. No cix needed.

# Config key "max_concurrent_requests" used somewhere?
# → grep is more precise.

Narrowing scope

cix search "middleware" --in ./api/
cix search "config" --in ./cmd/ --exclude legacy
cix refs Config --file ./internal/server.go

Tips

• Search queries are natural language, not regex. Write what you'd ask a colleague.
• Output groups by file: each result line is a file with all relevant matches inside, ordered top-to-bottom by line number. The [best 0.NN] is the score of the top hit in that file.
• cix def is a faster path than cix symbols when you already know the exact name.
• --exclude complements --in — use it to drop noisy dirs (bench/, legacy/, vendored code) inline without touching .cixignore.
• The watcher keeps the index fresh. If results feel stale, check cix status first — Watcher: ✗ not running is the usual cause.
• Don't loop. If a query returns nothing useful after one well-phrased attempt + one --min-score 0.2 retry, drop to grep.