codemap is a code analysis tool designed to generate a compact, structured "brain map" of your codebase for large language models (LLMs) to understand instantly. By providing architectural context without burning tokens, codemap helps developers and AI systems work more efficiently together.
Key Features:
Generates an architectural overview of your codebase for LLMs in one command.
Supports multiple modes for analysis:
Diff Mode: Visualizes changes in the codebase compared to a reference branch.
Dependency Flow: Maps how different parts of the codebase interact and depend on each other.
Skyline Mode: Provides a visual representation of the project's structure as a city skyline.
Works with over 18 programming languages, including Go, Python, JavaScript, TypeScript, Rust, and more.
Audience & Benefit:
Ideal for developers, AI researchers, and teams leveraging LLMs to analyze or generate code. By providing instant context, codemap saves time, reduces token usage, and enhances collaboration between humans and AI systems. It is particularly beneficial for projects where understanding the codebase's structure is critical for efficient development and integration with AI tools.
codemap can be installed via winget on Windows, making it accessible across different operating systems.
README
codemap 🗺️
> codemap — structural ground truth for coding agents.
> Resolves what your code actually imports, tells you what breaks if you change it, and is explicit about what it couldn't figure out.
What it's for
An agent reading your repo can see what a file says. It can't cheaply see what depends on that file — that answer lives in go.mod, Cargo workspace membership, package.jsonexports maps, and tsconfig path aliases, not in the source text.
codemap computes three things:
Orientation
A structure map with the most-imported files called out. Cheap cold start, useful when an agent has no memory of the last hour.
Dependency graph
Imports resolved through each ecosystem's real rules — not string matching.
Blast radius
Who breaks if you change this file.
And one thing that matters more than any of them: it tells you when it doesn't know. Every dependency answer carries a coverage status, so a partial graph never reads as a complete one.
codemap . # structure + hubs
codemap --importers path/to/file # who depends on this
codemap --diff # what changed vs main
Install
# macOS/Linux
brew tap JordanCoin/tap && brew install codemap
# Windows
scoop bucket add codemap https://github.com/JordanCoin/scoop-codemap
scoop install codemap
> Other options: Releases | go install | build from source
CI / tarball install
Release tarballs ship codemap and the bundled rules but not the executable, which needs. Either install it separately:
Run setup anywhere inside your git repo. Repo-scoped commands such as
setup, doctor, config, watch, skill, context, serve, and
managed hooks resolve the nearest git root automatically, including linked
worktrees with a .git file.
cd /path/to/your/project
codemap setup
codemap setup configures Claude Code and Codex by default:
creates .codemap/config.json with auto-detected language filters
merges hooks into .claude/settings.local.json and .codex/hooks.json
configures MCP in .mcp.json and .codex/config.toml
hooks start and read daemon state at session start
Managed entries record the verified absolute path of the running codemap, so agents don't depend on your shell PATH. Rerun setup if that path changes.
codemap setup --agent claude # one agent only
codemap setup --agent codex
codemap setup --global # user-scope, applies to every project
Verify
codemap doctor # validate this project's integrations
codemap doctor --global # validate user-scope configuration
Doctor checks project scope and falls back to user scope, reporting which one satisfied each check. For Codex, trust the hooks from /hooks in CLI or Settings → Hooks in Desktop, then start a new session.
Dependency resolution
--deps and --importers resolve imports using each ecosystem's own rules rather than guessing from paths:
Ecosystem
Resolved via
Go
module path from go.mod; stdlib and third-party imports are not fuzzy-matched into local files
Rust
cargo metadata — workspace membership, target kinds (lib/bin/test/bench/example/build), and dev-dependencies reachable from #[cfg(test)] blocks
Each source reports authoritative, mixed, fallback, timeout, unavailable, or failed.
A timed-out or failed scan returns an empty result with provenance, not a silent empty graph and not a hard error — so an agent can tell "nothing imports this" apart from "I couldn't tell".
The JSON payload is versioned (schema_version: codemap.analysis/v1) so consumers can depend on its shape.
> Powered by ast-grep. Installed automatically with the Homebrew formula.
Commands
codemap . # structure view (respects .codemap/config.json)
codemap --diff # what changed vs main
codemap --deps . # dependency flow
codemap --importers f # who imports a file
codemap blast-radius # review bundle: diff + deps + importers
codemap handoff . # save layered handoff for cross-agent continuation
codemap context # machine-readable project context JSON
codemap doctor # validate agent integrations
codemap skill list # available agent skills
codemap watch start # background daemon for live graph state
codemap serve # HTTP API for non-MCP integrations
codemap mcp # MCP server on stdio
codemap --version
Options
Standard linked Git worktrees automatically reuse the primary worktree's
.codemap/config.json and project skills. Create the worktree with Git, an IDE,
or any manager that uses standard linked-worktree metadata, then give the agent
its absolute path:
Normal CLI and plugin MCP calls need no --setup-root: central config and skills
come from the primary worktree, while handoffs, watcher files, and hook/session
state remain in the linked worktree. Independent clones have no trusted Git
metadata linking them, so sharing setup between them still requires an explicit
override:
-C/--project-root selects the repository Codemap operates on.
--setup-root explicitly reuses /.codemap policy and runtime state
from another checkout. Both accept a repository or subdirectory; relative setup
paths resolve from the project root.
| Flag | Description |
Flag
Description
-C, --project-root
Operate on code in ``
--setup-root
Explicitly reuse policy and runtime state from /.codemap
--depth, -d
Limit tree depth (0 = unlimited)
--only
Only include files with these extensions
--exclude
Exclude files matching patterns
--diff
Show files changed vs main branch
--ref
Branch to compare against (with --diff)
--deps
Dependency flow mode
--importers
Check who imports a file
--skyline
City skyline visualization
--animate
Animate the skyline (with --skyline)
--json
Output JSON
> Flags come before the path/URL: codemap --json github.com/user/repo
Pattern matching needs no quotes: .png matches any .png file, Fonts matches any /Fonts/ directory, *Test* is a glob.
Modes
Diff
codemap --diff
codemap --diff --ref develop
╭─────────────────────────── myproject ──────────────────────────╮
│ Changed: 4 files | +156 -23 lines vs main │
╰────────────────────────────────────────────────────────────────╯
├── api/
│ └── (new) auth.go ✎ handlers.go (+45 -12)
└── ✎ main.go (+29 -3)
⚠ handlers.go is used by 3 other files
Shallow-clones to a temp directory and cleans up. If you already have the repo locally, codemap uses your copy.
Agent integration
Hooks
Automatic context at session start, before and after edits, and at compaction.
→ See docs/HOOKS.md
The prompt-submit hook classifies intent, surfaces hub-file risk, shows your working set, matches relevant skills, and emits structured markers (``) for tool consumption.
get_structure, get_diff, get_importers, get_dependencies, and get_handoff declare an OutputSchema and return typed structured content alongside the text response, so callers get parseable results instead of prose.
Codex
codemap setup configures Codex alongside Claude. For Codex only:
codemap setup --agent codex # project hooks + MCP
codemap plugin install # global plugin (MCP + skills), activated by default
codemap doctor --agent codex # validate; reports CLI and Desktop runtimes separately
After upgrading the codemap binary, agent integrations do not update themselves:
codemap plugin install # Codex only, once per Codex environment
cd /path/to/project && codemap setup && codemap doctor # both agents, per project
codemap plugin install refreshes the plugin for CLI and Desktop sharing a Codex environment, and migrates the current project when run inside one — but it does not discover every configured project. Start a new task or session afterward, and re-check hook trust if Codex asks.
> codemap doctor probes executables recorded in project-local config (.codex/config.toml, .mcp.json), so running it inside an untrusted repo executes a repo-chosen path. Doctor bounds this by requiring absolute paths and a recognized argument shape, but treat it like any command that honors project-local config.
Project config
Per-project defaults in .codemap/config.json, so you don't pass --only/--exclude/--depth every time. Hooks respect it too.
codemap config init # auto-detect top extensions, write config
codemap config show # display current config
All fields are optional; CLI flags always override config. When an MCP file search finds real matches hidden by only, codemap reports the paths and suggests which extensions to add — set guidance.missing_extension_hints: false to disable.
Skills
Markdown files that give agents context-aware guidance, matched against intent, mentioned files, and project languages.
codemap skill list
codemap skill show hub-safety
codemap skill init # custom skill template
Builtin
Activates when
hub-safety
Editing hub files (3+ importers)
refactor
Restructuring, renaming, moving code
test-first
Writing tests, TDD workflows
explore
Understanding how code works
handoff
Switching between AI agents
config-setup
.codemap/config.json is missing, boilerplate, or mismatched to the stack
Drop a .md file with YAML frontmatter in .codemap/skills/ to add your own — project-local skills override builtins, no Go code required:
---
name: my-skill
description: When this skill should activate
keywords: ["relevant", "keywords"]
languages: ["go"]
---
# Instructions for the AI agent
Context protocol
One command that gives any AI tool codemap's full intelligence:
codemap context # full JSON envelope
codemap context --for "refactor auth" # with pre-classified intent + matched skills
codemap context --compact # minimal, for token-constrained agents
Returns a ContextEnvelope with project metadata, dependency-graph evidence, intent classification, working set, matched skills, and a handoff reference. If fresh graph evidence is unavailable, hub counts are null and risk is unknown instead of being inferred from stale state. Anything that can shell out gets code-aware context.
HTTP API
codemap serve --port 9471
Endpoint
Returns
GET /api/context?intent=refactor+auth
Full context envelope
GET /api/context?compact=true
Minimal envelope
GET /api/skills
All skills with metadata
GET /api/skills?language=go&category=refactor
Filtered skill matches
GET /api/skills/
Full skill body
GET /api/working-set
Current session's active files
GET /api/health
Health check
Binds to 127.0.0.1; use --host 0.0.0.0 to expose.
Cross-agent handoff
When you switch agents (Claude → Codex → Cursor), codemap tracks who worked and what they touched:
