CoreMap

CLI that packs any repo into one AI-friendly file — or, with a task, keeps only the lines that matter and proves they were enough with a verification receipt.

Comment

Inspiration

Coding agents like Codex are powerful — but on a real repo they often read everything to fix one bug. That burns tokens, confuses the model, and still misses the decisive lines.

I wanted something simple: give the agent either one clean pack of the whole repo, or — when I know the task — only the exact spans that matter, with proof those lines were enough.

That’s CoreMap.

What it does

CoreMap is a CLI with two modes:

  1. Pack — npx @0xanand/coremap .
    Turns a repository into one AI-friendly file (coremap.md): directory tree + sources + summary. Secrets are excluded by path and content.

  2. Task — coremap . --task "fix the payment timeout"
    Ranks and selects exact file + line spans for that job, writes coremap-context.md + coremap-receipt.json, and with --verify can apply a patch and run tests.

On our pinned demo: 432 → 192 tokens, HitFile 1.00, tests PASS — a GREEN DELTA. It didn’t guess; it proved the small context was enough.

Try it

How we built it

Built end-to-end with OpenAI Codex (and GPT-5.6 in the Codex workflow) for OpenAI Build Week.

Stack: TypeScript, Node CLI (Commander), tree-sitter (WASM) for TS/JS symbols, js-tiktoken (o200k) for real token counts, vitest for tests.

Pipeline:

  • Walker — gitignore-aware walk + secret scan
  • Pack mode — tree + full files under a token budget
  • Task mode — parse task → candidates → rank → select exact spans → receipt
  • Verify — optional patch + tests (offline oracle or LLM)

AGENTS.md kept Codex on product rules: deterministic receipts, offline --no-llm, precision over recall, no secret leakage.

Shipped as a public npm package: @0xanand/coremap.

Challenges we ran into

  • Token honesty — early counts were guesses; we switched to real tiktoken so the receipt means something.
  • WASM under npm install — tree-sitter grammars break when node_modules is hoisted; fixed with require.resolve and tarball smoke tests.
  • CLI bin on scoped packages — npm 11 + scoped name quirks (coremap: not found / missing --version); hardened the bin entry and publish path.
  • Demo risk — task mode on a random repo can fail live; we pinned a tax-bug eval so GREEN DELTA is reproducible.

Accomplishments that we're proud of

  • A working, installable CLI on day one — not a slide deck.
  • Two clear modes: pack (easy on-ramp) and task + receipt (the wedge).
  • Reproducible GREEN DELTA with HitFile = 1.0 and tests PASS.
  • Secret-safe packs and deterministic receipts.
  • Public GitHub + npm + demo video judges can open in one click.

What we learned

  • Judges and agents both care about outcomes, not “another repo map.”
  • Precision beats recall for agent context — fewer decisive lines beat dumping neighbors.
  • Codex is fastest when the repo has a clear constitution (AGENTS.md) and a fixed demo command.
  • Shipping to npm early surfaces real install bugs that local tsx never shows.

What's next for CoreMap

  • Web UI — paste a public GitHub URL → shallow clone → same pack engine → tree + download (no install).
  • Task mode in the browser + clearer receipt UX.
  • Broader language support beyond TS/JS symbols.
  • Keep the CLI as the source of truth; web is just another front door.

Built With

Share this project:

Updates