LayerMap

LayerMap

Inglês · 中文

_{Uma sessão real do Claude Code em Miniflux, reproduzida: uma chamada de mapa encontra todos os endpoints, e então o agente os confirma no código-fonte.}

Um mapa em camadas do seu código para agentes de programação. O LayerMap dá ao Claude Code, Codex, DeepSeek Harness e outros clientes MCP três ferramentas somente leitura que respondem, em uma única chamada, o que um agente normalmente descobre com dezenas de buscas:

• O que chama isso, e o que mudar isso afeta? Chamadores rastreados até 8 níveis, até as rotas HTTP, handlers, jobs e comandos de onde partem.
• O que isso chama? Chamados até 8 níveis.
• O que há aqui? Módulos, as declarações de cada arquivo e cada uso de um símbolo.

Ele mapeia TypeScript, JavaScript, Go, Python e Java com o compilador de cada linguagem, então chamadas através de interfaces, classes base, templates e decorators são resolvidas como o compilador as resolve, incluindo aquelas que a busca por texto não encontra.

Exemplo

Em Miniflux, uma chamada em Storage.MarkFeedAsRead encontra todas as quatro formas de uma requisição chegar até ele, cada uma com sua rota:

DECLARATION internal/storage/entry.go: Storage.MarkFeedAsRead m656-680 exported
  ← called by internal/api/feed.go: handler.markFeedAsRead m140-155 @149
  ← called by internal/fever/handler.go: handler.handleWriteFeeds m492-519 @508
  ← called by internal/googlereader/handler.go: handler.markAllAsReadHandler m1261-1338 @1311
  ← called by internal/ui/feed_mark_as_read.go: handler.markFeedAsRead m14-30 @24
[1] internal/api/feed.go: handler.markFeedAsRead m140-155
  ← used as value by internal/api/api.go: Serve f25-84 @61 "/feeds/{feedID}/mark-all-as-read"
[1] internal/googlereader/handler.go: handler.markAllAsReadHandler m1261-1338
  ← used as value by internal/googlereader/handler.go: Serve f44-64 @62 "/mark-all-as-read"
[1] internal/ui/feed_mark_as_read.go: handler.markFeedAsRead m14-30
  ← used as value by internal/ui/ui.go: Serve f18-180 @77 "/feed/{feedID}/mark-all-as-read"
… (the Fever API, then on down to main.go: main)

m e f marcam métodos e funções com suas linhas; @ é a linha da chamada, e o caminho entre aspas é a rota sob a qual está registrado.

Resultados

Perguntas de impacto ("quais endpoints HTTP mudar isso afeta?") em projetos públicos de Go, Python e Java, avaliadas às cegas contra conjuntos de verdade verificados com a própria ferramenta de cada linguagem:

	Com LayerMap	Sem
Endpoints encontrados, no máximo 15 requisições (gpt-5.5, 6 tarefas × 3 execuções)	97,9%	58,8%
Usado sem solicitação pelo Claude Code / Codex (plugin instalado)	6 de 6 / 6 de 6	—
Endpoints encontrados, sem limite de requisições (Claude Code / Codex)	99,3% / 98,0%	99,0% / 98,6%
Custo, sem limite de requisições (Claude Code em USD / Codex em tokens de entrada)	−32% / −55%
Tempo, sem limite de requisições	+24% / +17%

Com um orçamento apertado, o mapa encontra muito mais do código afetado, com cerca de 24% mais tokens. Sem limite, ambos os agentes chegam lá de qualquer forma. O mapa torna a execução mais barata, e os agentes exploram mais amplamente, o que leva mais tempo. São amostras pequenas em tarefas escritas pelos autores do LayerMap. O relatório tem a configuração, as tarefas publicadas e as limitações.

Como o LayerMap difere

Outras ferramentas dão aos agentes parte disso. O LayerMap combina precisão de compilador com rastreamentos de cadeia completa em um único mapa local:

	Grafos de código Tree-sitter (codegraph, GitNexus, …)	Servidores de linguagem e IDEs (ferramenta LSP do Claude Code, Serena, JetBrains)	Busca por embeddings (Claude Context, Augment)	LayerMap
Como as chamadas são vinculadas	Correspondidas por nomes, imports e regras de framework, muitas vezes com pontuações de confiança	A própria resolução do compilador	Não vinculadas; código semelhante é recuperado	Resolvidas pelo compilador ou verificador de tipos de cada linguagem
Chamadores rastreados até rotas e handlers	Em várias ferramentas, com profundidade variável	Um nível por requisição (JetBrains: 5 por padrão)	—	Até 8 níveis em uma única chamada
Mantido como um mapa	Sim, com monitoramento de arquivos	Não, respondido ao vivo por um servidor em execução	Um índice de blocos de código	Sim, atualizado a cada chamada
Executa na sua máquina	Sim; alguns enviam telemetria anônima	Sim	Geralmente com embeddings na nuvem	Sim, e não envia nada

