Your AI agent can read the code.
Codemaps tells it what matters.
A local-first context layer that maps your repo's architecture, dependencies, risks, and invariants — and feeds them to Claude Code, Cursor, and Copilot over MCP. So agents stop handing you code that's almost right — and change it like someone who's worked here for years, not someone who just cloned it.
“Almost right, but not quite” is developers' #1 frustration with AI code (45%), and 66% say they lose time fixing it (Stack Overflow, 2025). That re-check-and-re-fix loop is the verification tax. Codemaps exists to shrink it.
🧭 Understand the system🎯 Change with confidence🛡️ Guard what must stay true
$ npm i -g @codemaps/cli # open source, Apache-2.0 $ codemaps init # any git repo — nothing leaves your machine ✓ risk 1,204 files from 6,153 commits (hotspots, bus-factor, coverage) ✓ guardrails 3 do-not-touch zones, 14 invariants — with consequences ✓ contracts 213 published endpoints, 9 consumed ✓ AGENTS.md generated · MCP server ready · PR check available
14 seconds on a 285-file TypeScript repo, cold. (Measured 2026-07-28 on honojs/hono via npx, 2.7k-commit history; flask took 2s.)
The invariant nobody wrote down is why AI code comes back almost right. The edit compiles, the tests pass — and it quietly violates a rule only the team knew. So instead of claiming numbers, here are two real answers from a live repo — word for word, exactly what your AI assistant reads before it touches code.
This one line of code stops strangers from reading private files off the server. To an AI “cleaning up,” it looks like clutter — in our benchmark, an agent deleted it and rewrote the test that would have caught it. This is the warning Codemaps staples to it:
A code graph would show your agent that this line exists. Codemaps tells it why it's load-bearing — the rule and the reason — before the edit.
The other half of the job is the Jenga check: before you pull a block, know exactly which pieces are resting on it — and which tests will tell you if the tower wobbles:
Same question, org-wide, in the cloud: “the endpoint you're about to change is used by 3 other teams' services.”
Six lenses — understand it, then protect it
Half of this is about not breaking things. The other half is just answering “how does this system actually work” — for a new hire or an agent starting cold. Every lens is callable by your agent over MCP, and readable by you.
🧭 Know the system
Components, entry points, how services talk to each other — the mental model a new hire builds after a week, on day one instead.
📍 Know where to look
Point at a concept in plain language, get back ranked files and symbols — plus every prior change that touched them.
🎯 Know what depends on it
Direct and transitive dependents, affected tests, published contracts it touches — in-repo locally, across services in the cloud.
🛡️ Know what must stay true
Invariants and do-not-touch zones your agent can't see — with the consequence of breaking them. Advisory until a human confirms; enforced after.
🔥 Know what's fragile — and who to ask
Hotspots, weak coverage, single-owner code, and the owner behind it — the “slow down here” a senior dev feels instinctively, derived from your git history.
🔒 Know the attack surface
Trust boundaries, taint paths, auth gates, secrets — the security-critical surface, mapped before an agent ever touches it.
How the loop actually works
Two ways it reaches your agent: it pulls what it needs on demand, and gets a nudge at the moment it edits. No prompt bloat, no black box.
codemaps init builds a code graph, a risk map from your git history, and mined guardrails into .codemaps/. Source never leaves the machine.
codemaps serve exposes six lenses. Your agent calls them on demand, query-scoped — context arrives when it's relevant, not stuffed into every prompt. Each answer carries provenance + a confidence score.
A PreToolUse hook fires the instant your agent touches a file; a SessionStart hook drops a hotspot orientation. This is where “advisory until confirmed” gets concrete ↓
So enforcement is earned, not default. Everything Codemaps mines ships as advisory; only a human promotes an advisory to a block.
Languages — support is per-lens, not all-or-nothing: Risk works on any git repo, any language — it's mined from history, not parsed. Guardrail mining covers TS/JS, Python, Go, Ruby, Java, Rust, and C#. Contract detection speaks Express-style routers, NestJS, Next.js, FastAPI/Flask — plus proto, GraphQL, and OpenAPI, which are language-neutral. The deep code graph (impact/locate) runs on TypeScript/JavaScript, Python, Go, Java, Kotlin, and Ruby today. More languages are grammar work, not architecture — and detectors are the easiest open-source contribution we take.
Does it reduce almost-right edits?
That's the question we hold ourselves to. We keep an adversarial trap harness (bench/) that asks an agent to make edits it shouldn't — plausible-looking changes that quietly break an invariant. One task tells it to loosen the exact res.sendFile guard above.
6 tasks × 3 arms × n=3, one pinned model: a tie with a free commodity-graph tool, 6/6 vs 6/6. One apparent edge: our mined security invariant kept a path-traversal guard intact 3/3 where both alternatives went 0/3.
A tie again — 4/6 for all three arms — and the v1 edge did not replicate: the alternatives went 0/3 → 2/3 on identical prompts, our miner produced no invariant for any of the three new traps, and the one differential result in the matrix ran against us.
So here is what we claim after running our own benchmark, twice, and publishing both: nothing measured — we do not claim the local lenses make agents safer than free alternatives. They're honest, useful context with their confidence labeled. The open question the matrices structurally could not test — because every arm is single-repo — is the cross-repo layer: “changing this endpoint breaks 3 consumers in 2 other repos.” That's the bet we're testing with design partners now. Both matrices, the raw scoring, our scorer's own bugs, and every withdrawn claim live in bench/. We publish the losses; price our other claims accordingly.
To be precise about what does what: the advisory context above is what reduces almost-right edits, and it's the default everywhere. Blocking — hard-denying an edit to a human-confirmed do-not-touch zone — is the governance layer for teams: opt-in, earned per zone, and the basis for org-wide enforcement policies in the enterprise tier.
How teams run it
codemaps init in any repo. Six lenses over MCP, agent hooks that warn on risky edits, a PR check. Telemetry-free; your source never leaves.
Install the GitHub App: every push auto-indexes contract surfaces into your org's append-only history. Source is processed in-memory and discarded — only the surfaces are stored. Prefer zero source contact? Push surfaces from your own CI with codemaps push.
Codemaps stitches repos into a live service graph: “changing this endpoint breaks 3 consumers in 2 other repos” — before you ship it.
A code graph tells your agent what connects. Codemaps tells it what matters — and what not to touch.
Free while in beta. Sign in with just an email — no card, no sales call.