Intensivo Grátis 21–22/11Intensivo gratuito de 2 dias em Vibecoding (21–22/11 às 16:00 MSK) · Turma 3 começa 23/11Inscrever-se grátis →Turma 3 (23/11)
LançamentoAnálise · No radarHabr AI→ original

Mod para o Claude Code que desenha um mapa do trabalho do agente soma 1000 estrelas em 10 dias

O autor pediu a um agente no Claude Code que desenhasse o próprio trabalho e transformou a imagem em um mod: o modelo fica no centro, cercado por dez estações — arquivos, terminal, rede, memória. Em dez dias, o repositório chegou a 1000 estrelas. Em 11 de novembro, a pedido dos usuários, saíram 14 versões em um único dia. O mod só observa e não altera nada, por isso o autor recusou botões de bloqueio e skins. A lição para quem desenvolve extensões: um foco estreito e princípios documentados geram mais confiança do que um monte de funções.

Processado por IA de Habr AI; editado por Hamidun News
Mod para o Claude Code que desenha um mapa do trabalho do agente soma 1000 estrelas em 10 dias
Fonte: Habr AI. Colagem: Hamidun News.
Ouvir artigo
Ficha técnica e números-chave
ParâmetroDados
Fonte originalHabr AI ↗
Editor-chefe
Dado-chave #1O iTerm2 inchou de 286 MB para 17 GB em cinco minutos — a imagem foi desativada
Dado-chave #2De um curl com token, o mapa mostra só a palavra curl; de um endereço, só o host
No Japão, um teste com 40 chamadastodas caíram na estação correta

Quando um agente trabalha no terminal, o que se vê é apenas um fluxo de linhas. O que ele está fazendo agora: lendo arquivos, acessando a rede, iniciando um subagente? Dá para descobrir, mas é preciso vasculhar o log. O autor do mod lot-map resolveu o problema de um jeito simples. Ele pediu ao seu agente no Claude Code que desenhasse como ele mesmo enxerga o próprio fluxo de trabalho e transformou o desenho em uma extensão. Em dez dias, o repositório reuniu 1000 estrelas. Para um pequeno projeto open source, é um bom resultado, e mais notável ainda é a forma como o projeto foi conduzido.

Como funciona e como cresceu

No mapa, o modelo fica no centro, cercado por dez estações: arquivos, terminal, rede, memória, subagentes, hooks e outras. Quando o agente chama uma ferramenta, um pulso corre até a estação correspondente, e as últimas chamadas aparecem abaixo do mapa. A primeira versão saiu em 9 de novembro, e o autor a mostrou no r/ClaudeAI com um vídeo. Na noite de 11 de novembro, eram 100 estrelas; em 12 de novembro, 500; em 18 de novembro, 1000.

O crescimento veio junto com o feedback. Só em 11 de novembro saíram quatorze versões: quase todo pedido nos comentários virava um release. Assim surgiram a rotação do mapa, cores personalizadas, fundo transparente, a correção dos caminhos no Windows e legendas em italiano e português. A versão atual é a 0.12.0. O recurso mais elogiado é o anel ao redor do centro, que mostra o quanto do contexto está preenchido. Há também um contador de tokens, que indica quanto cada chamada acrescentou ao contexto.

Terminal, iTerm2 e o catálogo da Anthropic

No Claude Code, imagens só são renderizadas no aplicativo e no VS Code; no terminal, sobram apenas linhas de texto. O autor tentou desenhar o mapa com caracteres e admitiu que o resultado ficou ruim: sete linhas sem movimento. Foi aí que entraram os entusiastas. Um deles enviou um pull request de 2000 linhas em que o próprio mod desenha um PNG e o entrega ao terminal quadro a quadro (versão 0.6.0). Outro fez o mapa com caracteres braille para terminais sem suporte a imagens, como o Windows Terminal.

Depois apareceu uma falha desagradável. Um usuário ficou sem memória: o iTerm2 cresceu de 286 MB para 17 GB em cinco minutos, porque guardava cada quadro até a aba ser fechada. Do lado do mod, não há como contornar isso, e na 0.9.0 a imagem no iTerm2 foi desativada. O autor enviou um relatório ao desenvolvedor do iTerm2, que corrigiu o erro no dia seguinte. Na 0.12.0, a imagem voltou para o iTerm2 a partir da versão 3.7.8.

Com o catálogo da Anthropic, a história foi pior. Para passar na validação, o hook de verificação de permissões foi removido do mod (versão 0.4.0), e duas linhas sumiram do mapa. No fim, veio a recusa: o catálogo só aceita mods de organizações verificadas. O hook voltou na 0.5.0. A lição é simples: não adapte o produto a uma plataforma antes de entender as condições dela.

O que foi recusado e por que o mod ganhou confiança

