Um mod do Claude Code na prática — instalação, testes e limites (parte 2 de 2)

Um mod do Claude Code é um plugin com código que roda dentro do programa: reage aos eventos da sessão, guarda estado e desenha na interface. Na prática, ele se instala a partir de um marketplace, não se atualiza sozinho, pode ser testado sem abrir uma sessão e tem limites que só aparecem no uso.

Este post mostra um mod de ponta a ponta, para quem quer instalar um ou avaliar o de outra pessoa: o que ele põe na tela, como instalar, como testar e o que ele ainda não faz. O exemplo é o csr-cockpit, um painel ao lado da conversa que mostra o que a sessão está fazendo (os subagentes e quem chamou quem, as edições, o uso do contexto, os turnos com os comandos, os arquivos mexidos agora e o que está instalado), com o custo estimado de cada agente e de cada turno. O código do csr-cockpit está na pasta plugins/csr-cockpit do claude-code-kit, um repositório público. Não é um tutorial de como programar um mod.

Alguns termos aparecem o tempo todo. O modelo é a IA; o Claude Code é o programa do terminal, que conversa com ela. Agente, aqui, é o subagente: o ajudante que o Claude Code chama para cuidar de uma parte da tarefa. Turno é cada pedido feito na sessão, com tudo o que ele desencadeia. Contexto é tudo o que o modelo tem na frente para responder (as instruções, a conversa, os arquivos lidos); tem tamanho máximo e é medido em tokens, os pedaços de palavra pelos quais se cobra.

Sem um mod, o /usage mostra quanto a sessão inteira custou e, nos planos pagos, que fatia do uso foi para subagentes, em percentual. Quanto custou cada agente, ou cada turno, ele não diz.

O cockpit faz essa conta, e ela é uma estimativa dele: a seção Os limites do csr-cockpit explica como o custo é repartido e onde a conta pode errar.

O que o cockpit mostra

O painel abre e fecha com /cockpit e tem seis abas. Cada uma responde a uma pergunta:

As telas a seguir saem do próprio mod, rodando uma sessão de exemplo numa loja online. As bolinhas numeradas não fazem parte do painel: elas apontam as partes que a lista embaixo de cada tela explica.

Agentes

A imagem do começo do post é a aba Agentes. Nela:

1. As contagens: quantos subagentes estão rodando, quantos terminaram e quantos falharam.
2. Quem chamou quem: um grafo com a conversa principal, desenhada como um cérebro, e cada agente, como um robozinho. Com poucos agentes, todos criados pela conversa principal, eles ficam num anel em volta do cérebro; quando um agente cria outro, como aqui, o grafo vira uma árvore, com um nível por coluna. Quando dois conversam pelo SendMessage, a mensagem aparece como uma curva com seta e a contagem (✉ 2). A cor do agente é o estado (azul rodando, verde concluído, vermelho com falha), e a borda diz de onde vem a definição dele: tracejada para os globais, que ficam em ~/.claude/agents e valem em todo projeto, cheia para os do projeto. Os agentes de um workflow, que não passam pela ferramenta Agent, aparecem com o nome que o script lhes deu e a fase em que rodam.
3. A linha do tempo: uma barra por agente na mesma régua, que mostra quem rodou em paralelo e quem demorou.
4. Os cartões: só o essencial, a tarefa, o tipo, o tempo, o modelo, o contexto do próprio agente, o custo atribuído a ele, as chamadas e, enquanto ele roda, a ferramenta que usa agora. O resultado fica no detalhe.
5. Ver detalhes, que abre o detalhe do agente. Clicar num agente do grafo ou no nome dele na linha do tempo faz o mesmo.

O detalhe de um agente segue o jeito do detalhe de um turno. Na sessão das imagens, o agente Plan ficou com US$ 0,18:

