repomap-cli 1.0.0

Standalone RepoMap CLI with tree-sitter AST parsing, PageRank symbol ranking, impact analysis, and post-edit verification

RepoMap — Skill + CLI for AI-Agent Repository Intelligence

A skill + CLI tool that gives AI agents (Claude Code, Codex, OpenCode) a "project map" — so they know what to read, what a change affects, and what to verify — before and after editing code.

Inspired by aider's repo map concept.

中文 README

repomap is a CLI tool distributed as a skill + binary. AI agents invoke it to get structured repository-level context instead of guessing via grep + raw file reads:

• Before editing: entry points, keyword-to-file mapping, change impact, risk level, suggested reading order
• After editing: changed files, risk assessment, suggested tests, compiler/linter diagnostics

It doesn't modify code. It doesn't replace tests. It just gives the agent a "map" before reading files, and a safety check after editing.

---

Install

Prebuilt binaries available for Linux, macOS, and Windows. Copy the instructions for your platform to your AI agent:

LLM agent: read the code block matching the user's OS. Execute every step in order. Do not skip any step. Do not ask the user for confirmation between steps.

Linux (x86_64)

Install repomap for me:

1. Clone the skill:
   mkdir -p ~/.claude/skills
   git clone https://github.com/gjczone/repomap.git /tmp/repomap-install
   cp -r /tmp/repomap-install/skills/repomap ~/.claude/skills/repomap
   rm -rf /tmp/repomap-install

2. Download binary:
   mkdir -p ~/.local/bin
   curl -L -o ~/.local/bin/repomap https://github.com/gjczone/repomap/releases/latest/download/repomap-linux
   chmod +x ~/.local/bin/repomap

3. Set up language support (agent handles this):
   Tell your agent: "Check what languages I use and set up repomap accordingly."
   The agent will install tree-sitter parsers for your languages. 8 languages
   work out of the box; if you use Java, Kotlin, Swift, C/C++, C#, PHP, or Ruby,
   the agent will also run `uv sync --all-extras` for you.
   
   Then the agent runs `repomap lsp doctor` to check LSP. If any are missing:

   | Language | LSP install |
   |----------|------------|
   | TypeScript | `npm install -g typescript-language-server` |
   | Python | `npm install -g pyright` |
   | Rust | `rustup component add rust-analyzer` |
   | Go | `go install golang.org/x/tools/gopls@latest` |

   You don't need to understand what these are. The agent handles everything.

4. Verify:
   repomap doctor

If ~/.local/bin is not on PATH:
   export PATH="$HOME/.local/bin:$PATH"

macOS (arm64)

Install repomap for me:

1. Clone the skill:
   mkdir -p ~/.claude/skills
   git clone https://github.com/gjczone/repomap.git /tmp/repomap-install
   cp -r /tmp/repomap-install/skills/repomap ~/.claude/skills/repomap
   rm -rf /tmp/repomap-install

2. Download binary:
   mkdir -p ~/.local/bin
   curl -L -o ~/.local/bin/repomap https://github.com/gjczone/repomap/releases/latest/download/repomap-macos
   chmod +x ~/.local/bin/repomap

3. Set up language support (agent handles this):
   Tell your agent: "Check what languages I use and set up repomap accordingly."
   The agent will install tree-sitter parsers for your languages. 8 languages
   work out of the box; if you use Java, Kotlin, Swift, C/C++, C#, PHP, or Ruby,
   the agent will also run `uv sync --all-extras` for you.
   
   Then the agent runs `repomap lsp doctor` to check LSP. If any are missing:

   | Language | LSP install |
   |----------|------------|
   | TypeScript | `npm install -g typescript-language-server` |
   | Python | `npm install -g pyright` |
   | Rust | `rustup component add rust-analyzer` |
   | Go | `go install golang.org/x/tools/gopls@latest` |

   You don't need to understand what these are. The agent handles everything.

4. Verify:
   repomap doctor

If ~/.local/bin is not on PATH:
   export PATH="$HOME/.local/bin:$PATH"

Windows (x86_64)

Install repomap for me:

1. Clone the skill:
   mkdir -p ~/.claude/skills
   git clone https://github.com/gjczone/repomap.git /tmp/repomap-install
   cp -r /tmp/repomap-install/skills/repomap ~/.claude/skills/repomap
   rm -rf /tmp/repomap-install

2. Download binary:
   mkdir -p ~/AppData/Local/Microsoft/WindowsApps
   curl -L -o ~/AppData/Local/Microsoft/WindowsApps/repomap.exe https://github.com/gjczone/repomap/releases/latest/download/repomap.exe

