codemap: dependency resolution for coding agents, with coverage stated up front
a project brain for your AI. Give LLMs instant architectural context without burning tokens
At a glance
- What is it?
- codemap is a Go CLI that computes a repository's structure map, resolves imports through each ecosystem's own rules, and reports how much of the resulting dependency graph it can actually stand behind. The coverage contract is the interesting part, and the ast-grep dependency is the part that will bite you in CI.
- Who is it for?
- Adopt codemap if you run Claude Code or Codex against a multi-language repository and want agents to stop guessing at import topology. Skip it if your work is single-language and small enough that an agent can read the whole tree, because the setup, the ast-grep dependency and the daemon hooks are overhead you will not recover.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 4 days ago.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The question an agent cannot answer by reading source text
A model reading a repository sees what a file says. It does not cheaply see what depends on that file, because that answer is not in the source. It lives in go.mod, in Cargo workspace membership, in package.json exports maps, in tsconfig path aliases. The README states this directly: the answer lives in config files, not in the source text. codemap's stated purpose is to compute that answer and hand it to an agent before the agent starts editing.
The audience is narrow and specific. You are running Claude Code or Codex against a repository that spans more than one ecosystem, or one large enough that loading the tree into context is expensive. The three outputs map to three agent behaviours: orientation for a cold start with no memory, a dependency graph for reasoning about module boundaries, and blast radius for deciding what a change will break. The fourth output, the coverage status, is the one that changes how you use the tool rather than what it computes.
Resolution per ecosystem, not string matching against paths
The mechanism is per-ecosystem resolution. Go imports resolve through the module path declared in go.mod, and the README is explicit that stdlib and third-party imports are not fuzzy-matched into local files. Rust goes through cargo metadata, which supplies workspace membership, target kinds (lib, bin, test, bench, example, build), and dev-dependencies reachable from #[cfg(test)] blocks. JS and TS resolve through package.json exports and imports maps, npm, pnpm and Bun workspaces, Deno import maps, and tsconfig rootDir/outDir remapping including extends chains. Dart and Flutter resolve package: URIs within the owning package's lib/, and undeclared or duplicate package names fail closed rather than resolving to a guess.
Everything outside those four ecosystems falls back to ast-grep import extraction with suffix and directory matching. That fallback is weaker by construction, and the coverage report is how you find out you are on it. The README lists 21 ast-grep language rules covering Go, Python, JavaScript, JSX, TypeScript, TSX, Rust, Ruby, C, C++, Java, Swift, Dart, Kotlin, C#, PHP, Bash, Lua, Scala, Elixir and Solidity, plus CUE package edges through lexical import extraction, which the README notes is not an ast-grep rule. Breadth here is real but shallow: a language appearing in the rule list means imports are extracted, not that they are resolved with the fidelity Go and Rust get.
The coverage contract is the actual design decision
Most tools in this space return a graph and let you assume it is complete. codemap attaches provenance to every dependency answer. The README gives the shape: codemap --json --deps . | jq .coverage returns a status of complete, partial or unavailable, plus a per-source list where each source reports authoritative, mixed, fallback, timeout, unavailable or failed. The example in the README shows a partial status with ast-grep authoritative and cargo-metadata mixed, with the detail string "2 of 5 Cargo manifests used fallback topology".
The behaviour on failure is the part worth noting. A timed-out or failed scan returns an empty result with provenance, not a silent empty graph and not a hard error. The README's framing is that an agent can then tell "nothing imports this" apart from "I couldn't tell". That distinction matters more than the graph itself, because an agent that reads an empty importer list as authoritative will delete a file that six packages depend on. The JSON payload carries schema_version: codemap.analysis/v1, so a consumer can pin against the shape. If you are wiring codemap into your own tooling rather than into an agent, that version field is the contract you should be reading.
Install, setup and the ast-grep dependency you will trip over
Homebrew and Scoop are the supported package paths: brew tap JordanCoin/tap && brew install codemap, or scoop bucket add codemap https://github.com/JordanCoin/scoop-codemap followed by scoop install codemap. The Homebrew formula installs ast-grep automatically.
The CI path does not. The README states plainly that release tarballs ship codemap and the bundled rules but not the ast-grep executable, which --deps needs. The documented workaround is to fetch the tarball, extract codemap to /usr/local/bin, and install ast-grep separately with python3 -m pip install --no-cache-dir ast-grep-cli. The alternative is the codemap-full artifact, which bundles codemap, ast-grep and sg in one tarball. If you are building a container image, choose codemap-full and skip the pip step; the README's own CI snippet includes apk add for curl, jq, bash, python3 and py3-pip purely to support the split install.
Setup is repo-scoped. Running codemap setup anywhere inside a git repo resolves the nearest git root, including linked worktrees where .git is a file rather than a directory. It creates .codemap/config.json with auto-detected language filters, merges hooks into .claude/settings.local.json and .codex/hooks.json, and configures MCP in .mcp.json and .codex/config.toml. Managed entries record the verified absolute path of the running codemap so agents do not depend on your shell PATH. That detail is a maintenance obligation: rerun setup if that path changes, which it will after a version manager switch or a reinstall. codemap setup --agent claude or --agent codex narrows the target, and --global writes user-scope configuration for every project. Verification is codemap doctor, with codemap doctor --global for the user scope; doctor checks project scope and falls back to user scope, reporting which one satisfied each check. For Codex you still have to trust the hooks from /hooks in the CLI or Settings, then start a new session.
Where codemap is the wrong tool
The four ecosystems with real resolution rules are Go, Rust, JS/TS and Dart/Flutter. Everything else is ast-grep extraction with suffix and directory matching. If your repository is primarily C++, Java, Swift or Solidity, you are on the fallback path and the graph will be coarser than the README's framing suggests. The coverage report will tell you this, but you have to read it, and the tool does not prevent you from feeding a fallback-quality graph to an agent that treats it as ground truth.
The second limitation is operational. codemap setup writes into .claude/settings.local.json, .codex/hooks.json, .mcp.json and .codex/config.toml, and the hooks start and read daemon state at session start. That is a persistent process and a set of committed or semi-committed config files, not a one-shot command. On a small single-language repository, the agent can read the tree directly and the daemon is pure overhead. The README also routes several commands through the git root, so a repository that is not a git repo, or a checkout where git is unavailable, loses the repo-scoped commands entirely.
Third, the README does not document performance characteristics, memory use, or behaviour on very large monorepos. There is no stated repository size limit and no guidance on incremental scanning cost. If you have a monorepo with thousands of packages, you are the one who finds out.
How this differs from an LSP or a plain grep for imports
A language server answers the same dependency question with higher fidelity, because it type-resolves rather than parsing import statements. The difference is scope and cost. An LSP is per-language, needs a working toolchain for each language present, and is designed for an editor session rather than for producing a serialisable artifact an agent can read in one shot. codemap produces a versioned JSON payload with a coverage block, and it does so across ecosystems in one invocation.
A grep for import statements is the other common approach, and it is what codemap's fallback path effectively is, done properly with ast-grep. The gap shows up exactly where the README says it does: tsconfig path aliases, package.json exports maps, Cargo workspace membership. A grep finds the string import and stops. codemap's own README example of a partial result, where two of five Cargo manifests used fallback topology, is a case a grep would report as complete and codemap reports as partial. That difference in honesty is the reason to pick it over a shell script, and it is also the reason the coverage block is the first thing you should look at rather than the last.
Maintenance, licensing and what to check before you commit
The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is a permissive licence with no copyleft obligation, but codemap bundles ast-grep, and the licence of the bundled ast-grep binary is a separate question from codemap's own. The README does not state ast-grep's licence. Check it before you redistribute the codemap-full artifact; I am not giving legal advice and this is the specific thing to verify with whoever handles licensing on your side.
Maintenance cost is concentrated in two places. The managed hook entries record an absolute path to the codemap binary, so every reinstall, version manager switch or container rebuild that changes that path requires running codemap setup again. The README says this outright. Second, the project ships releases frequently: v4.5.1 on 2026-09-05, v4.5.0 on 2026-08-29, v4.4.2 on 2026-08-22. Three releases in two weeks is a fast cadence, and while schema_version: codemap.analysis/v1 gives you a pinning point for the JSON shape, the config files codemap writes into your editor settings are not versioned the same way. Pin a version in CI rather than tracking latest.
The commands worth knowing before you decide are the short ones. codemap . gives the structure view with the most-imported files called out. codemap --importers path/to/file answers who depends on a file. codemap blast-radius bundles diff, deps and importers for review. codemap collide ranks open PRs by shared-file merge-order hazard, which is the one command here that has nothing to do with agents and everything to do with merge sequencing. Start with codemap doctor after setup, then read the coverage block on your largest package before you let an agent act on any of it.
Editorial conclusion
Adopt codemap if you run Claude Code or Codex against a multi-language repository and want agents to stop guessing at import topology. Skip it if your work is single-language and small enough that an agent can read the whole tree, because the setup, the ast-grep dependency and the daemon hooks are overhead you will not recover. Before committing, run codemap setup, then codemap doctor, then codemap --json --deps . and read the coverage block: if status comes back partial or unavailable on your primary language, the graph is not something you should let an agent act on.
Community notes