1. Voltar e Reler mensagens: as mensagens do agente são lidas da transcrição dele ao abrir o detalhe e de novo no botão.
2. As ferramentas que o agente chamou, em barras, com quantas vezes cada uma.
3. Os comandos Bash dele, cada um abrindo o próprio detalhe.
4. O pedido que o agente recebeu, inteiro.
5. A resposta, quando ele termina. Entre o pedido e a resposta ficam as últimas chamadas, com o estado e a duração.

Os agentes de um workflow, a orquestração de vários agentes que o Claude Code roda por um script, não passam pela ferramenta Agent, e o Claude Code não entrega ao mod o nome nem o pedido deles. O cockpit lê isso dos arquivos da execução, ao lado da transcrição da sessão, e agrupa os agentes por fase, como o painel de tarefas do próprio Claude Code:

Diffs

A aba Diffs mostra o que mudou, arquivo por arquivo, como a visão de alterações do VS Code:

1. A fonte, uma de cada vez: as edições do Claude na sessão, as de um turno só ou a árvore de trabalho contra o último commit (o git), que inclui o que os comandos e a própria pessoa mudaram.
2. Os arquivos alterados numa árvore de pastas, com a letra do status do git, as linhas somadas e cinco quadradinhos com a proporção do que entrou e saiu.
3. O diff do arquivo escolhido, desenhado como o do próprio Claude Code: números de linha, fundo verde e vermelho e a palavra que mudou em destaque.

Contexto

A aba Contexto responde quanto do contexto sobra e quanto a sessão já custou:

1. O uso do contexto: o percentual, os tokens sobre o tamanho da janela e quanto o último turno somou.
2. O custo da sessão e do último turno.
3. O limite de uso do plano, cada janela com o percentual e quando renova.
4. O total geral da sessão, a conversa e todos os subagentes juntos, desde o começo: os tokens de todas as respostas do modelo e o custo, em dólar e em reais (a cotação é uma opção do plugin, porque o cockpit não busca nada na internet). Uma compactação da conversa não zera essa soma.
5. O contexto repartido por categoria (as mensagens, o prompt de sistema, as ferramentas, a memória, o espaço livre): uma estimativa local, atualizada a cada turno.
6. Contagem exata, que troca a estimativa pela contagem de verdade, com requisições a mais.

Turnos

Na aba Turnos, cada pedido aparece com o que custou e o que desencadeou. O custo do turno também é conta do cockpit (nota: o fim menos o começo): quanto o custo da sessão subiu do começo ao fim do pedido.

1. A duração de cada turno, numa barra: roxo concluído, vermelho com falha, azul em andamento.
2. As ferramentas mais chamadas na sessão.
3. O turno em andamento, num cartão, com a duração, o contexto somado, o custo e o que ele já usou.
4. Os comandos Bash ficam no turno em que rodaram, com o estado e o exit code; o que roda agora aparece no cartão.
5. ”… mais N comandos · ver todos” abre o detalhe do turno.

No detalhe do turno, (1) as ferramentas chamadas em barras, (2) todos os comandos Bash, cada um abrindo o próprio detalhe (o comando inteiro e o fim da saída), (3) o pedido, (4) os subagentes que o turno criou, com o pedido e a resposta de cada um, e (5) a resposta.

Árvore

A aba Árvore mostra onde o Claude está mexendo agora:

1. O que a aba mostra: os arquivos que a sessão leu ou editou, do loop principal e de todos os subagentes, e os que o git vê alterados, com o ramo no alto.
2. Os botões: ler o git de novo, mostrar o projeto inteiro em vez de só o que foi tocado, expandir e recolher todas as pastas.
3. Agora mesmo: enquanto uma leitura ou uma escrita roda, o arquivo aparece aqui, com quem está mexendo nele. Vale também para um comando Bash: o cockpit lê o próprio texto do comando (cat e grep leem; sed -i, tee e o redirecionamento > escrevem). Uma escrita esperando permissão fica acesa até a resposta.
4. Na árvore, o mesmo arquivo acende com o selo editando… ou lendo…, e fica destacado por 8 segundos depois. À direita, a letra do git e as linhas somadas.

Inventário

A aba Inventário lista o que está instalado e o que está ligado nesta sessão, sem gastar tokens:

1. As seções: plugins, skills, comandos, agentes, hooks, servidores MCP, outros (estilo de saída, memória, ferramentas embutidas) e o que há para instalar nos marketplaces cadastrados.
2. O filtro, por nome, origem ou descrição.
3. Ativo (3) ou inativo (4): cada peça com a origem, a descrição e o que ela traz. Ativo quer dizer, por exemplo, plugin habilitado ou servidor MCP conectado.

A linha de resumo

Clicar no nome de um agente, de um comando Bash ou de um turno abre o detalhe: o pedido, as chamadas e a resposta. E acima do prompt, a caixa onde se digita o pedido, o cockpit desenha uma faixa, a linha de resumo, que fica ali com o painel aberto ou fechado. Ela não é a linha de status do rodapé, que é outra peça do Claude Code. No aplicativo de desktop, ela é uma fileira de pílulas, e clicar no repositório ou no contexto abre a aba que fala dele:

Só observa

Ele não faz chamada de rede. Na máquina, roda só comandos de leitura do git, para as abas Árvore e Diffs, e lê o conteúdo antigo de um arquivo antes de uma escrita (para o diff mostrar o que mudou de verdade), as pastas de plugins, skills e agentes que o Inventário lista e, quando há um workflow rodando, os arquivos da execução dele, na pasta da sessão. Grava dois arquivos, só ali: um registro de erros, quando algo falha, e um de diagnóstico de cliques, quando é ligado. O resto fica no estado da sessão e some com ela.

O mod não chama o modelo, então não gasta token por conta própria. A exceção é o botão “Contagem exata”, da aba Contexto: quando ele é apertado, o Claude Code faz requisições a mais para trocar a estimativa local pela contagem de verdade.

Como instalar: o marketplace

Um mod se instala como qualquer plugin, a partir de um marketplace. Um marketplace é um repositório com um arquivo .claude-plugin/marketplace.json, de três campos obrigatórios: name, owner e plugins. Cada entrada de plugins é um item instalável, com um name e um source, que é a pasta dele dentro do repositório. Este é um pedaço do catálogo do claude-code-kit, só com os campos de que este post fala e com as descrições encurtadas:

{
  "name": "cesarschutz",
  "owner": { "name": "Cesar Schutz" },
  "plugins": [
    {
      "name": "csr-cockpit",
      "source": "./plugins/csr-cockpit",
      "description": "Mod: painel ao lado da conversa..."
    },
    {
      "name": "explicar-erro",
      "source": "./skills/explicar-erro",
      "description": "Exemplo de skill: explica um erro ou stack trace...",
      "skills": ["./"] (nota: é este campo que dispensa o plugin.json)
    }
  ]
}

A primeira entrada é um plugin completo: a pasta plugins/csr-cockpit tem o seu .claude-plugin/plugin.json, o manifesto que descreve o plugin. A segunda é uma peça avulsa, isto é, uma extensão sozinha (aqui uma skill, um arquivo de instruções para o modelo): não há plugin.json, e a própria entrada faz o papel de manifesto, dizendo o que a pasta traz no campo skills. Para o Claude Code ela também é um plugin, só que descrito pela entrada do catálogo.

O nome do repositório e o nome do marketplace são coisas diferentes. O repositório se chama claude-code-kit, e o marketplace, cesarschutz. O primeiro aparece na hora de cadastrar; o segundo, na hora de instalar:

claude plugin marketplace add cesarschutz/claude-code-kit
claude plugin install csr-cockpit@cesarschutz

A instalação e a atualização seguem seis passos, do repositório no GitHub à sessão aberta na sua máquina: o que chega a cada lugar e em que versão. Em Passo a passo, a figura se monta um passo por vez.

conferido em out/2026

Os comandos de plugin

Estes são os comandos para instalar, conferir, atualizar e testar um plugin. O resto está na referência dos comandos de plugin.

No terminal:

Dentro da sessão:

