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 — a project brain for your AI.
> Give LLMs instant architectural context without burning tokens.
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
Tarball / CI Install
If you install codemap from a release tarball, also install ast-grep separately for --deps.
The tarball includes codemap and the bundled rules, but not the ast-grep executable.
If you want a self-contained archive for CI/CD, use the codemap-full release artifact instead.
It includes codemap, ast-grep, and sg in one archive so --deps works after extraction.
apk add --no-cache curl jq bash
ARCH=$(uname -m)
if [ "$ARCH" = "x86_64" ]; then ARCH="amd64"; elif [ "$ARCH" = "aarch64" ]; then ARCH="arm64"; fi
CODEMAP_VERSION=$(curl -fsSL https://api.github.com/repos/JordanCoin/codemap/releases/latest | jq -r '.tag_name' | tr -d 'v')
curl -fsSL "https://github.com/JordanCoin/codemap/releases/download/v${CODEMAP_VERSION}/codemap-full_${CODEMAP_VERSION}_linux_${ARCH}.tar.gz" \
| tar xz -C /usr/local/bin/ codemap ast-grep sg
No repo clone is required for normal users.
Run setup from your git repo root (not a subdirectory), or hooks may not resolve project context.
# install codemap first (package manager)
brew tap JordanCoin/tap && brew install codemap
# then run setup inside your project
cd /path/to/your/project
codemap setup
codemap setup configures Claude Code and Codex by default:
creates .codemap/config.json (if missing) 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 automatically start/read daemon state on session start
Managed entries use the verified absolute path of the running codemap, so
agents do not depend on your shell PATH. Rerun setup if that path changes.
Windows (PowerShell): ./scripts/onboard.ps1 -ProjectRoot C:\path\to\your\project
Verify Setup
Run codemap doctor (or select --agent claude|codex).
Trust Codex project hooks from /hooks in CLI or Settings > Hooks in Desktop, then start a new session/task.
Confirm Codemap appears in /mcp, then edit a file and verify hook context.
Daily Commands
codemap . # Fast tree/context view (respects .codemap/config.json)
codemap --diff # What changed vs main
codemap handoff . # Save layered handoff for cross-agent continuation
codemap --deps . # Dependency flow (requires ast-grep)
codemap skill list # Show available skills
codemap context # Universal JSON context for any AI tool
codemap mcp # Run Codemap MCP server on stdio
codemap --version # Show the installed build version
codemap plugin install # Install/update and activate the Codemap plugin through Codex CLI
codemap doctor # Validate installed Claude/Codex integrations
codemap serve # HTTP API for non-MCP integrations
Uses a shallow clone to a temp directory (fast, no history, auto-cleanup). If you already have the repo cloned locally, codemap will use your local copy instead.
> Powered by ast-grep. Install via brew install ast-grep for --deps mode.
Blast Radius Bundle
If you want a compact review bundle for another LLM, combine the three high-signal views:
codemap --json --diff --ref main .
codemap --json --deps --diff --ref main .
codemap --json --importers path/to/file .
For a reusable built-in command that emits either Markdown, text, or a single JSON object:
codemap blast-radius --ref main .
codemap blast-radius --json --ref main .
codemap blast-radius --text --ref main .
Codex Integration
Plain codemap setup already configures Claude Code and Codex. Use
codemap setup --agent codex to configure only Codex project hooks and MCP.
Add --no-config --no-mcp when the Codex plugin owns MCP and only hooks are needed.
Use codemap plugin install to install/update the bundled MCP and skills and
activate them through Codex CLI. Both commands are
idempotent and report when a new Codex task/session is needed. Use
--no-activate only for staging; legacy --activate is deprecated because
activation is now the default. Use codemap doctor --agent codex to validate
the shared project integration and report CLI/Desktop runtimes independently.
Managed MCP entries record the Codemap build version. After an upgrade, rerun
setup or plugin installation if MCP reports a mismatch. Codex CLI and Desktop
may use different runtime releases; doctor reports them independently.
After a Codemap upgrade
Agent integrations do not update themselves. Codex users should refresh the
global plugin first; all users should then refresh each project's managed hooks
and MCP entries:
# After upgrading the codemap binary
# Codex only, once for each Codex environment:
codemap plugin install
# Claude and Codex: repeat in each configured project
cd /path/to/project
codemap setup
codemap doctor
codemap plugin install updates the global plugin and migrates the current
project when run inside one, but it does not discover every configured project.
One installation refreshes the plugin for CLI and Desktop when they share the
same Codex environment. Repeat it for another host or CODEX_HOME; it does not
upgrade the Codex applications themselves.
Claude users skip that command but still rerun codemap setup --agent claude
and codemap doctor --agent claude in each configured project.
Rerun codemap setup --global separately if you use global agent settings.
After plugin or managed command changes, start a new task in Desktop or a new
session in CLI, and review hook trust again if Codex asks.
Note: codemap doctor probes the executables recorded in project-local
configuration (.codex/config.toml, .mcp.json), so running it inside a
repository you don't trust executes a repo-chosen path. Doctor bounds this by
requiring absolute paths and a recognized argument shape, but treat doctor like
any other command that honors project-local config.
Claude Integration
Hooks (Recommended) — Automatic context at session start, before/after edits, and more.
→ See docs/HOOKS.md
MCP Server — Deep integration with project analysis + handoff tools.
→ See docs/MCP.md
Multi-Agent Handoff
codemap now supports a shared handoff artifact so you can switch between agents (Claude, Codex, MCP clients) without re-briefing.
.codemap/handoff.metrics.log (append-only metrics stream, one JSON line per save)
Save defaults:
CLI saves by default; use --no-save to make generation read-only.
MCP does not save by default; set save=true to persist artifacts.
Compatibility note:
legacy top-level fields (changed_files, risk_files, etc.) are still included for compatibility and will be removed in a future schema version after migration.
Why this matters:
default transport is compact stubs (low context cost)
full per-file context is lazy-loaded only when needed (--detail / file=...)
output is deterministic and budgeted to reduce context churn across agent turns
Hook integration:
session-stop writes .codemap/handoff.latest.json
session-start shows a compact recent handoff summary (24h freshness window)
CLAUDE.md — Add to your project root to teach Claude when to run codemap:
cp /path/to/codemap/CLAUDE.md your-project/
Project Config
Set per-project defaults in .codemap/config.json so you don't need to pass --only/--exclude/--depth every time. Hooks also respect this config.
codemap config init # Auto-detect top extensions, write config
codemap config show # Display current config
When an MCP file search has no visible results but finds real matches hidden by only, Codemap reports the matching paths and suggests which extensions to include. These hints still respect exclude and never modify project config. Set guidance.missing_extension_hints to false to disable all hints, or list extensions in guidance.ignored_extensions to suppress only those suggestions.
All fields are optional. CLI flags always override config values.
Hook-specific policy fields are optional and bounded by safe defaults.
Skills
codemap ships with a skills framework — markdown files that provide context-aware guidance to AI agents. Skills are automatically matched against your intent, the files you mention, and the languages in your project.
codemap skill list # Show all available skills
codemap skill show hub-safety # Print full skill content
codemap skill init # Create a custom skill template
Builtin Skills
Skill
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
Custom Skills
Drop a .md file in .codemap/skills/ with YAML frontmatter:
---
name: my-skill
description: When this skill should activate
keywords: ["relevant", "keywords"]
languages: ["go"]
---
# Instructions for the AI agent
Project-local skills override builtins. No Go code needed — just markdown.
MCP Tools
Skills are also available via MCP: list_skills (metadata) and get_skill (full body).
Intelligent Routing
The prompt-submit hook performs intent classification on every prompt — detecting whether you're refactoring, fixing a bug, exploring, testing, or building a feature. It then:
Surfaces risk analysis based on hub file involvement
Emits exact next-step codemap commands at transition points like “before editing” and “before refactoring”
Shows your working set (files edited this session)
Emits structured JSON markers (``) for tool consumption
Matches relevant skills and tells you which to pull (codemap skill show )
Warns about documentation drift when docs are stale
Context Protocol
A single 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
The output is a ContextEnvelope containing project metadata, intent classification, working set, matched skills, and handoff reference. Cursor, Windsurf, Codex, custom agents — anything that can shell out gets code-aware intelligence.
HTTP API
For tools that prefer HTTP over CLI:
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
Server health check
Binds to 127.0.0.1 by default. Use --host 0.0.0.0 to expose to network.
Agent-Aware Handoff
When you switch between AI agents (Claude → Codex → Cursor), codemap tracks who worked and what they did:
