convez.ai
AgenteDevOps & InfraestruturaIntermediário
shihwesley

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 GitHub
InicialPluginScore · de 0 a 100

Agent 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-ai

1 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

Estrelas
4
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 8 meses
Versão
v1.0.1
Issues abertas
0
Contribuidores
1

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?

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.

FeatureCartographerMercator AI
Codebase scanningToken countingToken counting + SHA-256 hashing
Change detectiongit log --sinceMerkle tree O(1) root hash comparison
Update modeRe-scan entire codebase--diff against manifest, only re-explore changed files
Staleness preventionManual re-runPost-commit hook auto-refreshes manifest (zero tokens)
ManifestNonedocs/.mercator.json with full merkle tree
TLDR integrationNoneAuto-invalidates cached summaries for changed files
Exploration protocolNoneMap-first protocol documentation for agents
Git dependencyRequired for updatesOptional — 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.

TaskBlind ScanMap-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:

  1. Run /plugin to open the plugin manager
  2. Go to the Marketplaces tab
  3. Select mercator-ai
  4. 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.

Ver o original no GitHub

Bom para

Relacionados