cix

name	cix
description	Semantic code search and navigation across repositories indexed by a cix server, via the cix_* MCP tools. Use when finding code by meaning rather than exact strings — "find the authentication middleware", "where is X defined?", "what calls this function?", "how does Y work in this codebase?", "search the codebase for ...", or "explore this repo". The cix connection talks to a server that may hold many repos and has no current project, so always discover projects first and pass an explicit project (a host_path) to per-repo tools.
metadata	{"version":"0.1.0","surface":"cowork"}

Code Index (cix) — Semantic Code Search & Navigation

cix is a semantic code index that understands code via embeddings + AST parsing. You reach it through the cix_* MCP tools (no shell, no CLI). The right reflex is "cix when you don't have a pointer; read/grep when you do."

This connection talks to a cix SERVER, not a single project. One server may hold many indexed repositories, and nothing is inferred from a working directory — there is no "current project." Every per-repo tool needs an explicit project (a repository's host_path). So the first move is always to discover what's indexed.

First, orient

Before any per-repo call:

1. Call cix_list_projects to see the indexed repositories. Each row has a host_path (e.g. /Users/me/acme-api or github.com/acme/api@main).
2. Pick the host_path of the repo the user means, and pass it as the project argument to every per-repo tool below.

If the repo the user is asking about is not in cix_list_projects, this skill cannot index it — indexing is server-side. Tell the user to index it (via the cix dashboard, or cix init on the machine running the cix server), then retry.

You don't have to memorize host_paths: if you call a per-repo tool with a missing or unknown project, the server replies with an error that lists the valid projects, so you can self-correct in one step.

(Multi-server: cix_list_servers lists configured servers; every tool takes an optional server argument. Omit it for the default — most setups have one server. Only pass server when the user names a specific backend; never guess a name — call cix_list_servers.)

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 an exact string ("JWT validation" should find verifyToken even without that phrase)
• You're exploring an unfamiliar package or repo

Skip cix when:

• A failing test or stack trace already names the file and function, and that file is available locally — just Read it
• You're chasing an exact literal (a specific error message, a config key, an import path) in a repo you have on disk — a literal Grep is more precise
• You're inside dependencies (node_modules, vendor, .venv) — not indexed

Note: for remote-only indexed repos (host_path like github.com/owner/repo@branch, not on disk), the cix_* tools are your only way in — there's no local tree to Read or Grep. Use cix for everything there.

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

Pick the cheapest tool that answers the question

When you already know a symbol's name, reach for cix_definitions / cix_references before cix_search. They return metadata only (file, line, signature, call sites) — no source bodies — so they cost far fewer tokens.

Tool	Returns	Relative size
cix_definitions	definition location + signature	~1×
cix_references	every call site (file:line)	~4×
cix_search	matching code with full source bodies	~28×

Rule of thumb:

• Know the name, want "where is it defined / who calls it" → cix_definitions / cix_references. Cheap, precise, no source noise.
• Don't know the name, searching by meaning → cix_search.
• Escalate to cix_search for a known symbol only when you actually need to read the surrounding implementation, not merely locate it.

Tools reference

Every tool below takes project (a host_path from cix_list_projects) and an optional server.

cix_search — find code by meaning

Args: project (required), query (required), and optional limit, lang, in, exclude, min_score.

• in — restrict to these paths (relative paths resolve against the repo root).
• exclude — drop these paths from results.
• lang — filter by language (e.g. go, python, typescript).
• limit — max files returned (default 5; output groups all matches per file, so 5 files ≈ many snippets). Bump up only for broad exploration.
• min_score — minimum relevance 0.0–1.0 (default 0.4).

Examples (as tool calls): cix_search(project, "authentication middleware"); cix_search(project, "config parsing", in=["internal/config"]); cix_search(project, "API routes", lang=["go"]).

cix_definitions — where a symbol is defined

Args: project, symbol (required); optional kind (function/class/method/type), file, limit.

cix_references — where a symbol is used

Args: project, symbol (required); optional file, limit.

cix_symbols — find symbols by name

Args: project, query (required); optional kinds, limit.

cix_files — find files by path pattern

Args: project, pattern (required); optional limit.

cix_summary — project overview

Args: project. Returns languages, file/chunk/symbol totals, top directories, key symbols. A good first call when drilling into an unfamiliar repo.

cix_file — read an actual file (whole or a line range)

Args: project, file (required); optional start, end (1-based inclusive). Returns the file's real contents from the server's checkout. This is your primary way to read source here — Cowork has no local filesystem, so instead of stitching code together from cix_search snippets, pull the whole file (or a range) directly. External (GitHub-backed) projects only: for a local project the server holds no files and returns an error.

cix_tree — list a directory (one level)

Args: project; optional dir (omit for repo root). ls-like, no recursion — use it to navigate the file tree before reading a file. External projects only.

(There is no init / reindex / status / watch tool — indexing is server-side. If results seem stale or a repo is missing, ask the user to (re)index on the server host.)

Search quality — what scores mean

Default min_score 0.4 is calibrated for the production embedding model (path-aware preamble). Rough landscape:

Score	Meaning
0.65+	Exact / very strong match — almost certainly relevant
0.50–0.65	Strong match — usually relevant
0.40–0.50	Weaker match — sometimes useful
<0.40	Noise — filtered out by default

If a query returns nothing, lower the floor explicitly: min_score: 0.2 for very specific or long-tail queries. Don't go below 0.2 — that's noise.

Writing better queries — leverage path-aware embedding

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

• Generic: cix_search(project, "validation")
• Better — pins to the auth area: cix_search(project, "validation in auth middleware")
• Even better when you know the symbol: cix_search(project, "ValidateToken")

Queries that name the kind of thing and where it lives outperform single-word queries. Write what you'd ask a colleague — natural language, not regex.

Usage patterns

Exploring an unfamiliar repo (cix's strongest case): cix_summary(project) → cix_search(project, "main entry point server") → cix_search(project, "database connection setup") → cix_search(project, "request handler", in=["api"]).

Tracing a symbol end-to-end: cix_definitions(project, "HandleRequest") (where defined?) → cix_references(project, "HandleRequest") (who calls it?) → cix_search(project, "HandleRequest error handling") (how are errors handled?).

Narrowing scope: use in / exclude to focus, e.g. cix_search(project, "config", in=["cmd"], exclude=["legacy"]).

Tips

• Output groups by file: each result is a file with its matches inside, ordered by line number. The [best 0.NN] is the top hit's score in that file.
• cix_definitions is a faster path than cix_symbols when you already know the exact name.
• exclude complements in — drop noisy dirs (bench/, legacy/, vendored code) inline.
• Don't loop. If a query returns nothing useful after one well-phrased attempt plus one min_score: 0.2 retry, fall back to read/grep on a local repo.