mercator-ai

Mercator AI

Merkle-enhanced codebase mapping for AI agents. Maps codebases of any size using parallel subagents, with O(1) change detection and zero-token staleness prevention.

Built upon Bootoshi's Cartographer, enhanced with Merkle tree change detection, post-commit hooks, and a map-first exploration protocol.

Table of Contents

• What's Different from Cartographer?
• Install
• Usage
• How It Works
• Scanner CLI
• Map-First Exploration Protocol
• Merkle Tree
• Output Structure
• Updating
• Attribution
• License

What's Different from Cartographer?

Cartographer is a Claude Code plugin by Bootoshi that maps codebases using parallel subagents and token counting. Mercator AI started as a fork and adds merkle-based change detection so you don't re-scan files that haven't changed.

Feature	Cartographer	Mercator AI
Codebase scanning	Token counting	Token counting + SHA-256 hashing
Change detection	git log --since	Merkle tree O(1) root hash comparison
Update mode	Re-scan entire codebase	--diff against manifest, only re-explore changed files
Staleness prevention	Manual re-run	Post-commit hook auto-refreshes manifest (zero tokens)
Manifest	None	docs/.mercator.json with full merkle tree
TLDR integration	None	Auto-invalidates cached summaries for changed files
Exploration protocol	None	Map-first protocol documentation for agents
Git dependency	Required for updates	Optional — hash-based diff works without git

Install

Add the marketplace and install

/plugin marketplace add shihwesley/shihwesley-plugins
/plugin install mercator-ai@shihwesley-plugins

Or via CLI:

claude plugin marketplace add shihwesley/shihwesley-plugins
claude plugin install mercator-ai@shihwesley-plugins

Manual (GitHub)

git clone https://github.com/shihwesley/shihwesley-plugins.git ~/.claude/plugins/mercator-ai

Dependencies

The scanner requires tiktoken. With UV (recommended), it's automatic:

uv run scan-codebase.py  # tiktoken auto-installed

Without UV:

pip install tiktoken

Usage

Map a codebase

/mercator-ai

Or say: "map this codebase", "create codebase map", "document the architecture"

This creates:

• docs/CODEBASE_MAP.md — Architecture documentation with diagrams, module guides, data flows
• docs/.mercator.json — Merkle manifest for change tracking

Check for changes (O(1))

uv run scan-codebase.py . --diff docs/.mercator.json

Returns instantly: has_changes: true/false with lists of changed/added/removed files.

Auto-refresh on commit

The post-commit hook (hooks/mercator-auto-refresh.sh) automatically:

1. Detects git commits
2. Runs --diff against the manifest
3. Refreshes hashes for changed files (~2s, zero tokens)
4. Invalidates TLDR cache entries (if present)
5. Flags structural changes that need a full /mercator-ai run

Cost: ~2 seconds of Python. No API calls. No tokens.

How It Works

flowchart TD
    A["/mercator-ai invoked"] --> B["1. scan-codebase.py<br>Recursive file tree<br>Token count + SHA-256<br>Merkle tree + root hash"]
    B --> C["2. Plan subagent assignments<br>Group files by module<br>Balance token budgets<br>Skip unchanged modules"]
    C --> D["3. Spawn Sonnet subagents<br>(parallel — one per module group)<br>Read files, analyze dependencies<br>Return structured summaries"]
    D --> E["4. Synthesize reports<br>Merge subagent outputs<br>Build architecture diagrams<br>Create navigation guides"]
    E --> F["5. Write outputs<br>docs/CODEBASE_MAP.md<br>docs/.mercator.json<br>Update CLAUDE.md"]
    F --> G["6. Post-commit hook<br>Auto-refresh manifest on commit<br>Zero tokens, ~2 seconds"]

Map-First Exploration Protocol

See docs/MAP_FIRST_PROTOCOL.md for the full protocol.

TL;DR: Always read docs/CODEBASE_MAP.md before Glob/Grep. Use the manifest to skip unchanged files. Target specific files based on the map.

Task	Blind Scan	Map-First
"Where is auth?"	~15k tokens	~2k tokens
"Understand API layer"	~8k tokens	~1.5k tokens
"Any changes?"	~15k tokens	~50 tokens

Merkle Tree

The .mercator.json manifest contains a hierarchical merkle tree: