百科.dev
全部条目AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
C

codemap

> AI 编程
开源

为您的 AI 提供一个项目大脑。在不消耗代币的情况下,为 LLM 提供即时的架构上下文

651 stars0 点赞0 次浏览
访问官网GitHub

工具介绍

为您的 AI 提供一个项目大脑。在不消耗代币的情况下,为 LLM 提供即时的架构上下文

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

bash
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

bash
# 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:

bash
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:

bash
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.

bash
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.

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

Verify

bash
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:

bash
codemap --json --deps . | jq .coverage
json
{
  "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

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

…

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:

bash
git worktree add  -b  
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:

bash
codemap -C /tmp/independent-clone --setup-root /path/to/original context

-C/--project-root selects the repository Codemap operates on. --setup-root explicitly reuses /.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 Operate on code in ``
--setup-root Explicitly reuse policy and runtime state from /.codemap
--depth, -d Limit tree depth (0 = unlimited)
--only Only include files with these extensions
--exclude Exclude files matching patterns
--diff Show files changed vs main branch
--ref Branch to compare against (with --diff)
--deps Dependency flow mode
--importers Check who imports a file
--skyline City skyline visualization
--animate Animate the skyline (with --skyline)
--json Output JSON

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

bash
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

bash
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:

bash
codemap --importers config/config.go
⚠️  HUB FILE: config/config.go
   Imported by 21 files - changes have wide impact!

   Dependents:
   • cmd/hooks.go
   • mcp/find_guidance.go
   ...

For a review bundle in one command — Markdown, text, or a single JSON object:

bash
codemap blast-radius --ref main .
codemap blast-radius --json --ref main .
codemap blast-radius --text --ref main .

Skyline

bash
codemap --skyline --animate

Remote repos

Analyze any public GitHub or GitLab repo without cloning it yourself:

bash
codemap github.com/anthropics/anthropic-cookbook
codemap gitlab.com/user/repo

Shallow-clones to a temp directory and cleans up. If you already have the repo locally, codemap uses your copy.

Agent integration

Hooks

Automatic context at session start, before and after edits, and at compaction. → See docs/HOOKS.md

The prompt-submit hook classifies intent, surfaces hub-file risk, shows your working set, matches relevant skills, and emits structured markers (``) for tool consumption.

MCP

codemap mcp serves 19 tools over stdio:

Category Tools
Structure get_structure, find, find_file, get_hubs, get_file_context
Dependencies get_dependencies, get_importers, get_diff
Session get_working_set, get_activity, get_handoff
Daemon start_watch, stop_watch, status
Skills list_skills, get_skill
Discovery list_projects

get_structure, `ge

Issues· 0 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues，或尚未同步最近议题。

> 标签

Goclaudeclaude-codeclicodex

暂无评论，来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类AI 编程
定价开源

> 相关工具

G
GitHub Copilot
GitHub 官方 AI 编程助手，覆盖补全、Chat 与 Agent 模式。
C
Cursor
AI 原生代码编辑器，对话改代码、多文件 Agent 与规则体系是其核心。
S
skills
Skills for Real Engineers. Straight from my .agents directory.