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.

Related MCP server: RepoMap

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

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