codemap 🗺️

codemap — structural ground truth for coding agents. Resolves what your code actually imports, tells you what breaks if you change it, and is explicit about what it couldn't figure out.

What it's for

An agent reading your repo can see what a file says. It can't cheaply see what depends on that file — that answer lives in go.mod, Cargo workspace membership, package.json exports maps, and tsconfig path aliases, not in the source text.

codemap computes three things:

And one thing that matters more than any of them: it tells you when it doesn't know. Every dependency answer carries a coverage status, so a partial graph never reads as a complete one.

codemap .                        # structure + hubs
codemap --importers path/to/file # who depends on this
codemap --diff                   # what changed vs main

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

CI / tarball install

Release tarballs ship codemap and the bundled rules but not the ast-grep executable, which --deps needs. Either install it separately:

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

…or use the self-contained codemap-full artifact, which bundles codemap, ast-grep, and sg:

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

Setup

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.

cd /path/to/your/project
codemap setup

codemap setup configures Claude Code and Codex by default:

• creates .codemap/config.json 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 start and read daemon state at session start

Managed entries record the verified absolute path of the running codemap, so agents don't depend on your shell PATH. Rerun setup if that path changes.

codemap setup --agent claude   # one agent only
codemap setup --agent codex
codemap setup --global         # user-scope, applies to every project

Verify

codemap doctor            # validate this project's integrations
codemap doctor --global   # validate user-scope configuration

Doctor checks project scope and falls back to user scope, reporting which one satisfied each check. For Codex, trust the hooks from /hooks in CLI or Settings → Hooks in Desktop, then start a new session.

Dependency resolution

--deps and --importers resolve imports using each ecosystem's own rules rather than guessing from paths:

The coverage contract

Every dependency answer reports how much of it codemap actually stands behind:

codemap --json --deps . | jq .coverage

{
  "status": "partial",
  "sources": [
    { "name": "ast-grep", "status": "authoritative" },
    { "name": "cargo-metadata", "status": "mixed",
      "detail": "2 of 5 Cargo manifests used fallback topology" }
  ],
  "issues": []
}

• status is complete, partial, or unavailable.
• Each source reports authoritative, mixed, fallback, timeout, unavailable, or failed.
• A timed-out or failed scan returns an empty result with provenance, not a silent empty graph and not a hard error — so an agent can tell "nothing imports this" apart from "I couldn't tell".

The JSON payload is versioned (schema_version: codemap.analysis/v1) so consumers can depend on its shape.

Supported languages

20 language rules for dependency analysis: Go, Python, JavaScript, JSX, TypeScript, TSX, Rust, Ruby, C, C++, Java, Swift, Kotlin, C#, PHP, Bash, Lua, Scala, Elixir, Solidity.

Powered by ast-grep. Installed automatically with the Homebrew formula.

Commands

codemap .              # structure view (respects .codemap/config.json)
codemap --diff         # what changed vs main
codemap --deps .       # dependency flow
codemap --importers f  # who imports a file
codemap blast-radius   # review bundle: diff + deps + importers
codemap handoff .      # save layered handoff for cross-agent continuation
codemap context        # machine-readable project context JSON
codemap doctor         # validate agent integrations
codemap skill list     # available agent skills
codemap watch start    # background daemon for live graph state
codemap serve          # HTTP API for non-MCP integrations
codemap mcp            # MCP server on stdio
codemap --version

Options

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/original 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.

| Flag | Description |

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

Pattern matching needs no quotes: .png matches any .png file, Fonts matches any /Fonts/ directory, *Test* is a glob.

Modes

Diff

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

codemap --deps .

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

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

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

Blast radius

Who breaks if you change a file:

codemap --importers config/config.go

⚠️  HUB FILE: config/config.go
   Imported b