Outra ferramenta se encaixa melhor se você precisar de:

• mais linguagens, já que os grafos tree-sitter cobrem 30 ou mais;
• Windows;
• renomeação e refatoração, de servidores de linguagem;
• busca por significado, de busca por embeddings;
• busca em muitos repositórios, com Sourcegraph.

Instalação

Claude Code

/plugin marketplace add coffeecoproject/layermap
/plugin install layermap@layermap

Codex

codex plugin marketplace add coffeecoproject/layermap
codex plugin add layermap@layermap

DeepSeek Harness

npx layermap setup dsh

Isso adiciona o LayerMap a todos os perfis do dsh. Cada sessão mapeia o projeto em que o dsh foi iniciado, e npx layermap remove dsh desfaz isso.

Em cada agente, inicie uma nova sessão em um repositório Git e pergunte normalmente. O LayerMap informa ao agente quando o mapa ajuda. No primeiro lançamento, o npx baixa o pacote layermap fixado do npm.

O Claude Code pergunta uma vez antes de cada ferramenta de mapa ser executada em um projeto. Escolha "não perguntar novamente", ou execute npx layermap allow claude para permitir as ferramentas somente leitura do plugin em todos os lugares.

Sem plugins: execute npx layermap setup claude ou npx layermap setup codex. A configuração faz três coisas:

• registra o servidor;
• permite que suas ferramentas somente leitura sejam executadas sem prompt;
• adiciona uma frase marcada ao arquivo de instruções do agente.

Use --scope project para configurá-lo para toda uma equipe, e npx layermap remove … para desfazer. Para qualquer outro cliente MCP, execute npx -y layermap mcp como um servidor stdio no repositório.

Requisitos:

• Node.js 22.22 ou posterior.
• macOS ou Linux (x64 ou arm64).
• Um repositório Git.
• Para projetos Java, um JDK 21 ou posterior.

Como funciona

A primeira chamada em um repositório constrói seu mapa: segundos para um projeto pequeno, alguns minutos para um grande. Chamadas posteriores reanalisam apenas o que mudou, então o mapa sempre corresponde à árvore de trabalho.

Os mapas ficam no cache do usuário (~/Library/Caches/layermap, ~/.cache/layermap ou LAYERMAP_CACHE), nunca no repositório. O LayerMap é executado inteiramente na sua máquina e não envia nada para lugar nenhum (privacidade, segurança).

Ferramenta	Uso
project_explore_map	Um diretório, um arquivo, ou os chamadores e chamados de uma declaração (direction INCOMING ou OUTGOING, depth até 8).
project_search_map	Encontrar declarações por palavras em seus nomes, caminhos ou documentação.
project_find_references	Cada uso de uma declaração, compilado a partir do código-fonte atual.

O mesmo pela linha de comando:

npx layermap explore src/api/users.ts --name createUser --direction INCOMING --depth 8
npx layermap search "invoice total"
npx layermap refs src/billing/tax.ts calculateTax

FAQ

Quanto tempo leva o primeiro mapa? Em um Mac recente:

• Miniflux (400 arquivos Go): cerca de 3 s.
• Servidor do Polar (1.900 arquivos Python): cerca de um minuto.
• Conductor (1.500 arquivos Java e 1.300 arquivos TypeScript): menos de dois minutos.

O que ele não consegue ver? Chamadas que o compilador não consegue resolver estaticamente: injeção de dependência, roteamento de framework desconhecido, reflexão e nomes computados. As ferramentas dizem onde um rastreamento para, e uma relação ausente não prova ausência.

Windows? Ainda não.

Como removo?

• Claude Code: /plugin uninstall layermap@layermap.
• Codex: codex plugin remove layermap@layermap.
• Depois exclua o diretório de cache.

Desenvolvimento

Você precisa de pnpm, Go 1.24 e um JDK 21+. Uma ferramenta ausente deixa sua linguagem não analisada.

Execute pnpm install. Na primeira instalação, o pnpm pergunta quais dependências podem executar scripts de build; permita apenas o esbuild, já que o pacote SQLite vem com binários pré-compilados:

pnpm approve-builds esbuild '!@photostructure/sqlite'

Depois execute pnpm test, pnpm typecheck ou pnpm lint.

pnpm package constrói o pacote npm.

Licença

Apache-2.0. Veja LICENSE e NOTICE.