code-context AGENTS.md

code-context: notes for AI agents

Read CONTRIBUTING.md first for prerequisites, the build, test commands, and the PR workflow. This file covers what isn't there: what the project is, the repo map, and the boundaries that aren't obvious from the code.

Project overview

code-context is local code search for AI coding agents: a CLI (cx) and an MCP server over a ranked index that lives in plain files inside the repo. It fuses keyword (BM25) and semantic (vector) search into one ranked pass and exposes read-only SQL over the index, so an agent answers questions about a codebase without crawling files into the context window. The index is built and queried in-process with a local embedding model: no accounts, no API keys, no server. It is built on the infino engine, which runs SQL, full-text, and vector search over one copy of the data.

The user-facing surface, quick start, and configuration live in README.md; the measured results in docs/benchmark.md; the honest limits in docs/tradeoffs.md.

Repo map

• src/cli.ts: the cx / code-context command entry (commander).
• src/mcp/server.ts: the MCP server, three tools (search, sql, reindex). Each takes an optional path (repo root) so one server serves multiple repos in a session, defaulting to the startup root.
• src/mcp/repos.ts: the per-repo registry - resolves and validates a requested root, one engine connection per repo, LRU-capped.
• src/mcp/ensure.ts: auto-index on first query - a search/sql on a never-indexed repo builds the index inline, then answers on the same call (CX_AUTO_INDEX=0 restores the strict "index it first" error).
• src/core/: the engine-facing core. chunker (tree-sitter chunking), indexer (build + staged readiness + incremental sync), searcher (hybrid search + SQL), embedder (local model), filestate (incremental sync state), walker, manifest, config, context, output.
• src/commands/: CLI command implementations (index-cmd, query-cmds).
• test/: vitest suites. bench/: the benchmark harness. docs/: docs.