CoreMap

Pack your repository into one AI-friendly file — or pass a task and keep only the lines that matter.

npx @0xanand/coremap .

Writes coremap.md: directory tree, source files, and a short summary. Secrets are excluded.

Two modes

| Mode | Command | Output | |------|---------|--------| | Pack | coremap . | Full repo → one file (coremap.md) | | Task | coremap . --task "fix …" | Exact spans → coremap-context.md + coremap-receipt.json |

Pack is the everyday path. Task mode selects a small evidence set and can verify it by applying a patch and running your tests.

Install

No install (recommended):

npx @0xanand/coremap .

Global:

npm install -g @0xanand/coremap
coremap .

Requires Node.js 20+.

Usage

Pack mode

coremap .                          # → coremap.md
coremap . --out-file context.md    # custom name
coremap . --max-tokens 200000      # raise whole-file budget
coremap . --out-dir ./out          # write elsewhere

Task mode

coremap . --task "fix the tax bug" --budget-lines 25

# Optional: prove the context was enough
coremap . --task "fix the tax bug" --verify
coremap . --task "…" --verify --no-llm   # offline (no API key)

Pinned demo (included in this repo):

npm run demo

Example output:

                          Full  Compress   CoreMap
--------------------  --------  --------  --------
Context tokens             432        81       192
HitFile                      —         —      1.00
HitRegion≈                   —         —      0.71
Patch produced              no        no       yes
Tests (original repo)        no        no       yes

coremap: GREEN DELTA  tokens 432→192  |  HitFile=1.00  |  HitRegion≈0.71  |  tests=PASS

Tests (original repo) is the same baseline for the Full and Compress columns; CoreMap applies the demo oracle patch only in an isolated temporary copy.

Features

• One command — pack a repo in seconds
• Git-aware — respects .gitignore and optional .coremapignore
• Secret-safe — path + content filters (keys, tokens, PEMs, etc.)
• Real token counts — js-tiktoken o200k_base
• Exact spans — path + line ranges with real source (task mode)
• Verification receipt — optional patch + tests (--verify)
• Works offline — pack and selection need no API key

CLI reference

Usage: coremap [options] [path]

Arguments:
  path                        repository path (default: ".")

Options:
  --task <text>               issue / change request (enables task mode)
  --budget-lines <n>          max source lines in the context pack (default: 200)
  --verify                    run one patch attempt + tests
  --no-llm                    offline selection; skip LLM patch
  --ground-truth <patch>      unified diff for HitFile / HitRegion scoring only
  --max-tokens <n>            pack mode whole-file token budget (default: 50000)
  --out-file <name>           pack mode output filename (default: coremap.md)
  --out-dir <dir>             output directory (default: .)
  -V, --version               output version number
  -h, --help                  display help

| Flag | Mode | Notes | |------|------|--------| | --task | task | Turns on span selection + receipt | | --budget-lines | task | Hard line budget for selected source | | --verify | task | Patch attempt + test run | | --no-llm | task | Never call OpenAI; use oracle if --ground-truth is set | | --ground-truth | task | Eval only — never used as selection input | | --max-tokens | pack | Skip huge files once the budget is hit | | --out-file / --out-dir | both | Control where artifacts land |

How it works

Pack: walk the tree (gitignore-aware) → filter secrets → emit tree + files + summary with token counts.

Task: parse the task → gather candidates (terms, symbols, imports, tests) → rank → select exact spans under the line budget → write pack + receipt → optionally verify.

Project layout

src/
  cli.ts              # CLI entry
  index.ts            # library exports
  coremap/            # pack, select, receipt, verify, …
bin/coremap           # npm bin wrapper (optional; published bin is dist/cli.js)
fixtures/             # mini-repo + tax-bug eval fixture
evals/tax-bug/        # issue text + ground-truth patch
specs/coremap/        # product spec / plan / tasks
tests/                # vitest

Development

git clone https://github.com/Anand-0037/coremap.git
cd coremap
npm install
npm test          # 22 tests
npm run build
npm run lint
npm run pack      # dogfood: pack this repo → repomap.txt
npm run demo      # GREEN DELTA on the pinned eval

Scripts

| Script | Purpose | |--------|---------| | npm test | Run vitest | | npm run build | Compile TypeScript → dist/ | | npm run coremap | Run CLI via tsx | | npm run pack | Full pack of this repo | | npm run demo | Pinned task + verify demo |

Ignore rules

CoreMap respects .gitignore. Add a .coremapignore (gitignore syntax) for extra exclusions.

Security

• Path patterns: .env*, keys, PEMs, credential filenames, and similar
• Content scan: private-key headers, sk-…, AKIA…, high-entropy secret-like assignments
• Matched files are skipped; secret contents are never written into the pack

Report security issues via GitHub Issues (or privately if you prefer).

Contributing

1. Fork and create a branch
2. Keep changes small and typed (strict TypeScript)
3. Add or update a vitest for behavior you change
4. Run npm test && npm run build before opening a PR

Bug reports and PRs are welcome.

License

MIT

Built for the OpenAI Codex Build Week hackathon (Delhi NCR). See CODEX.md. Agent rules: AGENTS.md.