repo-map

RepoMap generates a compact symbol overview for a repository or subtree. It uses tree-sitter tag queries to find definitions and references, then ranks files and symbols with PageRank over the reference graph. The implementation is vendored from Pete Davis' RepoMapper and keeps the Aider lineage for the .scm tag queries.

Reach for it before deep rg dives when you are entering unfamiliar C2+ code and need the project shape: important files, definitions, cross-file reference gravity, and the likely architectural center of a subtree.

rg and ast-grep boundaries

Use rg for text, filenames, comments, literal strings, and byte-level regex searches.

Use cxc-ast-grep for shape search and deterministic rewrites: function/call patterns, imports, syntax-aware migrations, and codemods.

Use this skill for an overview map, not for exact search. The map is a guide for where to inspect next, not proof that a symbol is absent.

When to use this skill

• "Give me a repo map of this package."
• "I am in unfamiliar code; show me the structure first."
• "What files define the main symbols in this subtree?"
• "Build an architecture map before changing this module."
• "와꾸 먼저 보자."

CLI usage

Preferred:

cxc map .
cxc map src/ --budget 2048

Direct script:

python3 plugins/codexclaw/skills/repo-map/scripts/repomap.py .
python3 plugins/codexclaw/skills/repo-map/scripts/repomap.py src/ --budget 2048

Useful flags:

Note: compiled-output dirs (dist, build, target, out, coverage) are skipped during directory expansion. If a repo's real sources live there, pass the path explicitly (e.g. cxc map dist/) to map it anyway.

--map-tokens N      # token budget; default 4096
--budget N          # alias for --map-tokens
--chat-files ...    # files currently in focus, ranked higher
--mentioned-idents  # symbols to boost
--verbose           # stderr summary: files, defs, refs

Dependencies

cxc map resolves its Python dependencies through a bootstrap ladder, so in most environments no manual install is needed:

1. CODEXCLAW_PYTHON env override — that interpreter is used verbatim.
2. uv on PATH — the script runs via uv run --with-requirements, and deps resolve into uv's own rebuildable cache automatically (first run pays a short resolve; later runs are warm).
3. An existing venv at $CODEXCLAW_HOME|~/.codexclaw/venvs/repomap — a user-level rebuildable derived cache (philosophy §2). Auto-created only when CODEXCLAW_MAP_BOOTSTRAP=1 is set (opt-in network install).
4. Bare python3 — works when deps are already installed; otherwise degrades to the install hint below.

Manual install (rung 4 environments):

python3 -m pip install -r plugins/codexclaw/skills/repo-map/scripts/requirements.txt

The CLI degrades cleanly when dependencies are missing. --help works with only system Python and always bypasses the ladder (dep-free help contract). A real map run without parser dependencies prints a single install hint and exits with code 3.

The pinned parser stack matters: tree-sitter-language-pack==0.9.0 and tree-sitter==0.25.1 are the verified working pair for this vendored parser API.

Cache

RepoMap stores derived tag cache data under:

.codexclaw/cache/repomap/tags.v1

Set CODEXCLAW_REPOMAP_CACHE to override the location. The cache is rebuildable derived data. It is wiped only by cxc reset --all.

Verification tiers

Locally fixture-verified: TypeScript/JavaScript, Python, and Rust.

Other languages inherit the vendored Aider-tested .scm tag queries on a best-effort basis. Treat those maps as orientation, then inspect the files they surface.

Notes

• On-demand skill (allow_implicit_invocation: false); reached by trigger or explicit use.
• Discoverability: a SessionStart hook (hooks/session-start-announcing-map-affordance.json, cxc-ops) announces this tool's existence once per session when the repo clears a source-file size gate. That is a POINTER only — the map body is never session-injected (on-demand stays the rule). This is the runtime companion to the dev §1.5 DEV-MAP-FIRST-01 routing, which is model-autonomous.
• Stateless one-shot CLI: no daemon, server, MCP process, background indexer, or workspace watcher.
• Lazygap 005 compliant: no dependency import or runtime setup is required for --help; heavy Python modules load only after argument parsing.