Como se testa um mod

Um mod se testa em três camadas, da mais barata para a mais cara.

claude plugin validate. Num mod, além de conferir o manifesto, ele lista os eventos que o mod escuta e as chamadas que ele faz à API dos mods, sem executar nada. Serve também para auditar o mod de outra pessoa antes de instalar. No cockpit, a lista não tem chamada de rede; os processos são só os comandos de leitura do git, e as gravações, só os dois arquivos de registro.

Uma sessão de verdade. O Claude Code aberto num projeto de exemplo, com o mod carregado por claude --plugin-dir. Carregada assim, a pasta fica vigiada: o Claude Code recarrega o mod a cada arquivo salvo. É a única das três camadas que mostra o painel desenhado no terminal.

Os limites do csr-cockpit

Estes são os limites do csr-cockpit na versão 1.0.0, em 04/10/2026.

O mais importante: o custo por agente não é um número oficial. O Claude Code informa o custo da sessão inteira, não o de cada agente. O cockpit reparte esse custo: ao fim de cada resposta do modelo, ele vê quanto o custo da sessão subiu e põe essa diferença na conta de quem respondeu, um agente ou a conversa principal. Cada aumento vai para um dono só, então nada é contado duas vezes, e o que não vai para agente nenhum é o gasto da conversa principal: na sessão das imagens, os quatro agentes ficaram com US$ 0,37 dos US$ 2,21. É uma atribuição feita pelo cockpit e, se duas respostas terminam no mesmo instante, uma fração pode cair no agente vizinho.

O próprio valor em dólar é uma estimativa: o Claude Code calcula a preço de tabela, a partir dos tokens. Para quem paga assinatura ele não é cobrança, e serve para comparar um agente com outro.

Os outros limites:

• Não há custo por comando Bash. O cockpit mostra custo por agente e por turno. Um comando Bash aparece com o status e a duração.
• O raciocínio interno de um agente não aparece. O Claude Code não o expõe. O detalhe mostra só o texto que o agente escreveu.
• O código de saída do Bash não vem como campo. Em caso de falha, o cockpit tira o código do texto de erro. Em caso de sucesso, a linha mostra só a marca de concluído e a duração.
• No aplicativo de desktop, o painel não acompanha cada chamada. O aplicativo recusa o clique feito num desenho que já foi trocado, então o cockpit redesenha o painel na hora depois de um clique e, fora isso, no máximo a cada 2,5 segundos; o tempo de quem roda há mais de um minuto aparece em minutos.
• A API de mods ainda pode mudar de uma versão para outra.
• No aplicativo de desktop, depende da versão que ele traz. O aplicativo usa a própria cópia do Claude Code, que o claude --version do terminal não mostra. Em 02/10/2026, a versão 2.16120.0 para macOS trazia o Claude Code 2.1.284, anterior aos mods oficiais, e nela o /cockpit respondia que não era um comando. Em 04/10/2026, a versão 2.19675.0 já roda o cockpit, com o painel ao lado da conversa e as pílulas acima do prompt.

O repositório claude-code-kit

O claude-code-kit é público, com licença MIT. Em 04/10/2026 ele tem:

O README.md explica o catálogo, e o CONTRIBUTING.md, como acrescentar um item. O repositório vai continuar recebendo peças.

Fontes

• Claude — Claude Code mods (o anúncio dos mods, em 01/10/2026)
• Claude Code — Mods overview (o que é um mod e a versão mínima), Create a mod e Test a mod
• Claude Code — Create a marketplace e Marketplace reference (a entrada que faz o papel de manifesto)
• Claude Code — Install and manage plugins (o cadastro do marketplace e as atualizações), Plugin loading reference (como a versão é calculada e o que acontece com a sessão aberta) e Plugin commands reference
• Claude Code — Manage costs effectively (o que o /usage mostra e como o valor em dólar é calculado)
• Cesar Schutz — claude-code-kit e o README do csr-cockpit (as abas, as teclas, os limites e a privacidade)