codemap

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.

Your agent's first minute

brew tap JordanCoin/tap && brew install codemap   # one static binary
cd your-repo && codemap setup                      # hooks + MCP for Claude Code and Codex
codemap mcp                                        # stdio MCP server for any other client

After codemap setup, the agent gets three answers it cannot get from the source text, at session start, before an edit, and on request.

Where things are. codemap .

╭────────────────────────────── codemap ──────────────────────────────╮
│ Files: 289 | Size: 2.3MB                                            │
│ Top Extensions: .go (227), .yml (35), .md (23), .sh (2), .ps1 (1)   │
╰─────────────────────────────────────────────────────────────────────╯
codemap
├── analysis/ (2 files, 3.6KB, all .go)
├── cmd/ (47 files, 463.2KB, all .go)
├── config/ (2 files, 23.2KB, all .go)
...

Who depends on this. codemap --importers config/config.go

⚠️  HUB FILE: config/config.go
   Imported by 40 files - changes have wide impact!

   Dependents:
   • blast_radius.go
   • cmd/config.go
   ... and 38 more
Coverage: complete

Where is the code that does X. codemap find "hub importers"

main.go
  matched: resolveImportersInvocation, buildImportersReport, runImportersMode
  importers: 0
Coverage: complete

Ranked by path and symbol match, each hit tagged with its importer count. Lexical only, and it says so.

And the one line every answer carries. Every dependency answer reports a coverage status: complete, partial, or unavailable, with the source that could not be trusted. A partial graph never reads as a complete one, so "nothing imports this" and "I couldn't tell" are different answers.

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:

Orientation	A structure map with the most-imported files called out. Cheap cold start, useful when an agent has no memory of the last hour.
Dependency graph	Imports resolved through each ecosystem's real rules, not string matching.
Blast radius	Who breaks if you change this file.

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:

Ecosystem	Resolved via
Go	module path from go.mod; stdlib and third-party imports are not fuzzy-matched into local files
Rust	cargo metadata — workspace membership, target kinds (lib/bin/test/bench/example/build), and dev-dependencies reachable from #[cfg(test)] blocks
JS/TS	package.json exports/imports maps, npm/pnpm/Bun workspaces, Deno import maps, and tsconfig rootDir/outDir remapping (including extends)
Dart/Flutter	pubspec.yaml package names and declared dependencies; package: URIs resolve within the owning package's lib/, while undeclared or duplicate package names fail closed
Everything else	ast-grep import extraction with suffix and directory matching

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",
      "languages": ["bash", "c", "cpp", "csharp", "dart", "elixir", "go", "java", "javascript", "kotlin", "lua", "php", "python", "ruby", "rust", "scala", "solidity", "swift", "typescript"] },
    { "name": "cargo-metadata", "status": "mixed",
      "detail": "2 of 5 Cargo manifests used fallback topology",
      "languages": ["rust"] }
  ],
  "issues": [
    { "code": "unresolved-import", "path": "src/app.ts",
      "message": "import ./gone resolved to no file in the project" }
  ]
}

issues lists each project-relative import that resolved to no file, one entry per reference. The key is omitted when there are none.

• status is complete, partial, or unavailable.
• Each source reports authoritative, mixed, fallback, timeout, unavailable, or failed.
• languages names the languages a source can affect. Per-file answers (--importers, get_importers, get_file_context, the importer sections of blast-radius) keep only the sources tagged with the file's language, plus untagged sources, which apply everywhere. A Go file in a Go+Rust repo reads complete with no Rust caveat; --deps keeps the scan-level rollup.
• 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

21 ast-grep language rules for dependency analysis: Go, Python, JavaScript, JSX, TypeScript, TSX, Rust, Ruby, C, C++, Java, Swift, Dart, Kotlin, C#, PHP, Bash, Lua, Scala, Elixir, Solidity. Dart projects, including Flutter apps and packages, also get pubspec.yaml dependency discovery. CUE files also contribute module-scoped package edges through lexical import extraction; CUE is not an ast-grep rule.

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 collide        # rank open PRs by shared-file merge-order hazard
codemap find "<query>" # rank files by path and symbol match, with importer counts
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 operates on exactly the named directory, like git -C; it may be a subdirectory of a repository, and storage and config discovery still walk up to the git root. --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 |

Flag	Description
-C, --project-root <dir>	Operate on exactly <dir> (may be a subdirectory of a repository; storage and config discovery still walk up to the git root)
--setup-root <repo>	Explicitly reuse policy and runtime state from <repo>/.codemap
--depth, -d <n>	Limit tree depth (0 = unlimited)
--only <exts>	Only include files with these extensions
--exclude <patterns>	Exclude files matching patterns
--max-files <n>	Scan bound: files kept by the tree, and the largest repo a dependency scan runs on (default 100000, or config max_files; -1 = unbounded). Above it the output says bounded: scanned N of M files instead of presenting a prefix as the repo
--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 (with --skyline)
--json	Output JSON