3. Set up language support (agent handles this):
   Tell your agent: "Check what languages I use and set up repomap accordingly."
   The agent will install tree-sitter parsers for your languages. 8 languages
   work out of the box; if you use Java, Kotlin, Swift, C/C++, C#, PHP, or Ruby,
   the agent will also run `uv sync --all-extras` for you.
   
   Then the agent runs `repomap lsp doctor` to check LSP. If any are missing:

   | Language | LSP install |
   |----------|------------|
   | TypeScript | `npm install -g typescript-language-server` |
   | Python | `npm install -g pyright` |
   | Rust | `rustup component add rust-analyzer` |
   | Go | `go install golang.org/x/tools/gopls@latest` |

   You don't need to understand what these are. The agent handles everything.

4. Verify:
   repomap.exe doctor

Note for LLM agent: on Windows the binary is repomap.exe. If repomap.exe is on
PATH, the SKILL.md commands (repomap overview, repomap verify, etc.) work as-is.
If not on PATH, use the full path or repomap.exe in every command.

After installation, the agent automatically uses repomap during coding tasks — it calls commands like overview, impact, and verify on its own when needed.

---

Typical Usage

You don't type these commands yourself. The AI agent uses the repomap skill during its work — it decides when to call overview, impact, verify, etc. based on what you ask it to do.

Before editing

# First contact: get project structure
repomap overview --project /path/to/project

# Search by business keyword (when you don't know file names)
repomap query --project /path/to/project --query "auth token refresh"

# Inspect a file before reading it
repomap file-detail --project /path/to/project --file-path src/auth/login.ts

# Assess impact before changing a file
repomap impact --project /path/to/project --files src/auth/login.ts --with-symbols

# Trace who calls a function and what it calls
repomap call-chain --project /path/to/project --symbol refreshToken

After editing

# Quick: changed files + risk + suggested tests
repomap verify --project /path/to/project --quick

# Full: above + compiler/linter diagnostics + optional LSP
repomap verify --project /path/to/project

---

All Commands

Command	Purpose
overview	Project map: entry points, hotspots, key symbols (by PageRank), reading order
query --query <keywords>	Topic/keyword search across paths, filenames, and symbols
file-detail --file-path <file>	All symbols in a file: signatures, visibility, PageRank scores
impact --files <files> --with-symbols	Pre-edit blast radius: affected files, key symbols, risk level, suggested tests
call-chain --symbol <name>	Callers and callees of a symbol, sorted by importance
query-symbol --symbol <name>	Exact or fuzzy symbol lookup (shows definition location)
refs --symbol <name>	All references to a symbol (opt-in LSP for precise results)
verify	Post-edit gate: git changes, risk, diagnostics, suggested tests
verify --quick	Post-edit risk-only (skips compiler/LSP, faster)
check	Language diagnostics: tsc, cargo check, ruff, mypy, go vet
routes --json	HTTP API route inventory (FastAPI, Express, Axum, Spring Boot)
orphan	Dead-code candidate detection with confidence tiers
lsp doctor	Check locally installed LSP servers (typescript, pyright, rust-analyzer, gopls)

---

Supported Languages

You don't need to do anything. The AI agent handles language setup automatically during install — just tell it which languages you use.

8 languages work out of the box: Python, JavaScript, TypeScript (TSX), Go, Rust, HTML, CSS, JSON.

7 more (Java, Kotlin, Swift, C/C++, C#, PHP, Ruby) need one extra command that the agent runs for you: uv sync --all-extras.

For deeper analysis, the agent can use language servers already on your machine. If missing, install:

Language	Install command
TypeScript	npm install -g typescript-language-server
Python	npm install -g pyright
Rust	rustup component add rust-analyzer
Go	go install golang.org/x/tools/gopls@latest

Without them, overview / query / impact still work — LSP only adds extra precision for symbol-level lookups.

---

Origin

repomap's name and core idea come from aider. aider's author Paul Gauthier pioneered "repo mapping" — using tree-sitter + PageRank to give CLI AI agents codebase awareness. He proved a counterintuitive insight: a compact structural map often outperforms large amounts of raw code for agent understanding. We keep the "repo map" name to honor that origin.

repomap extends the concept: 15 languages, incremental scanning, pre-edit impact analysis, post-edit verification, and optional local LSP integration. Built by @gjczone, a non-programmer, using DeepSeek-V4-Pro, with GLM-5.1 and MIMO-V2.5-Pro for cross-validation and review.

---

Related Projects

• aider — the original CLI repo mapping pioneer. Paul Gauthier first conceived of tree-sitter + PageRank for AI-agent codebase awareness. This project stands on that foundation.
• DeepSeek-TUI — deepmap (Rust port of repomap's engine, PR submitted)

---

License

MIT — LICENSE