codemap 🗺️

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

This repository is a fork of JordanCoin/codemap, with additional agentic workflow features and fixes.

What This Fork Adds

• First-class Codex support — setup, hooks, MCP, plugins, skills, and runtime-aware diagnostics.
• Shared setup across worktrees — reuse the primary checkout's tuned .codemap configuration from linked or external worktrees.
• Project-aware MCP workflows — automatic root routing and fewer fragile per-call root arguments.
• Resilient project discovery — configuration-only projects remain usable without current daemon or index state.
• Accurate project state — configured counts, filters, and status reflect the effective project setup.
• Reliable agent handoffs — CLI and MCP handoffs preserve equivalent filtered context and metadata.
• Sandbox-safe, stable scanning — dependency scans avoid global writes and watchers debounce duplicate events.
• Traceable integration builds — cross-platform artifacts embed their exact version and commit.

Agentic Examples

1. Point an agent at a linked worktree

git worktree add /tmp/project.worktree -b feature main
codemap -C /tmp/project.worktree context --compact

Key detail: -C selects the agent's code checkout. Standard linked worktrees automatically reuse the primary checkout's config and skills, so do not add --setup-root; handoff, watcher, and session state stays worktree-local.

2. Reuse tuned setup from an independent clone

codemap -C /tmp/project.worktree --setup-root /path/to/configured/repo context --compact

Key detail: -C selects the code to analyze; --setup-root selects the .codemap setup to reuse. Both accept a repository root or a descendant.

3. Set up and diagnose Codex directly

codemap setup --agent codex
codemap doctor --agent codex

Key detail: managed integrations record the verified absolute codemap path. Rerun setup after moving the binary.

4. Generate a read-only machine handoff

codemap handoff --json --no-save .

Key detail: CLI handoffs save by default; --no-save avoids worktree writes. MCP get_handoff is read-only unless called with save=true.

5. Diff against the repository's real default branch

codemap -C /tmp/project.worktree --diff

Key detail: the base ref is auto-detected instead of assuming main. Add --ref <branch> only when you need an explicit override.

6. Make dependency requests root-safe

codemap --deps /path/to/configured/repo

For an agent, a portable MCP prompt is:

Use Codemap get_dependencies with path="/path/to/configured/repo".

Key detail: MCP may omit path only when the client advertises exactly one accessible local root; otherwise pass it explicitly.

7. Use configured projects before index state exists

codemap -C /path/to/configured/repo context --compact

Key detail: .codemap/config.json filters remain effective even without current daemon or index state.

8. Identify the exact integration build

codemap --version  # codemap v4.1.10-8+858eea2

Key detail: integration artifacts report both their release version and source revision, making deployed agent environments traceable.

Install Fork

Download the latest successful integration artifacts →

GitHub wraps the build files in an outer ZIP. On macOS, extract the basic archive and remove Gatekeeper's quarantine attribute before running it:

arch=$(uname -m); [ "$arch" = x86_64 ] && arch=amd64
unzip codemap-integration-*.zip
tar -xzf codemap_*_darwin_"$arch".tar.gz
xattr -dr com.apple.quarantine codemap
./codemap --version

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.

Example for Alpine-based CI:

apk add --no-cache curl jq bash python3 py3-pip

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_${CODEMAP_VERSION}_linux_${ARCH}.tar.gz" \
  | tar xz -C /usr/local/bin/ codemap

python3 -m pip install --no-cache-dir ast-grep-cli

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

Recommended Setup (Hooks + Daemon + Config)

No repo clone is required for normal users. 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.

# install codemap first (package manager)
brew tap JordanCoin/tap && brew install codemap

# then run setup anywhere inside your project repo
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.

Configure one agent only, or use global settings:

codemap setup --agent claude
codemap setup --agent codex
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. Run codemap doctor (or select --agent claude|codex).
2. Trust Codex project hooks from /hooks in CLI or Settings > Hooks in Desktop, then start a new session/task.
3. 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 the auto-detected default branch
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

Other Commands

codemap --only swift .
codemap --exclude .xcassets,Fonts,.png .
codemap --depth 2 .
codemap github.com/user/repo

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:

git worktree add <path> -b <branch> <base>
codemap -C /tmp/feature-worktree context

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:

codemap -C /tmp/independent-clone --setup-root /path/to/configured/repo context

-C/--project-root selects the repository Codemap operates on. --setup-root explicitly reuses <repository>/.codemap policy and runtime state from another checkout. Both accept a repository or subdirectory; relative setup paths resolve from the project root.

Options

Flag	Description
-C, --project-root <repo>	Operate on code in <repo>
--setup-root <repo>	Explicitly reuse policy and runtime state from <repo>/.codemap
--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 the auto-detected default 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.

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.

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 + configured file-count context (honors .codemap/config.json)
• 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"],
  "guidance": {
    "missing_extension_hints": true,
    "ignored_extensions": []
  },
  "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"]
  }
}

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
• Shows your working set (files edited this session)
• Emits structured JSON markers (<!-- codemap:intent -->) for tool consumption
• Matches relevant skills and tells you which to pull (codemap skill show <name>)
• 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, dependency-graph evidence, intent classification, working set, matched skills, and handoff reference. If fresh graph evidence is unavailable, hub counts are null and risk is unknown instead of being inferred from stale state. 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