Mercator AI – Mapeamento de Codebase com Detecção de Mudanças
shihwesley/mercator-ai
Mapeia codebases com detecção Merkle-based de mudanças, sem re-scanear arquivos inalterados
Ver no GitHubAgent que mapeia codebases de qualquer tamanho usando subagentes paralelos e árvores Merkle para detecção O(1) de mudanças. Elimina re-varreduras desnecessárias através de hashing SHA-256 e oferece auto-refresh em commits com custo zero de tokens via hooks pós-commit.
Instalação
npx convez-ai shihwesley/mercator-ai1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Mapear arquitetura de grandes projetos sem consumir tokens em mudanças menores
- Manter documentação de codebase automaticamente atualizada após commits
- Explorar repositórios complexos com protocolo map-first para agents IA
Veredito

Solução técnica robusta para o problema real de manter contexto de codebase sem desperdício de tokens. A abordagem Merkle é elegante e o auto-refresh elimina fricção; ideal para desenvolvedores que trabalham com agents em codebases maiores e em evolução.
README
A tradução para o português deste README ainda está na fila.
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 flowsdocs/.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:
- Detects git commits
- Runs
--diffagainst the manifest - Refreshes hashes for changed files (~2s, zero tokens)
- Invalidates TLDR cache entries (if present)
- Flags structural changes that need a full
/mercator-airun
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:
root_hash: "a1b2c3d4e5f6" <- O(1) "anything changed?"
├── src/: "f1e2d3c4b5a6" <- O(1) "src/ changed?"
│ ├── api/: "..." <- drill to changed module
│ │ ├── routes.ts: "..." <- individual file hash
│ │ └── auth.ts: "..."
│ └── lib/: "..."
└── tests/: "..."
- O(1) staleness check: Compare root hash
- O(log n) change localization: Walk down tree to find changed modules
- Works without git: Pure hash-based comparison
Output Structure
The generated docs/CODEBASE_MAP.md includes:
- System Overview — Mermaid architecture diagram
- Directory Structure — Annotated file tree
- Module Guide — Per-module documentation with purpose, exports, dependencies
- Data Flow — Mermaid sequence diagrams for key flows
- Conventions — Naming, patterns, style
- Gotchas — Non-obvious behaviors and warnings
- Navigation Guide — How to add features, modify systems
Updating
Enable auto-updates (recommended)
After installing, enable auto-updates so you get new versions automatically at startup:
- Run
/pluginto open the plugin manager - Go to the Marketplaces tab
- Select mercator-ai
- Select Enable auto-update
Claude Code will check for updates on every startup and notify you when a new version is available.
Manual update
/plugin marketplace update mercator-ai
/plugin update mercator-ai@mercator-ai
For maintainers
Use the release script to publish updates:
./scripts/release.sh patch # 1.0.0 → 1.0.1 (bug fix)
./scripts/release.sh minor # 1.0.0 → 1.1.0 (new feature)
./scripts/release.sh major # 1.0.0 → 2.0.0 (breaking change)
Attribution
Mercator AI is built upon Cartographer by Bootoshi. See ATTRIBUTION.md for details on what came from the original and what was added.
License
MIT — See LICENSE for dual copyright notice.