cartograph

Cartograph

Cartograph is task-shaped repo context for coding agents. It ships a CLI, an MCP server, user-scope install adapters for Claude Code and OpenClaw, and packaged agent assets for documentation-heavy workflows.

• npm: @anthony-maio/cartograph
• MCP Registry: io.github.anthony-maio/cartograph
• Quickstart: cartograph.making-minds.ai

Instead of dumping an entire repository into context, Cartograph ranks the files that matter, maps dependencies, caches structured artifacts, and lets the next tool or agent pick up from those artifacts.

The primary workflow is:

1. analyze to map the repo
2. packet to prepare the work
3. context to load the minimum files

wiki, host installs, and benchmarks are secondary surfaces built around that core path.

Install

npm install
npm run build

For global use from npm:

npm install -g @anthony-maio/cartograph

For MCP host discovery via the official registry:

• io.github.anthony-maio/cartograph
• Registry listing

For Claude Code plugin install from this public repo:

/plugin marketplace add anthony-maio/cartograph
/plugin install cartograph@making-minds-tools

For global use from a local checkout:

npm install -g .

See CONTRIBUTING.md for the development workflow and SECURITY.md for vulnerability reporting.

Claude Code Plugin

This repo also acts as a Claude Code plugin marketplace. The cartograph plugin bundles:

• a plugin-scoped Cartograph MCP server
• slash commands: /cartograph:analyze, /cartograph:context, /cartograph:wiki
• the use-cartograph and repo-surveyor skills
• the documentation-agent bundle: repo-scout, dependency-tracer, context-picker, api-surface-writer, and wiki-writer

Install it with:

/plugin marketplace add anthony-maio/cartograph
/plugin install cartograph@making-minds-tools

Primary Workflow

If you only remember one thing, remember this:

cartograph analyze <repo> --static
cartograph packet <repo> --type <type> --task "<task>"
cartograph context <repo> --task "<task>" --json

• analyze maps the repo and tells you what matters.
• packet turns a concrete job into a reusable working artifact.
• context gives the next agent the smallest useful file set.

Command Surface

cartograph analyze <repo> [options]
cartograph packet <repo> --type <type> --task "<task>" [--changed <paths...>]
cartograph context <repo> --task "<task>" [options]
cartograph wiki <repo> [options]
cartograph export <run-id> --to <path> [--artifact <name>]
cartograph install <claude|openclaw|mcp>
cartograph uninstall <claude|openclaw|mcp>
cartograph doctor [target] [--json]
cartograph mcp

Legacy compatibility still works:

cartograph <repo> --static
cartograph <repo> -c "trace auth flow"

CLI Usage

# Map the repo
cartograph analyze ./my-project --static

# Prepare a concrete job
cartograph packet ./my-project --type bug-fix --task "fix auth refresh bug" --changed src/auth/service.ts tests/auth/service.test.ts

# Load the minimum file set for that job
cartograph context ./my-project --task "add user authentication" --json

# Force embedded snippets when you really want them
cartograph analyze ./my-project --static --json --include-contents

# Full wiki output
cartograph wiki ./my-project -p gemini -k $CARTOGRAPH_API_KEY -o wiki.md

# Export a cached artifact to an explicit path
cartograph export run-abc123 --to ./artifacts/wiki.md

# Run the MCP server directly
cartograph mcp

For small repos, analyze --static --json now defaults to compact output instead of embedding top-file contents. That keeps tiny repos readable and lets direct file reads stay cheaper than a giant JSON blob. Use --include-contents when you explicitly want embedded snippets.

The default markdown output from analyze --static is human-first: it highlights what matters, surfaces dependency hubs, and recommends the next commands instead of dumping raw file contents immediately.

Providers

• gemini
• openai
• openrouter
• ollama

Set the API key with --key or CARTOGRAPH_API_KEY. Ollama does not require a key.

Cache Model

Cartograph writes successful runs into the user cache by default:

• Windows: %USERPROFILE%\\.cartograph\\cache
• POSIX: ~/.cartograph/cache

Each run gets a manifest plus named artifacts, which keeps agent handoffs lightweight and makes cartograph export deterministic.

Host Installs

Cartograph uses an explicit hybrid install model. Installing the package does not modify Claude Code, OpenClaw, or MCP host configs automatically.