codemap

codemap

a project brain for your AI. Give LLMs instant architectural context without burning tokens

Stars: 445

Visit
 screenshot

Codemap is a project brain tool designed to provide instant architectural context for AI projects without consuming excessive tokens. It offers features such as tree visualization, file filtering, dependency flow analysis, and remote repository support. Codemap can be integrated with Claude for automatic context at session start and supports multi-agent handoff for seamless collaboration between different tools. The tool is powered by ast-grep and supports 18 languages for dependency analysis, making it versatile for various project types.

README:

codemap 🗺️

Run in Smithery

codemap — a project brain for your AI. Give LLMs instant architectural context without burning tokens.

License Go

codemap screenshot

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

Quick Start

codemap .                    # Project tree
codemap --only swift .       # Just Swift files
codemap --exclude .xcassets,Fonts,.png .  # Hide assets
codemap --depth 2 .          # Limit depth
codemap --diff               # What changed vs main
codemap --deps .             # Dependency flow
codemap handoff .            # Save cross-agent handoff summary
codemap github.com/user/repo # Remote GitHub repo

Options

Flag Description
--depth, -d <n> Limit tree depth (0 = unlimited)
--only <exts> Only show files with these extensions
--exclude <patterns> Exclude files matching patterns
--diff Show files changed vs main branch
--ref <branch> Branch to compare against (with --diff)
--deps Dependency flow mode
--importers <file> Check who imports a file
--skyline City skyline visualization
--animate Animate the skyline (use with --skyline)
--json Output JSON

Note: Flags must come before the path/URL: codemap --json github.com/user/repo

Smart pattern matching — no quotes needed:

  • .png → any .png file
  • Fonts → any /Fonts/ directory
  • *Test* → glob pattern

Modes

Diff Mode

See what you're working on:

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

Dependency Flow

See how your code connects:

codemap --deps .
╭──────────────────────────────────────────────────────────────╮
│                    MyApp - Dependency Flow                   │
├──────────────────────────────────────────────────────────────┤
│ Go: chi, zap, testify                                        │
╰──────────────────────────────────────────────────────────────╯

Backend ════════════════════════════════════════════════════
  server ───▶ validate ───▶ rules, config
  api ───▶ handlers, middleware

HUBS: config (12←), api (8←), utils (5←)

Skyline Mode

codemap --skyline --animate

codemap skyline

Remote Repos

Analyze any public GitHub or GitLab repo without cloning it yourself:

codemap github.com/anthropics/anthropic-cookbook
codemap https://github.com/user/repo
codemap gitlab.com/user/repo

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.

Supported Languages

18 languages for dependency analysis: Go, Python, JavaScript, TypeScript, Rust, Ruby, C, C++, Java, Swift, Kotlin, C#, PHP, Bash, Lua, Scala, Elixir, Solidity

Powered by ast-grep. Install via brew install ast-grep for --deps mode.

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 .                 # Build + save layered handoff artifacts
codemap handoff --latest .        # Read latest saved artifact
codemap handoff --json .          # Machine-readable handoff payload
codemap handoff --since 2h .      # Limit timeline lookback window
codemap handoff --prefix .        # Stable prefix layer only
codemap handoff --delta .         # Recent delta layer only
codemap handoff --detail a.go .   # Lazy-load full detail for one changed file
codemap handoff --no-save .       # Build/read without writing artifacts

What it captures (layered for cache reuse):

  • prefix (stable): hub summaries + repo file-count context
  • delta (dynamic): changed file stubs (path, hash, status, size), risk files, recent events, next steps
  • deterministic hashes: prefix_hash, delta_hash, combined_hash
  • cache metrics: reuse ratio + unchanged bytes vs previous handoff

Artifacts written:

  • .codemap/handoff.latest.json (full artifact)
  • .codemap/handoff.prefix.json (stable prefix snapshot)
  • .codemap/handoff.delta.json (dynamic delta snapshot)
  • .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/

Roadmap

  • [x] Diff mode, Skyline mode, Dependency flow
  • [x] Tree depth limiting (--depth)
  • [x] File filtering (--only, --exclude)
  • [x] Claude Code hooks & MCP server
  • [x] Cross-agent handoff artifact (.codemap/handoff.latest.json)
  • [x] Remote repo support (GitHub, GitLab)
  • [ ] Enhanced analysis (entry points, key types)

Contributing

  1. Fork → 2. Branch → 3. Commit → 4. PR

License

MIT

For Tasks:

Click tags to check more tools for each tasks

For Jobs:

Alternative AI tools for codemap

Similar Open Source Tools

For similar tasks

For similar jobs