O autor recusou skins de steampunk e de cometas: o mapa existe para mostrar, num relance, o que o agente está fazendo, e um cometa já é enfeite. Recusou também botões que permitiriam proibir o agente de usar a rede ou o terminal: o mod só observa e não altera nada, e é nisso que a confiança se apoia. Recusou ainda uma camada para outros agentes, porque ninguém rodava o mapa com nada além do Claude Code. Os ports vivem em repositórios separados.

No quinto dia, o projeto formulou seis princípios: o mod não altera nada; a legenda mostra apenas o nome, sem o conteúdo; ele custa quase nada em recursos; uma falha no mapa não atrapalha o trabalho do agente; o mapa é discreto; as configurações do usuário permanecem como estão. Cada princípio tem um teste que o protege. No primeiro, o teste verifica que o evento segue adiante exatamente como chegou. Para o terceiro, há medições com orçamento de tempo. O repositório traz uma lista de tudo o que o mod solicita ao Claude Code, e uma verificação em cada pull request confere o código contra essa lista. Rede, leitura de arquivos e execução de processos não constam nela.

O segundo princípio se mostrou necessário antes de ser escrito. O mod enxerga cada chamada por inteiro: comandos, caminhos, endereços com parâmetros, e a tela pode acabar em screenshots. Por isso, de um curl com token sobra apenas a palavra curl; de um endereço, só o host. No terceiro dia, um leitor do código encontrou uma forma de escrever um endereço em que a senha ainda vazava para a legenda. A correção saiu no mesmo dia.

Verificações externas

Um blogueiro japonês rodou cinco tarefas e quarenta chamadas, conferindo o mapa a cada meio segundo. Todas as quarenta caíram na estação correta, e o nome do alvo apareceu em trinta. A conclusão dele: o mapa dá uma visão geral, mas não substitui o log. Na Espanha, o mod passou por um scanner de segurança, e dez alertas foram analisados manualmente: todos eram falsos, o scanner reclamava de curl e sudo nos testes. Alguém criou um overlay para o Codex a partir dos mesmos arquivos, e outra pessoa adicionou uma linha do tempo com a duração de cada turno.

Para quem escreve extensões para agentes, a conclusão é prática. O papel estreito de "só observo" permitiu formular garantias verificáveis. A lista de princípios com testes ajudou a recusar ideias de terceiros sem discussão. As limitações também são honestas: o mapa é uma visão geral, não um substituto do log, e em terminais sem suporte a imagens ele fica mais pobre. O mod pode ser visto no navegador em alexeyw.github.io/lot-map, e o código está no repositório alexeyw/lot-map.

História

Perguntas frequentes sobre a notícia

Como funciona e como cresceu?

No mapa, o modelo fica no centro, cercado por dez estações: arquivos, terminal, rede, memória, subagentes, hooks e outras. Quando o agente chama uma ferramenta, um pulso corre até a estação correspondente, e as últimas chamadas aparecem abaixo do mapa. A primeira versão saiu em 9 de novembro, e o autor a mostrou no r/ClaudeAI com um vídeo. Na noite de 11 de novembro, eram 100 estrelas; em 12 de novembro, 500; em 18 de novembro, 1000. O crescimento veio junto com o feedback.

O que se sabe sobre Terminal, iTerm2 e o catálogo da Anthropic?

No Claude Code, imagens só são renderizadas no aplicativo e no VS Code; no terminal, sobram apenas linhas de texto. O autor tentou desenhar o mapa com caracteres e admitiu que o resultado ficou ruim: sete linhas sem movimento. Foi aí que entraram os entusiastas. Um deles enviou um pull request de 2000 linhas em que o próprio mod desenha um PNG e o entrega ao terminal quadro a quadro (versão 0.6.0). Outro fez o mapa com caracteres braille para terminais sem suporte a imagens, como o Windows Terminal.

O que foi recusado e por que o mod ganhou confiança?

O autor recusou skins de steampunk e de cometas: o mapa existe para mostrar, num relance, o que o agente está fazendo, e um cometa já é enfeite. Recusou também botões que permitiriam proibir o agente de usar a rede ou o terminal: o mod só observa e não altera nada, e é nisso que a confiança se apoia. Recusou ainda uma camada para outros agentes, porque ninguém rodava o mapa com nada além do Claude Code. Os ports vivem em repositórios separados.

ZK
Zhemal Khamidun — CPO da Alpina Digital, gerente de produto do AlpinaGPT. Cria produtos de IA desde 2019. O Hamidun News é um projeto pessoal que virou um agregador em produção com mais de 6.000 leitores.
✦ Hands-On AI Engineering · Hamidun Academy

Build & Ship Production AI Agents Without Boilerplate Code

Start your free 72-hour trial at Hamidun Academy (academy.hamidun.com) — interactive lessons on Claude Code & Cursor, live Tech Radar, and production agent templates.

Start 72h Free Trial →Vibe-Coding Intensive
O que você acha?
Carregando comentários…