Technical data sheet · measured, not declared
Zero-install, deterministic repo-indexing engine — one vendorable file, a library, a CLI, and 26 MCP tools.
Walks a repo, extracts symbols and imports across 15 languages,
resolves cross-file references into a typed link-graph, and
renders byte-identical artifacts every time it runs. Vendor the
single engine.mjs, install it from npm or Homebrew, or
run it from a container — nothing else to install, ever.
Install
npm i -g @maxgfr/codeindexbrew install maxgfr/tap/codeindexdocker run --rm -v "$PWD":/work \
ghcr.io/maxgfr/codeindex scan --repo /work
Same zero-dependency engine.mjs bundle behind all
three — CLI, library import, and Docker image.
Key numbers (JavaScript disabled — see full figures in
BENCHMARKS.md): a full typed cross-file graph built in seconds, with extraction
spread across worker threads; a warm rerun of
vercel/next.js in around a second, and roughly twice that
for one touched file; far fewer tokens than a raw grep dump for a
single-symbol lookup; 15 languages; 0 runtime dependencies;
byte-identical rebuilds on 7/7 measured repos; 26 MCP tools.
Fig. 01 — measured, reproducible
Measured against universal-ctags,
Serena (LSP over MCP) and Graphify
with a reproducible harness
(scripts/bench/) — median of 5 runs, one warmup
discarded. Every number on this page comes from the same
site/benchmarks.json committed to this repo; nothing
here is rounded or typed in by hand. Full methodology and every
scenario:
BENCHMARKS.md.
code-du-travail2,823 files, every tool measured on the same repo. Lower is faster.
No competitor here exposes an incremental reindex, so the baseline is the cold build of the same repo: what a rerun costs once the cache is warm, and what one touched file costs. Lower is faster.
One row per thing an agent-tooling team weighs. A filled tile marks the
leader on that axis — hover any cell for the measured number. Where a
rival wins it stays at the top of the table, unedited: ctags takes both
cold-index rows, because a flat tags pass is a smaller job
than a typed cross-file graph. Speed is the axis that matters least
here, and the file cap showed why — codeindex used to finish next.js
ahead of ctags by leaving 7,952 of its files out of the index, so every
lookup answered for a prefix of the repo and called it the repo. The
cap is gone: slower, and correct about the whole tree. The rows below
are the axes that time is spent on.
Full tables require JavaScript to render from the embedded dataset without retyping numbers by hand. See the same data as plain Markdown in BENCHMARKS.md or site/benchmarks.json.
Fig. 02 — capabilities
Everything below ships in the same zero-dependency bundle — no feature is an optional add-on package.
BM25 lexical ranking over symbol names, path segments and
headings. A term with zero document frequency falls back to a
byte-deterministic character-trigram match (Dice ≥ 0.6) — typo
tolerance with no embeddings. Disable with
--no-fuzzy.
An opt-in static token → vector lookup table — no
neural forward pass. Encode → mean-pool → L2-normalize →
round-half-to-even int8 quantize; ranking is a pure integer dot
product, byte-identical everywhere. No model on disk, no
behavior change.
Point at a containerized HTTP endpoint
(ghcr.io/maxgfr/codeindex-embed, all-MiniLM-L6-v2)
via CODEINDEX_EMBED_ENDPOINT. Wins over the static
tier by explicit intent; degrades to lexical on exit 0 if
unreachable — never a silent fallback to the wrong model.
Typed import / call / use
/ doc-link / mention edges at file and
module level. Per-symbol callers and references resolve in-proc
in sub-millisecond time on an already-loaded warm scan.
Louvain communities, PageRank & betweenness centrality, dead-code detection, complexity × churn hotspots, change coupling, surprise-edge detection, and a tests→code map — all derived from the same link-graph.
index.scip via a hand-rolled zero-dependency
protobuf encoder — validated against the official
scip CLI's stats/lint.
npm/yarn, pnpm, lerna, nx, cargo, go.work, maven, gradle, uv and Composer — detected and named without running any of their own tooling.
replace_symbol_body, insert_after_symbol, insert_before_symbol — precise edits addressed by
symbol name, not by line ranges that drift.
Render a mermaid dependency diagram or a plain-text repo map directly from the graph — no separate diagramming step.
Two cold builds of an unchanged repo produce identical
graph.json/symbols.json — confirmed on
7 of 7 measured repos this session. Graphify's graph.json
differed on 5 of the 6 measurable repos; determinism is a value we
hold across every repo, not just where it's easy.
Fig. 03 — usage
Five ways in — pick the one matching your integration.
Install it as a regular dependency and import the pure functions.
npm i @maxgfr/codeindeximport { scanRepo, ENGINE_VERSION } from "@maxgfr/codeindex";
const scan = scanRepo("/path/to/repo");Skills and CLI tools that don't want an npm dependency should still prefer vendoring — see the Vendoring tab.
The CLI ships in the same package as the library.
# or: brew install maxgfr/tap/codeindex
npm i -g @maxgfr/codeindex
codeindex index --repo . --out .codeindex
codeindex graph --repo . > graph.json
codeindex scip --repo . --out index.scip
codeindex callers --repo .
codeindex search "http client retry" --repo .
Serves the engine over stdio: 26 tools, including
scan_summary, graph,
symbols, find_symbol,
find_references, callers,
search, repo_map,
hotspots, coupling,
dead_code, complexity,
mermaid, grep,
replace_symbol_body,
insert_after_symbol,
insert_before_symbol, memory tools,
workspaces, churn,
check_rules and embed_status.
claude mcp add codeindex -- codeindex mcp{
"mcpServers": {
"codeindex": {
"command": "codeindex",
"args": ["mcp"]
}
}
}
Multi-arch (linux/amd64, linux/arm64) —
nothing inside but node and the bundle, no
npm install.
docker run --rm -v "$PWD":/work ghcr.io/maxgfr/codeindex scan --repo /work
docker run --rm -v "$PWD":/work ghcr.io/maxgfr/codeindex index --repo /work --out /work/.codeindex
docker run -i --rm -v "$PWD":/work ghcr.io/maxgfr/codeindex mcp
Pin by digest in CI or anywhere reproducibility matters:
ghcr.io/maxgfr/codeindex@sha256:…. The rich
semantic-search tier ships separately as
ghcr.io/maxgfr/codeindex-embed.
Consumers who don't want an npm dependency vendor
scripts/engine.mjs + engine.d.mts at a
pinned release tag instead — the model downstream consumer
tools use, so each stays a standalone, single-file install.
node scripts/sync-engine.mjs --ref v2.15.0Full steps and version-constant semantics: docs/MIGRATION.md.
Fig. 04 — what each tool is
The axis-by-axis scoreboard sits with the benchmarks, where its numbers come from. This is the shape of each tool: what it models, what it covers, what it costs to install.
| Tool | Model | Language coverage | Install | Worth knowing |
|---|---|---|---|---|
| codeindex |
Static byte-stable artifacts
(graph.json/symbols.json), rebuilt
each run with an incremental cache
|
15 (regex, always on) / 13 (tree-sitter AST, opt-in grammars) | npm i -g, brew, or docker — zero runtime deps | A single-file incremental reindex is slower than a live database (see Benchmarks) |
| universal-ctags | A flat tags file |
Broad, generic parser rules | Binary install | Fastest cold index on small repos, overtaken on the largest one measured — and definitions only: no call graph, no import resolution, no cross-file links |
| Serena | LSP client orchestrating per-language language servers | Any language with an LSP server | 114 MB venv + per-language language servers | Type-aware references no static tool claims — bought with the slowest activation and per-call latency measured here, and no on-disk artifact to reproduce |
| Graphify |
tree-sitter knowledge graph (graph.json);
code-only mode is keyless, the docs/PDF tier needs an LLM and is
excluded here
|
36 via tree-sitter | 140 MB Python venv (uv tool) |
~1 ms per lookup, but graph.json is not
byte-identical across rebuilds on 5 of the 6 measurable repos,
and file nodes are basename-keyed (no file-overview)
|