codemap 🗺️

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

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

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
`--json`	Output JSON

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

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 7 tools for codebase analysis. → See docs/MCP.md

CLAUDE.md — Add to your project root to teach Claude when to run codemap:

cp /path/to/codemap/CLAUDE.md your-project/

Roadmap

Diff mode, Skyline mode, Dependency flow
Tree depth limiting (--depth)
File filtering (--only, --exclude)
Claude Code hooks & MCP server
Enhanced analysis (entry points, key types)

Contributing

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

License

MIT

jordancoin/codemap

README