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

Recommended Setup (Hooks + Daemon + Config)

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 is the default onboarding path and configures the pieces that make codemap most useful with Claude:

• creates .codemap/config.json (if missing) with auto-detected language filters
• installs codemap hooks into .claude/settings.local.json (project-local by default)
• hooks automatically start/read daemon state on session start

Use global Claude settings instead of project-local settings:

codemap setup --global

Windows equivalent:

scoop bucket add codemap https://github.com/JordanCoin/scoop-codemap
scoop install codemap
cd C:\path\to\your\project
codemap setup

Optional helper scripts (mainly for contributors running from this repo):

• macOS/Linux: ./scripts/onboard.sh /path/to/your/project
• Windows (PowerShell): ./scripts/onboard.ps1 -ProjectRoot C:\path\to\your\project

Verify Setup

1. Restart Claude Code or open a new session.
2. At session start, you should see codemap project context.
3. Edit a file and confirm pre/post edit hook context appears.

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 serve      # HTTP API for non-MCP integrations

Other Commands

codemap --only swift .
codemap --exclude .xcassets,Fonts,.png .
codemap --depth 2 .
codemap github.com/user/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

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/

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

Example .codemap/config.json:

{
  "only": ["rs", "sh", "sql", "toml", "yml"],
  "exclude": ["docs/reference", "docs/research"],
  "depth": 4,
  "mode": "auto",
  "budgets": {
    "session_start_bytes": 30000,
    "diff_bytes": 15000,
    "max_hubs": 8
  },
  "routing": {
    "retrieval": { "strategy": "keyword", "top_k": 3 },
    "subsystems": [
      {
        "id": "watching",
        "paths": ["watch/**"],
        "keywords": ["hook", "daemon", "events"],
        "docs": ["docs/HOOKS.md"],
        "agents": ["codemap-hook-triage"]
      }
    ]
  },
  "drift": {
    "enabled": true,
    "recent_commits": 10,
    "require_docs_for": ["watching"]
  }
}

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
• Shows your working set (files edited this session)
• Emits structured JSON markers (<!-- codemap:intent -->) for tool consumption
• Matches and injects relevant skills automatically
• 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/<name>	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:

{
  "agent_history": [
    {"agent_id": "claude-code", "files_edited": ["cmd/hooks.go", "main.go"], "ended_at": "..."},
    {"agent_id": "codex", "files_edited": ["scanner/types.go"], "ended_at": "..."}
  ]
}

Agent detection is automatic via environment variables. History is carried across sessions (capped at 20 entries) in the handoff artifact.

Roadmap

• Diff mode, Skyline mode, Dependency flow
• Tree depth limiting (--depth)
• File filtering (--only, --exclude)
• Project config (.codemap/config.json)
• Claude Code hooks & MCP server
• Cross-agent handoff artifact (.codemap/handoff.latest.json)
• Remote repo support (GitHub, GitLab)
• Intelligent routing (intent classification, risk analysis, working set)
• Skills framework (builtin + custom skills, CLI, MCP tools)
• Context protocol (codemap context — universal JSON envelope for any AI tool)
• HTTP API (codemap serve — REST endpoints for non-MCP integrations)
• Agent-aware handoff (multi-agent history tracking)
• Community skill registry (GitHub-hosted, codemap skill add <name>)
• Enhanced analysis (entry points, key types)

Contributing

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

License

MIT