{
  "markdown": "# codemap 🗺️\n\n> **codemap — structural ground truth for coding agents.**\n> Resolves what your code actually imports, tells you what breaks if you change it, and is explicit about what it couldn't figure out.\n\n![License](https://img.shields.io/badge/license-MIT-blue.svg)\n![Go](https://img.shields.io/badge/go-1.24+-00ADD8.svg)\n![Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/JordanCoin/6ffe3276ddb8a7a7f08d50d649e567bd/raw/codemap-coverage.json)\n[![Run in Smithery](https://smithery.ai/badge/skills/jordancoin)](https://smithery.ai/skills?ns=jordancoin&utm_source=github&utm_medium=badge)\n\n![codemap screenshot](assets/codemap.png)\n\n## What it's for\n\nAn 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.\n\ncodemap computes three things:\n\n| | |\n|---|---|\n| **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. |\n| **Dependency graph** | Imports resolved through each ecosystem's real rules — not string matching. |\n| **Blast radius** | Who breaks if you change this file. |\n\nAnd 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.\n\n```bash\ncodemap .                        # structure + hubs\ncodemap --importers path/to/file # who depends on this\ncodemap --diff                   # what changed vs main\n```\n\n## Install\n\n```bash\n# macOS/Linux\nbrew tap JordanCoin/tap && brew install codemap\n\n# Windows\nscoop bucket add codemap https://github.com/JordanCoin/scoop-codemap\nscoop install codemap\n```\n\n> Other options: [Releases](https://github.com/JordanCoin/codemap/releases) | `go install` | build from source\n\n### CI / tarball install\n\nRelease tarballs ship `codemap` and the bundled rules but not the `ast-grep` executable, which `--deps` needs. Either install it separately:\n\n```bash\napk add --no-cache curl jq bash python3 py3-pip\n\nARCH=$(uname -m)\nif [ \"$ARCH\" = \"x86_64\" ]; then ARCH=\"amd64\"; elif [ \"$ARCH\" = \"aarch64\" ]; then ARCH=\"arm64\"; fi\n\nCODEMAP_VERSION=$(curl -fsSL https://api.github.com/repos/JordanCoin/codemap/releases/latest | jq -r '.tag_name' | tr -d 'v')\ncurl -fsSL \"https://github.com/JordanCoin/codemap/releases/download/v${CODEMAP_VERSION}/codemap_${CODEMAP_VERSION}_linux_${ARCH}.tar.gz\" \\\n  | tar xz -C /usr/local/bin/ codemap\n\npython3 -m pip install --no-cache-dir ast-grep-cli\n```\n\n…or use the self-contained `codemap-full` artifact, which bundles `codemap`, `ast-grep`, and `sg`:\n\n```bash\ncurl -fsSL \"https://github.com/JordanCoin/codemap/releases/download/v${CODEMAP_VERSION}/codemap-full_${CODEMAP_VERSION}_linux_${ARCH}.tar.gz\" \\\n  | tar xz -C /usr/local/bin/ codemap ast-grep sg\n```\n\n## Setup\n\nRun setup anywhere inside your git repo. Repo-scoped commands such as\n`setup`, `doctor`, `config`, `watch`, `skill`, `context`, `serve`, and\nmanaged hooks resolve the nearest git root automatically, including linked\nworktrees with a `.git` file.\n\n```bash\ncd /path/to/your/project\ncodemap setup\n```\n\n`codemap setup` configures Claude Code and Codex by default:\n\n- creates `.codemap/config.json` with auto-detected language filters\n- merges hooks into `.claude/settings.local.json` and `.codex/hooks.json`\n- configures MCP in `.mcp.json` and `.codex/config.toml`\n- hooks start and read daemon state at session start\n\nManaged 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.\n\n```bash\ncodemap setup --agent claude   # one agent only\ncodemap setup --agent codex\ncodemap setup --global         # user-scope, applies to every project\n```\n\n### Verify\n\n```bash\ncodemap doctor            # validate this project's integrations\ncodemap doctor --global   # validate user-scope configuration\n```\n\nDoctor 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.\n\n## Dependency resolution\n\n`--deps` and `--importers` resolve imports using each ecosystem's own rules rather than guessing from paths:\n\n| Ecosystem | Resolved via |\n|-----------|--------------|\n| **Go** | module path from `go.mod`; stdlib and third-party imports are not fuzzy-matched into local files |\n| **Rust** | `cargo metadata` — workspace membership, target kinds (lib/bin/test/bench/example/build), and `dev-dependencies` reachable from `#[cfg(test)]` blocks |\n| **JS/TS** | `package.json` `exports`/`imports` maps, npm/pnpm/Bun workspaces, Deno import maps, and `tsconfig` `rootDir`/`outDir` remapping (including `extends`) |\n| **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 |\n| **Everything else** | ast-grep import extraction with suffix and directory matching |\n\n### The coverage contract\n\nEvery dependency answer reports how much of it codemap actually stands behind:\n\n```bash\ncodemap --json --deps . | jq .coverage\n```\n\n```json\n{\n  \"status\": \"partial\",\n  \"sources\": [\n    { \"name\": \"ast-grep\", \"status\": \"authoritative\" },\n    { \"name\": \"cargo-metadata\", \"status\": \"mixed\",\n      \"detail\": \"2 of 5 Cargo manifests used fallback topology\" }\n  ],\n  \"issues\": []\n}\n```\n\n- `status` is `complete`, `partial`, or `unavailable`.\n- Each source reports `authoritative`, `mixed`, `fallback`, `timeout`, `unavailable`, or `failed`.\n- 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\".\n\nThe JSON payload is versioned (`schema_version: codemap.analysis/v1`) so consumers can depend on its shape.\n\n### Supported languages\n\n21 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.\n\n> Powered by [ast-grep](https://ast-grep.github.io/). Installed automatically with the Homebrew formula.\n\n## Commands\n\n```bash\ncodemap .              # structure view (respects .codemap/config.json)\ncodemap --diff         # what changed vs main\ncodemap --deps .       # dependency flow\ncodemap --importers f  # who imports a file\ncodemap blast-radius   # review bundle: diff + deps + importers\ncodemap collide        # rank open PRs by shared-file merge-order hazard\ncodemap handoff .      # save layered handoff for cross-agent continuation\ncodemap context        # machine-readable project context JSON\ncodemap doctor         # validate agent integrations\ncodemap skill list     # available agent skills\ncodemap watch start    # background daemon for live graph state\ncodemap serve          # HTTP API for non-MCP integrations\ncodemap mcp            # MCP server on stdio\ncodemap --version\n```\n\n### Options\n\nStandard linked Git worktrees automatically reuse the primary worktree's\n`.codemap/config.json` and project skills. Create the worktree with Git, an IDE,\nor any manager that uses standard linked-worktree metadata, then give the agent\nits absolute path:\n\n```bash\ngit worktree add <path> -b <branch> <base>\ncodemap -C /tmp/feature-worktree context\n```\n\nNormal CLI and plugin MCP calls need no `--setup-root`: central config and skills\ncome from the primary worktree, while handoffs, watcher files, and hook/session\nstate remain in the linked worktree. Independent clones have no trusted Git\nmetadata linking them, so sharing setup between them still requires an explicit\noverride:\n\n```bash\ncodemap -C /tmp/independent-clone --setup-root /path/to/original context\n```\n\n`-C`/`--project-root` selects the repository Codemap operates on.\n`--setup-root` explicitly reuses `<repository>/.codemap` policy and runtime state\nfrom another checkout. Both accept a repository or subdirectory; relative setup\npaths resolve from the project root.\n\n| Flag | Description |\n\n| Flag | Description |\n|------|-------------|\n| `-C, --project-root <repo>` | Operate on code in `<repo>` |\n| `--setup-root <repo>` | Explicitly reuse policy and runtime state from `<repo>/.codemap` |\n| `--depth, -d <n>` | Limit tree depth (0 = unlimited) |\n| `--only <exts>` | Only include files with these extensions |\n| `--exclude <patterns>` | Exclude files matching patterns |\n| `--diff` | Show files changed vs main branch |\n| `--ref <branch>` | Branch to compare against (with `--diff`) |\n| `--deps` | Dependency flow mode |\n| `--importers <file>` | Check who imports a file |\n| `--skyline` | City skyline visualization |\n| `--animate` | Animate the skyline (with `--skyline`) |\n| `--json` | Output JSON |\n\n> Flags come before the path/URL: `codemap --json github.com/user/repo`\n\n**Pattern matching** needs no quotes: `.png` matches any `.png` file, `Fonts` matches any `/Fonts/` directory, `*Test*` is a glob.\n\n## Modes\n\n### Diff\n\n```bash\ncodemap --diff\ncodemap --diff --ref develop\n```\n\n```\n╭─────────────────────────── myproject ──────────────────────────╮\n│ Changed: 4 files | +156 -23 lines vs main                      │\n╰────────────────────────────────────────────────────────────────╯\n├── api/\n│   └── (new) auth.go         ✎ handlers.go (+45 -12)\n└── ✎ main.go (+29 -3)\n\n⚠ handlers.go is used by 3 other files\n```\n\n### Dependency flow\n\n```bash\ncodemap --deps .\n```\n\n```\n╭──────────────────────────────────────────────────────────────╮\n│                    MyApp - Dependency Flow                   │\n├──────────────────────────────────────────────────────────────┤\n│ Go: chi, zap, testify                                        │\n╰──────────────────────────────────────────────────────────────╯\n\nBackend ════════════════════════════════════════════════════\n  server ───▶ validate ───▶ rules, config\n  api ───▶ handlers, middleware\n\nHUBS: config (12←), api (8←), utils (5←)\n```\n\n### Blast radius\n\nWho breaks if you change a file:\n\n```bash\ncodemap --importers config/config.go\n```\n\n```\n⚠️  HUB FILE: config/config.go\n   Imported by 21 files - changes have wide impact!\n\n   Dependents:\n   • cmd/hooks.go\n   • mcp/find_guidance.go\n   ...\n```\n\nFor a review bundle in one command — Markdown, text, or a single JSON object:\n\n```bash\ncodemap blast-radius --ref main .\ncodemap blast-radius --json --ref main .\ncodemap blast-radius --text --ref main .\n```\n\n### Skyline\n\n```bash\ncodemap --skyline --animate\n```\n\n![codemap skyline](assets/skyline-animated.gif)\n\n### Remote repos\n\nAnalyze any public GitHub or GitLab repo without cloning it yourself:\n\n```bash\ncodemap github.com/anthropics/anthropic-cookbook\ncodemap gitlab.com/user/repo\n```\n\nShallow-clones to a temp directory and cleans up. If you already have the repo locally, codemap uses your copy.\n\n## Agent integration\n\n### Hooks\n\nAutomatic context at session start, before and after edits, and at compaction.\n→ See [docs/HOOKS.md](docs/HOOKS.md)\n\nThe prompt-submit hook classifies intent, surfaces hub-file risk, shows your working set, matches relevant skills, and emits structured markers (`<!-- codemap:intent -->`) for tool consumption.\n\n### MCP\n\n`codemap mcp` serves 16 tools over stdio:\n\n| Category | Tools |\n|----------|-------|\n| Structure | `get_structure`, `find_file`, `get_hubs`, `get_file_context` |\n| Dependencies | `get_dependencies`, `get_importers`, `get_diff` |\n| Session | `get_working_set`, `get_activity`, `get_handoff` |\n| Daemon | `start_watch`, `stop_watch`, `status` |\n| Skills | `list_skills`, `get_skill` |\n| Discovery | `list_projects` |\n\n`get_structure`, `get_diff`, `get_importers`, `get_dependencies`, and `get_handoff` declare an `OutputSchema` and return typed structured content alongside the text response, so callers get parseable results instead of prose.\n\n### Codex\n\n`codemap setup` configures Codex alongside Claude. For Codex only:\n\n```bash\ncodemap setup --agent codex          # project hooks + MCP\ncodemap plugin install               # global plugin (MCP + skills), activated by default\ncodemap doctor --agent codex         # validate; reports CLI and Desktop runtimes separately\n```\n\n**After upgrading the codemap binary**, agent integrations do not update themselves:\n\n```bash\ncodemap plugin install   # Codex only, once per Codex environment\ncd /path/to/project && codemap setup && codemap doctor   # both agents, per project\n```\n\n`codemap plugin install` refreshes the plugin for CLI and Desktop sharing a Codex environment, and migrates the current project when run inside one — but it does not discover every configured project. Start a new task or session afterward, and re-check hook trust if Codex asks.\n\n> `codemap doctor` probes executables recorded in project-local config (`.codex/config.toml`, `.mcp.json`), so running it inside an untrusted repo executes a repo-chosen path. Doctor bounds this by requiring absolute paths and a recognized argument shape, but treat it like any command that honors project-local config.\n\n## Project config\n\nPer-project defaults in `.codemap/config.json`, so you don't pass `--only`/`--exclude`/`--depth` every time. Hooks respect it too.\n\n```bash\ncodemap config init   # auto-detect top extensions, write config\ncodemap config show   # display current config\n```\n\n```json\n{\n  \"only\": [\"rs\", \"sh\", \"sql\", \"toml\", \"yml\"],\n  \"exclude\": [\"docs/reference\", \"docs/research\"],\n  \"depth\": 4,\n  \"mode\": \"auto\",\n  \"guidance\": {\n    \"missing_extension_hints\": true,\n    \"ignored_extensions\": []\n  },\n  \"budgets\": {\n    \"session_start_bytes\": 30000,\n    \"diff_bytes\": 15000,\n    \"max_hubs\": 8\n  },\n  \"routing\": {\n    \"retrieval\": { \"strategy\": \"keyword\", \"top_k\": 3 },\n    \"subsystems\": [\n      {\n        \"id\": \"watching\",\n        \"paths\": [\"watch/**\"],\n        \"keywords\": [\"hook\", \"daemon\", \"events\"],\n        \"docs\": [\"docs/HOOKS.md\"],\n        \"agents\": [\"codemap-hook-triage\"]\n      }\n    ]\n  },\n  \"drift\": {\n    \"enabled\": true,\n    \"recent_commits\": 10,\n    \"require_docs_for\": [\"watching\"]\n  }\n}\n```\n\nAll fields are optional; CLI flags always override config. When an MCP file search finds real matches hidden by `only`, codemap reports the paths and suggests which extensions to add — set `guidance.missing_extension_hints: false` to disable.\n\n## Skills\n\nMarkdown files that give agents context-aware guidance, matched against intent, mentioned files, and project languages.\n\n```bash\ncodemap skill list\ncodemap skill show hub-safety\ncodemap skill init            # custom skill template\n```\n\n| Builtin | Activates when |\n|---------|---------------|\n| `hub-safety` | Editing hub files (3+ importers) |\n| `refactor` | Restructuring, renaming, moving code |\n| `test-first` | Writing tests, TDD workflows |\n| `explore` | Understanding how code works |\n| `handoff` | Switching between AI agents |\n| `config-setup` | `.codemap/config.json` is missing, boilerplate, or mismatched to the stack |\n\nDrop a `.md` file with YAML frontmatter in `.codemap/skills/` to add your own — project-local skills override builtins, no Go code required:\n\n```yaml\n---\nname: my-skill\ndescription: When this skill should activate\nkeywords: [\"relevant\", \"keywords\"]\nlanguages: [\"go\"]\n---\n\n# Instructions for the AI agent\n```\n\n## Context protocol\n\nOne command that gives any AI tool codemap's full intelligence:\n\n```bash\ncodemap context                       # full JSON envelope\ncodemap context --for \"refactor auth\" # with pre-classified intent + matched skills\ncodemap context --compact             # minimal, for token-constrained agents\n```\n\nReturns a `ContextEnvelope` with project metadata, dependency-graph evidence, intent classification, working set, matched skills, and a handoff reference. If fresh graph evidence is unavailable, hub counts are `null` and risk is `unknown` instead of being inferred from stale state. Anything that can shell out gets code-aware context.\n\n## HTTP API\n\n```bash\ncodemap serve --port 9471\n```\n\n| Endpoint | Returns |\n|----------|---------|\n| `GET /api/context?intent=refactor+auth` | Full context envelope |\n| `GET /api/context?compact=true` | Minimal envelope |\n| `GET /api/skills` | All skills with metadata |\n| `GET /api/skills?language=go&category=refactor` | Filtered skill matches |\n| `GET /api/skills/<name>` | Full skill body |\n| `GET /api/working-set` | Current session's active files |\n| `GET /api/health` | Health check |\n\nBinds to `127.0.0.1`; use `--host 0.0.0.0` to expose.\n\n## Cross-agent handoff\n\nWhen you switch agents (Claude → Codex → Cursor), codemap tracks who worked and what they touched:\n\n```json\n{\n  \"agent_history\": [\n    {\"agent_id\": \"claude-code\", \"files_edited\": [\"cmd/hooks.go\", \"main.go\"], \"ended_at\": \"...\"},\n    {\"agent_id\": \"codex\", \"files_edited\": [\"scanner/types.go\"], \"ended_at\": \"...\"}\n  ]\n}\n```\n\nAgent detection is automatic via environment variables. History carries across sessions, capped at 20 entries, in `.codemap/handoff.latest.json`.\n\n## Roadmap\n\nShipped: diff/skyline/deps modes, project config, Claude + Codex hooks and MCP, cross-agent handoff, remote repos, intent routing, skills framework, context protocol, HTTP API, build-system-aware resolution for Go/Rust/JS/TS, and the versioned coverage contract.\n\nNext:\n\n- [ ] Per-query coverage — report only the gaps that affect *this* answer, not the whole scan ([#111](https://github.com/JordanCoin/codemap/issues/111))\n- [ ] Per-edge provenance — which resolver produced each edge, so \"why does codemap think A imports B?\" is answerable\n- [ ] Community skill registry (`codemap skill add <name>`)\n- [ ] Enhanced analysis (entry points, key types)\n\n## Contributing\n\nFork → branch → commit → PR. See [CONTRIBUTING.md](CONTRIBUTING.md) before adding a new language.\n\n## License\n\nMIT\n",
  "bytes": 18095,
  "sha": "6a3f264ffd99efae4ee5fcd63be86f1b5826efcddb8d8f099186a9f99d6f57e8",
  "repo_slug": "jordancoin/codemap",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/skl_jordancoin_codemap_claude_skills_codemap_0eb372ac/readme"
}