code-map

code-map

🇰🇷 한국어로 읽으시려면 → README.ko.md  ·  🇬🇧 English below.

Hand your AI agent the exact slice of code it needs — by coordinate, not by guessing. 좌표만 정밀하게. 의미는 LLM이 raw를 보고 매번 새로 판정한다.

---

Sound familiar? 😅

Your agent needs to read createMessage. So it greps — and gets 40 hits across providers. It opens whole files to find the right one, burning tokens on code it won't use. Next turn it "remembers" the function was at line 120 — but your last edit pushed it to 138, so it reads the wrong lines and never notices. 😱

With code-map riding along, the agent just:

read({ refs: ["anthropic.ts#createMessage", "openai.ts#createMessage"] }) → both exact slices, one call, still correct even after the file moved.

grep still does the finding — it's great at that. code-map does the reading: small, exact, drift-proof. That's the whole idea.

---

What you get — measured, not promised

🎯 Never silently wrong	After heavy edits with no re-index, read re-anchors on the signature line: 0 silently-wrong bytes (a naive "line number" cache is ~100% wrong). It returns the right code or tells you it can't — never the wrong bytes.
⚡ Fewer tokens, fewer steps	Wired into a coding agent (codex, 150-task pass@30): −19% tokens, −67% shell commands, same success rate. On known-ref reads the cut is much larger — grok composer-2.5-fast, 30 passes: −53…−60% tokens, −71…−78% retrieval payload; codex with the routing skill: −34…−54%.
🧭 Routing is the lever	Agents won't reach for read on their own (~17%). The bundled plugin/skill makes them: it flips discovery from a loss to −31% by killing the double-call, and turns vague usage (erratic, +61% worse on one task) into a steady win — 30/30 pass.
🧩 Tiny & drop-in	Node + one dependency (oxc-parser), no build step. TS/JS and Python. MCP server + a one-line skill — install for Claude, Codex, grok, or Antigravity.

Honest about the edges (this repo's whole point): code-map does not beat grep at searching — it ties, so keep grepping. And it's not a universal token-saver — the win is large for reading known symbols with routing, ~0 on an already-lean read task, and a loss on raw discovery unless the skill routes it. Every number, every retraction, the model/metric caveats, and a one-command verifier: code-map-bench.

TL;DR — grep finds, read reads.

---

Quick start

# 1. install (until npm publish, straight from GitHub)
npm install -g github:annyeong844/map        # gives you `map` + `map-mcp`

# 2. index the repo you want your agent to read
cd /path/to/your-repo && map index --root .  # writes ./.map-index.json

# 3. wire it into your agent (examples)
codex mcp add code-map -- map-mcp             # Codex
claude mcp add code-map --scope user -- map-mcp   # Claude Code

That's it — your agent now has one tool, read. For the −19% / −67% efficiency win on Codex you also tell it when to use code-map (one line); see Wiring it for real below. The MCP server auto-detects the index (walks up for .map-index.json) and auto-reloads when you re-index — no reconnect.

---

Who is this for?

✅ Great fit if you

• run an AI coding agent (Codex, Claude Code, …) that reads a lot of code
• have a repo big enough that grep returns noise and reads pull whole files
• work in TypeScript / JavaScript or Python
• want reads that stay correct as the code changes under the agent

❌ Not the tool (yet) if you

• want a better search — grep/ripgrep already ties it; code-map is for reading
• have a 1–2 file project — the read savings won't show up
• want "where is auth handled?" concept search — that's embeddings (a measured non-goal here)

---

The one tool: read

map read "alias-map.ts#buildAliasMap"        # path-scoped name → exact slice
map read buildAliasMap                       # bare name (errors if ambiguous)
map read withRetry --snippet "req.copy()"    # char range *inside* the symbol
map read --refs "getModel,createMessage,withRetry"   # batch: many symbols, one call
map stats                                    # index overview

Add --json for machine output. Search with your own grep — feed the file:line or symbol name you find to read. As an MCP tool it's the same read (single ref, a refs array for batch, optional snippet).

---

🧪 The honest scorecard — what we kept, and what the data made us cut