Single package repo analysis for coding agents

Map the repo before you burn context.

Cartograph is a CLI-first repo analysis package with an optional MCP server, user-scope host installs, and two packaged skills that keep agent context tight without losing structure.

Use it against local repos or GitHub repos. Rank the files that matter, trace dependency hubs, pull only the context needed for a task, and hand structured artifacts to Claude Code, OpenClaw, or any agent that can run a shell command.

See the 5-minute quickstart npm package
CLI
first, MCP optional
2 skills
same output contract
1 package
Claude, OpenClaw, MCP
Zero to first result
npm install -g @anthony-maio/cartograph

cartograph analyze ./my-project --static --json
cartograph context ./my-project --task "add auth" --json

cartograph install claude
cartograph install openclaw
cartograph install mcp
Outputs: ranked files, dependency hubs, minimal task context same contract across both skills
Why Cartograph

Most repo handoffs waste tokens on the wrong files.

Dumping an entire codebase into context is slow, expensive, and noisy. Cartograph gives agents a smaller, better map: entry points, fan-in, API surfaces, dependency hubs, and task-scoped context chosen on purpose.

Without structure

Repo orientation becomes a context tax.

  • Agents read broad file trees just to get started.
  • Important wiring gets buried under leaf modules and tests.
  • Docs tasks pull too much parent-context prose.
  • Every new host integration rebuilds the same survey logic.
With Cartograph

The repo gets reduced to the useful shape.

  • CLI and MCP expose the same core analysis engine.
  • Artifacts land in user cache instead of dirtying the repo.
  • Claude Code and OpenClaw get packaged skills out of the box.
  • Downstream agents consume the same output contract either way.
5-minute quickstart

Install once, map a repo, then wire your host.

This is the fastest useful path. You do not need MCP to start. Install the package, run the CLI, and only add host integrations where they help.

01

Install the package

Publish path is scoped. The executable remains cartograph.

npm
npm install -g @anthony-maio/cartograph
02

Analyze a repo

Start with static analysis to get ranked files, edges, and top file contents.

local or GitHub
cartograph analyze ./my-project --static --json
cartograph analyze https://github.com/anthony-maio/cartograph --static --json
03

Pull task-scoped context

Ask for the smallest file set that supports the task you actually want to do.

task context
cartograph context ./my-project --task "add user authentication" --json
04

Install only the host you want

Hybrid install model: explicit, user-scope, and non-invasive by default.

host installs
cartograph install claude
cartograph install openclaw
cartograph install mcp
05

Generate docs or export artifacts

Keep working artifacts in user cache. Export only when a human needs a concrete path.

docs and export
cartograph wiki ./my-project --static
cartograph export run-abc123 --to ./artifacts/wiki.md
Host installs

One package, three host paths.

Keep the core engine universal. Add host-specific behavior only where it helps.

Claude Code

Skill and agent bundle

Installs user-scope skills plus the balanced documentation-agent set.

  • use-cartograph
  • repo-surveyor
  • repo-scout, dependency-tracer, context-picker, api-surface-writer, wiki-writer
OpenClaw

Skill pack plus OpenProse templates

Installs user-scope skills with bundled templates for repo docs and task-context flows.

  • use-cartograph
  • repo-surveyor
  • OpenProse templates for repo docs and task context
MCP

Optional server path

Use MCP only when the host wants tool wiring instead of shell calls.

  • analyze_repo
  • get_file_contents
  • Reusable config snippet under the user cache
Two-skill model

Tool-first when available. Manual fallback when not.

The point of shipping both skills is not redundancy. It is portability. Different acquisition path, same downstream contract.

use-cartograph

Use when the CLI or MCP server is available. It tells the host to run Cartograph directly for repo orientation, task context, documentation, and artifact export.

repo-surveyor

Use when Cartograph itself is unavailable or when you want a manual verification pass. It teaches the host how to replicate Cartograph behavior with targeted file discovery, ranking, dependency tracing, and synthesis.

Shared output contract

Downstream agents see the same shape either way.

key files
dependency hubs
minimal task context
doc-ready summary
Examples

Common first runs.

Local repo orientation
cartograph analyze ./my-project --static --json

Use this to get the first ranked map of a repo before touching code.

Task-scoped handoff
cartograph context ./my-project --task "trace the auth flow" --json

Use this when the next agent needs the smallest useful file set for a specific change.

Documentation output
cartograph wiki ./my-project --static

Use this to generate a structured docs pass without rereading the entire tree by hand.