codemap

Auto-generated, budget-bounded codebase maps inside AGENTS.md — so coding agents stop re-exploring your repo at the start of every session.

Coding agents don't fail at finding code; they fail at knowing the shape of a system in the first minutes of a session. Codemap keeps a small (≤ 2,000-token) machine-generated map inside AGENTS.md — the context file agents already read — and keeps it provably fresh.

• Compass, not encyclopedia — three layers under a hard token budget: L0 annotated directory layout · L1 key files ranked by import graph · L2 public signatures.
• Freshness contract — deterministic output, check with CI-friendly exit codes, a pre-commit hook so the map travels in the same commit as the change, and an MCP server that refreshes the map at session start.
• Zero dependencies — single stdlib-only Python package (≥ 3.9), 40+ languages, local-only, no network, never fails on unknown file types.
• A format, not just a tool — the block layout and freshness rules are a spec (codemap-spec.md); any generator can implement it.

Install

pipx install codemap-agents      # PyPI (or: uv tool install codemap-agents)
pipx install git+https://github.com/xenitV1/codemap   # bleeding edge
# or, from a clone: python3 bin/codemap ... / pipx install .

The installed command is codemap in all cases.

Always-latest, npx-style (no install)

For MCP configs that should track the newest release automatically — the Python equivalent of npx some-server@latest:

uvx --from codemap-agents@latest codemap mcp --no-cache                             # PyPI
uvx --refresh --from git+https://github.com/xenitV1/codemap codemap mcp --no-cache  # git HEAD

Trade-off: the launcher checks for updates at every server start (a few seconds cold). Pin a version or use pipx install if session startup latency matters more than freshness.

Quickstart

cd your-project
codemap update        # writes the map block into ./AGENTS.md (creates skeleton if missing)
codemap check         # exit 0 fresh / 1 drift / 2 no map — wire this into CI
codemap install --ci  # pre-commit hook + GitHub Actions freshness gate

Everything between <!-- codemap:begin --> and <!-- codemap:end --> is machine-owned; everything outside is yours (architecture notes, conventions, warnings — the parts only humans can write).

Exclude vendored or irrelevant directories with gitignore-like globs in a repo-local .codemapignore (travels with the repo, CI sees it) or a user-global ~/.codemapignore (every repo on your machine).

Automatic mode (MCP)

codemap mcp is a stdio MCP server. Registered once at user scope, it starts automatically with every agent session, refreshes AGENTS.md for the project it opens in (git repos only), and exposes on-demand tools: codemap (return a fresh map without writing files), codemap_update, codemap_check.

# Claude Code
claude mcp add --scope user codemap -- codemap mcp --no-cache

# Codex CLI — ~/.codex/config.toml
[mcp_servers.codemap]
command = "codemap"
args = ["mcp", "--no-cache"]

# opencode — ~/.config/opencode/opencode.json
"mcp": { "codemap": { "enabled": true, "type": "local",
                      "command": ["codemap", "mcp", "--no-cache"] } }

Any other MCP client: stdio transport, command codemap mcp --no-cache.

Agent skill

codemap skill   # installs SKILL.md into ~/.agents/skills/codemap and ~/.claude/skills/codemap

Skill-aware agents (Claude Code, Codex, …) then know when and how to use the tool without extra prompting.

All commands

Command	What it does
codemap update	(Re)generate the map block in ./AGENTS.md
codemap check	Freshness: exit 0 fresh / 1 drift / 2 missing
codemap print	Write the block to stdout, touch nothing
codemap install [--ci]	Pre-commit hook (+ CI workflow) for this repo
codemap watch	Regenerate on every source change while you work
codemap mcp	MCP stdio server with session-start auto-refresh
codemap skill	Install the agent SKILL.md

Options: --root PATH · --file AGENTS.md · --budget 2000 · --no-cache · --quiet · --interval N · --include-ext .foo,.bar

How it works

A full tree walk every run (adds/deletes reflected by construction), regex import/symbol extraction per language, import-graph PageRank for L1 ranking, and budget-driven degradation (drop L2 first, then L1, then collapse L0). Output is deterministic — same tree, same bytes — which is what makes check and reviewable map diffs possible. An incremental content-hash cache makes warm runs fast and is semantically invisible.

Measured: ~130-file repo ≈ 0.2 s · ~900-file repo ≈ 0.4 s cold.

Tests

python3 -m unittest discover -s tests -v

License

MIT