codemap CLI
Resolves which files import each other and what an edit will touch, and serves it to agents through hooks, MCP and a CLI
- 704 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- `codemap setup` merges hooks into Claude Code and Codex settings, and those hooks run the binary on every session and edit
- The background watcher and the HTTP API on 127.0.0.1 hold graph state, and a command with a GitHub or GitLab address clones a third-party repository into a temp folder
- `codemap doctor` in an untrusted repository runs a path from its local config, as the developer warns
Install
- Works in
Manual install
brew tap JordanCoin/tap && brew install codemapmacOS and Linux. On Windows: scoop bucket add codemap https://github.com/JordanCoin/scoop-codemap, then scoop install codemap.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- `codemap setup` merges hooks into Claude Code and Codex settings, and those hooks run the binary on every session and edit
- The background watcher and the HTTP API on 127.0.0.1 hold graph state, and a command with a GitHub or GitLab address clones a third-party repository into a temp folder
- `codemap doctor` in an untrusted repository runs a path from its local config, as the developer warns
This is third-party code. Review the repository files before installing.
What it does
codemap builds a repository map and an import graph for an agent. An agent can see what a file says but not what depends on it, and that follows from go.mod, Cargo workspace membership, package.json exports maps and tsconfig aliases. codemap resolves them by each ecosystem's own rules. `codemap .` shows the tree with the most-imported files marked, `codemap --importers config/config.go` lists the dependents of a file, and `codemap find "query"` ranks files by path and symbol match and tags each with its importer count. Every dependency answer ends with a coverage line: complete, partial or unavailable, naming the source that could not be trusted. That makes "nothing imports this file" and "could not tell" read differently. If a scan times out or fails, codemap returns an empty result with provenance. `codemap setup` wires all of this into Claude Code and Codex: it creates `.codemap/config.json` with language filters, merges hooks into `.claude/settings.local.json` and `.codex/hooks.json` and registers MCP in `.mcp.json` and `.codex/config.toml`. Hooks supply context at session start, before an edit and at compaction, and a 19-tool MCP server starts with `codemap mcp` for any client.
Who it is for. For developers whose agent edits large repositories in Go, Rust, TypeScript, Python and other languages and needs to know in advance which files a change will touch.
Good fit when
- An agent is about to rename or move a file that dozens of others import, and you want to show it the dependents with `codemap --importers`
- Before review you need one change report: `codemap blast-radius --ref main .` bundles the diff, dependencies and importing files as Markdown or JSON
- The agent starts every session from zero and needs a cheap structure overview: a tree with the most-imported files marked at the start
- Several pull requests are open and `codemap collide` ranks them by merge-conflict hazard from shared files
- Work moves between Claude Code, Codex and Cursor, and `codemap handoff` records who edited which files
Not a fit when
- You need meaning-based search: `codemap find` matches paths and symbols only and says so itself
- The repository is small and the agent copes by reading a few files without a graph
- You need to run or test code: codemap reads sources and imports and does not execute the program
- You need analysis of a language outside the 21 dependency rules: for such files the graph stays incomplete
Example request
Before changing config/config.go, use codemap to find which files import it and tell me how wide the edit will reachLimitations
- Dependency analysis uses ast-grep. Homebrew installs it for you, while the release tarball ships only codemap, so CI needs a separate ast-grep or the codemap-full build.
- Without fresh graph evidence, hub counts in the context stay null and the edit-risk estimate reads unknown, so a guess is not shown as fact.
- After a binary upgrade the agent integrations stay as they were until you refresh them: run `codemap setup` in every project, and for Codex run `codemap plugin install` once.
- `codemap doctor` probes executables recorded in a project's local config. The developer warns that in an untrusted repository this runs a path chosen by that repository.
How to disable. Remove the codemap block from `.mcp.json` and `.codex/config.toml` and the codemap hooks from `.claude/settings.local.json` and `.codex/hooks.json`. The project's `.codemap` folder can be deleted. The background watcher is started separately with `codemap watch start`, so end its process if you launched it. The binary itself is removed with `brew uninstall codemap` or `scoop uninstall codemap`.
FAQ
How do I connect codemap to Claude Code?
Install the program through Homebrew or Scoop and run `codemap setup` in the git repository root. It creates the project config, merges hooks into the Claude Code settings and registers MCP. Add `--agent claude` for Claude only, and `codemap doctor` verifies the connection.
What does the line Coverage: partial mean in a codemap answer?
The status shows how fully codemap stands behind the answer: complete, partial or unavailable. With partial, some sources, such as Cargo manifests, were resolved by fallback, and unresolved imports are listed under issues. An empty answer with partial does not mean nobody imports the file.
How do I find out what breaks if I change a file?
Run `codemap --importers path/to/file`: it lists the dependent files and marks the file as a HUB FILE when three or more files import it. `codemap blast-radius --ref main .` gives a full review report, and with `--json` it prints a single JSON object.
Which languages does codemap support?
Dependency analysis ships 21 ast-grep rules: Go, Python, JavaScript, TypeScript, Rust, Ruby, C, C++, Java, Swift, Dart, Kotlin, C#, PHP and more. Go, Rust, JS/TS and Dart imports resolve by the ecosystem's rules, and the rest by suffix and directory matching.
Can I analyze someone else's repository from GitHub?
Yes, pass the address instead of a path, for example `codemap github.com/user/repo`. The program shallow-clones the repository into a temporary folder and cleans it up afterward. If a local copy exists, it uses that. Flags go before the address.
Discussion
No questions or reviews yet.
Related
CLI toolscodesight maps a project in one run: routes, DB models, dependencies, env vars. It gives the map to an agent as files or through an MCP server
Local code structure graph: builds a repository map with tree-sitter and serves the assistant only the context a change actually touches over MCP
CodeGraph (Rust)
codegraph-rust
A Rust code graph for agents: four MCP tools show what an edit will touch, how the architecture fits together and where the fragile spots are
Deep Graph MCP: a code graph of a repository for agents
Deep Graph MCP
An MCP server that gives an agent a repository code graph: search by meaning, symbol links and the places an edit would touch
Work modes for AI coding agents: a light solo mode for daily tasks and /man with a plan, checks and review for big changes
An MCP server and CLI in Go: the agent keeps an index of code and database schema in the repository, versions it in Git and reads it whole before each task
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| codemap (this entry) | no | 704 | ||
| CodeGraph | no | not required | 75,798 | a local code graph for MCP with entry points and symbol links, no hooks and no handoff between agents |
| GitNexus | no | not required | 48,101 | indexes code into a knowledge graph and serves call links over MCP, without marking answer coverage |
README in short
The repository page opens with three commands for an agent's first minute: install, run setup and start MCP. It then explains why a dependency graph matters and shows the coverage contract with a JSON example. After that come install, resolution rules for Go, Rust, JS/TS and Dart, the full list of commands and flags and the diff, deps, blast radius and skyline modes. The end covers hooks, the 19 MCP tools, project config, built-in skills, the context protocol, the HTTP API and handoff between agents.