/cix

name: cix
description: Semantic code search and navigation using the cix index. Reach for cix when you don't already know where to look. Covers search, definitions, references, symbols, files, and indexing.
user-invocable: true

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:

| Command | Returns | Output size | |---|---|---| | `cix def <symbol>` | definition location + signature | ~250 B | | `cix refs <symbol>` | every call site (file:line) | ~1 KB | | `cix search "<intent>"` | matching code **with full source bodies** | ~7 KB |

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 t