ctx-optimize gives your coding agent a deterministic map of your codebase, so it answers where is X, who calls Y, what breaks if I change Z with cited file:line facts — in ~100ms, on any repo, in any shell, with nothing else installed. Fewer wrong turns, lower token bills, answers you can trust. One static Go binary. No LLM at query time, no database, no server.
npm install -g @muthuishere/ctx-optimize ctx-optimize install --skills # one-time: teach your agent (global) cd your-repo && ctx-optimize up # one verb: bootstrap, gather, or pull — then ask anything
One measured Claude Code session, the same questions on the same repo. Without a knowledge graph the agent greps, reads, and opens the wrong file again — more turns, more tokens, more dollars. With the store it asks and gets cited answers instead. The numbers on screen are from one real kill-test run and change with every question, repo, and model — but the savings hold up.
Narrated · one measured session · ~⅓ lower cost, ~¼ fewer turns — actual numbers vary by question & repo
npm install -g @muthuishere/ctx-optimize # one static binary per platform, no postinstall downloads ctx-optimize install --skills # one-time: teach your coding agent to answer from the store cd your-repo && ctx-optimize up # bare repo → bootstraps config + gathers (about a second); # monorepo → scan-bootstraps one store per module + a navigator; # clone with a shared store declared → pulls it; stale → refresh
Want control instead of up's defaults — review a monorepo's module list before gathering, pick pointer targets? That's init:
ctx-optimize scan # lists every project it found (read-only) ctx-optimize init --scan --yes && ctx-optimize add . # curate config.json, then gather explicitly
Source and tests in separate folders (the .NET / Gradle case)? Declare one module across both — they share a graph, and test→source calls resolve across the split:
# .ctxoptimize/config.json "modules": [{ "name": "Billing", "paths": ["src/Billing", "tests/Billing.Tests"] }]
A teammate cloning your repo runs the same one command — ctx-optimize up — which does whatever the state needs: pulls the team's prebuilt store when the committed config declares a pull, gathers locally otherwise, fast-refreshes a stale store, no-ops on a fresh one. Idempotent — run it whenever.
macOS / Linux / Windows · works with Claude Code, Codex, Copilot & Devin · framework routes, build-tool dependencies, k8s topology, subsystems, multi-path modules & a first-class dashboard · scripted sharing, one-verb onboarding & change-plan · source on GitHub.
The installed skill makes your agent query the store before it greps. Markdown docs are gathered natively. Your Postgres schema arrives via a drop-in adapter script — tables become nodes, foreign keys become edges. Anything else goes through the validated JSON door. Then one question cites the table, the code, and the doc together:
Unedited recording · a repo with .ctxoptimize/adapters/postgres-schema.py against a live Postgres
Apple M5 Pro · 2026-07-11 · methodology and every corpus below · raw results.json
Grep. Open the file. Wrong one. Grep again. Open three more files just to see one signature. Every hop is tokens, latency, and context that's gone for the rest of the session.
> grep -rn "Merge" . — 214 matches > read store.go — 9.4k tokens > read store_test.go — 11k tokens > read app.go — 14k tokens … and the window is half gone
One query. Complete, citable hits — id, kind, file, line range, signature, doc, callers, callees — under a hard token budget. The agent reads a file only when it truly must.
> ctx-optimize card "Store.Merge" — 96ms sig: func (s *Store) Merge(b *schema.Batch) … doc: Merge upserts a validated batch … called by (12): cmdAdd, cmdMerge, … calls (6): Batch.Validate, writeNDJSON, …
Signature, doc comment, location, callers, callees — in one shot, from the graph. This is the read your agent no longer makes. About to edit? change-plan X goes further: one composed answer with the signature, the callers, the blast radius, and which tests to run — measured ~90% fewer answer tokens than the query+card+affected chain it replaces.
Unedited recording · ctx-optimize card "Store.Merge" on this project's own source
Tree-sitter grammars compiled to WASM, hosted by wazero, fanned across every core. 12 languages embedded in one static binary; any other language is a one-command grammar pack. Re-gather after a change in under a second.
Every edge carries confidence: EXTRACTED is parsed fact, INFERRED is name-matched. Ambiguous calls are dropped, never guessed. The benchmarks on this page show where the other tool wins, too.
Same input, same graph, byte for byte — git-diffable NDJSON, a markdown wiki regenerated on every add, atomic writes. The binary never calls a model. Your agent supplies the intelligence; the store supplies precise recall.
add . — parse, graph, prune stale nodes, rebuild the wiki
ask — deterministic retrieval under a token budget
affected walks reverse dependencies; path connects symbols
12 embedded · languages add <name-or-url> for the rest
A readable map of the repo, regenerated on every add
Head-to-head vs graphify — the one rival we've run the full measured harness against. Measured 2026-07-11 · Apple M5 Pro (18 cores, 48 GB) · graphify 0.9.12 vs a ctx-optimize dev build · raw data. How we stack up against CodeGraph, GitNexus, potpie & Serena — on architecture, setup, and their own published numbers — is on the comparison.
cold gather — full extraction, bars scaled per corpus
nodes 11,056 vs 10,996 — within 1% · store 8.3 MB vs 30.1 MB — 3.6× smaller
nodes 1,978 vs 1,473 — we also graph docs & import modules · store 1.3 MB vs 4.2 MB
nodes 1,922 vs 1,975 — graphify finds more here, shown as-is · store 1.4 MB vs 6.2 MB
nodes 572 vs 599 — graphify finds more here too · store 0.4 MB vs 2.2 MB
query latency — 12k-file corpus, median of 5 runs, 2,000-token budget
| corpus | files | ctx cold | graphify cold | ctx nodes | graphify nodes | ctx size | graphify size |
|---|---|---|---|---|---|---|---|
| graphify's own source | 12,484 | 0.67s | 8.88s | 11,056 | 10,996 | 8.3 MB | 30.1 MB |
| flask | 265 | 0.79s | 1.06s | 1,978 | 1,473 | 1.3 MB | 4.2 MB |
| gin | 159 | 0.41s | 0.90s | 1,922 | 1,975 | 1.4 MB | 6.2 MB |
| ctx-optimize source | 75 | 0.37s | 0.51s | 572 | 599 | 0.4 MB | 2.2 MB |
| query "how does clustering work" | — | 89 ms | 367 ms | — | — | — | — |
| query "remote push pull hooks" | — | 96 ms | 364 ms | — | — | — | — |
| query "community labeling" | — | 96 ms | 370 ms | — | — | — | — |
update --no-cluster: extraction only, no clustering, no LLM). ctx-optimize was timed on add, which does more work per run: extraction, graph build, stale-node pruning, and full wiki regeneration. Query latency is the median of 5 runs, same question, same 2,000-token budget, both CLIs invoked cold from the shell. Node counts are shown for scale, not equivalence — the tools disagree about what counts as a node (ctx-optimize graphs import modules and markdown documents as first-class nodes; graphify includes some file types we skip), which is why ctx-optimize shows ~34% more nodes on flask while the 12k-file totals land within 1%. On gin and on its own source graphify finds slightly more nodes and edges than we do, and we show that as-is. graphify also does things ctx-optimize deliberately does not: LLM-assisted community labeling and semantic clustering. If you want those, use graphify — the comparison here is the deterministic core both tools share.Before launch we pre-committed a kill bar: if the store can't beat a plain grep-and-read agent by 25% on hostile terrain, stop. Then we ran it — 12 Linux-kernel questions, answered twice by the same agent (grep-and-read vs store-first — a real agent always reads, never just greps), every answer judged against source-derived ground truth before tokens counted. Measured 2026-07-12 · full write-up · questions + keys (raw json) · raw runs ship in the repo's proof/.
graphify-out/ dump; ours is extensible by design — drop-in adapters, grammar packs, skills installed by default. We threw the strawman out and tested against a real grep-and-read agent. A smaller honest number beats a big fake one.
Tokens & cost: natural usage on Claude Code — plain questions, real dollars, no store vs store. Query latency: 12k-file benchmark. Honest caveat: total session wall runs +31% today (the store trades wall-time for tokens and dollars — more tool calls); we just cut query latency 40% and that gap is closing.
gorilla/mux:
See the full table, the harness, and how to run it yourself →
the result that clears the bar — natural usage, plain questions, real dollars billed
the fix: cards now carry the function body head (first ~30 lines) — the follow-up read they used to force is gone · turns 70→53 (−24%) · 56 unprompted store calls · before the fix the same harness measured +6% worse (published, below) · quality spot-verified: the $0.05 answers are complete and correct
"Cuts raw input+output tokens on a cached frontier agent" — dead. Claude Code and Codex grep well, and prompt caching absorbs every extra hop, so on that one narrow metric the store is parity on locate/mechanism questions. We don't claim otherwise anywhere on this page. But raw tokens aren't the bill →
The real bill is cheaper. Cache reads still bill (~10%), and fewer steps means fewer of them — so on each harness's own dollar report the store wins every Claude tier: −9% to −16%. Plus onboarding −34% to −49% tokens, correctness (grep arms of Codex and Devin named the wrong gatekeeper; the store arms didn't), and −13% to −29% steps everywhere.
fresh tokens per tier — where even a hand-tuned grep baseline shows parity (the adversarial version of the test)
steps ~flat · wall −14% (347→298s) · quality 12/12 vs 11.5/12 — the best grep agent on earth doesn't need us for tokens
steps −13% · wall +3% (386→397s) · quality 11.5/12 vs 12/12 — the store arm was the only one to catch a comment posing as a real caller
steps −29% · wall +9% (641→698s) · quality 11/12 vs 11/12 — a third fewer hops, but caching makes hops free
steps ~flat · wall ±0% (683→680s) · quality 11.5/12 vs 11.5/12 — its grep arm named the wrong gatekeeper; the store arm didn't
steps −24% · wall −34% (294→195s) · quality 5/6 vs 6/6 · no prompt caching — every step re-pays full context, so saved steps become saved money · daily quota cut the run at 6 pairs
| harness · model | corpus | tokens, grep→store | steps | wall time | answer quality (grep vs store) |
|---|---|---|---|---|---|
| Claude Code · default | linux/block · 98 files | 370,398 → 369,673 (±0%) | ~flat | 347→298s (−14%) | 12/12 vs 11.5/12 |
| Claude Code · Sonnet | linux slice · 3,987 files | 370,308 → 389,647 (+5%) | 89→77 (−13%) | 386→397s (+3%) | 11.5/12 vs 12/12 |
| Claude Code · Haiku | linux slice · 3,987 files | 286,943 → 283,669 (−1%) | 174→124 (−29%) | 641→698s (+9%) | 11/12 vs 11/12 |
| Codex CLI · default | linux/block · 98 files | 385,794 → 397,323 (+3%) | ~flat | 683→680s (±0%) | 11.5/12 vs 11.5/12 |
| Devin CLI · SWE-1.6 | linux/block · 98 files (n=6) | 4,004,232 → 2,300,736 (−42%) | −24% | 294→195s (−34%) | 5/6 vs 6/6 |
Same prebuilt store (linux kernel, ~274k nodes), same 8 block-layer questions, one fresh agent session per model — answers graded against withheld golden keys the product already pins in CI. Measured 2026-07-17 · questions, keys & raw transcripts.
| model · harness | score /80 | avg s/question | tool calls (8 q) | notes |
|---|---|---|---|---|
| Fable 5 · Claude Code | 80 | 24.6 | 23 | every key + full mechanism chains |
| Sonnet 5 · Claude Code | 80 | 17.5 | 25 | every key; fastest frontier-quality run |
| Opus 4.8 · Claude Code | 79 | 19.0 | 22 | one canonical symbol described but not named |
| Haiku 4.5 · Claude Code | 72 | 13.6 | 18 | 90% of frontier quality at half the wall time |
| gpt-4o-mini · toolnexus, one-shot | 54 | 9.4 | 24 | $0.015 for all 8 — protocol pinned from the committed .ctxoptimize/instructions.md card |
.ctxoptimize/instructions.md. With it, a $0.15/M-token model reaches ~70% of frontier quality at ~1/100th the cost. One-shot per question beats a continuous conversation: same score, 7× cheaper, no cross-question bleed.
.ctxoptimize/ per repo: config + drop-in adapter scripts~/ctxoptimize/<repo>/ — multi-module, git-diffable NDJSONremote push/pull run commands you declare in the committed config (a git repo, any bucket, anything); secrets stay env-var namesThe lane has graph-DB tools (CodeGraph on SQLite, GitNexus on an embedded DB, potpie on Neo4j), a Python central-store (graphify), and a live language-server (Serena). We're the one that's a single static binary you extend — here's what that changes versus the whole field.
npm i -g and it runs, offline.The full board — where every rival wins and where we lose, with numbers — is on the honest comparison.
npm install -g @muthuishere/ctx-optimize ctx-optimize install --skills # one-time: teaches your coding agent to use the store cd your-repo && ctx-optimize up
Every command and every config key — repo config, machine-global config, monorepos, remotes, adapters, route/manifest/grammar packs — on one page: the docs. See where we stand against the field, honestly: the comparison.