Quanto custou cada agente? — Do CLAUDE.md ao mod no Claude Code

Quanto custou cada agente que o Claude Code rodou no seu último pedido? E cada turno da conversa?

Arraste para o lado para ver a imagem inteira.

Agente, aqui, é o subagente: o ajudante que o Claude Code chama para cuidar de uma parte da tarefa. Turno é cada pedido seu, com tudo o que ele desencadeia. Até os mods virarem oficiais, em 01/10/2026, a ferramenta não me mostrava essa conta: 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.

Desde aquele dia dá para fazer a conta, por causa de uma peça nova: o mod, código que roda dentro do Claude Code e desenha na interface. No mesmo dia publiquei um: o csr-cockpit, o painel da imagem. Ele está no claude-code-kit, um repositório meu.

O número de cada agente é uma conta do painel, não do Claude Code, que continua informando só o custo da sessão inteira. Como o painel reparte esse custo, e onde a conta pode errar, está em O que ainda não dá.

Este post conta como o Claude Code chegou até o mod, peça por peça. Quando comecei, eu não conhecia skill, agente, hook, plugin, marketplace nem mod: aprendi tudo naquele dia. Por isso o texto explica o básico de cada peça e aponta a documentação oficial para quem quiser se aprofundar. Não é um tutorial de código.

A linha do tempo

O Claude Code foi lançado em 24/02/2025, como prévia de pesquisa, e o mod chegou em 01/10/2026. São pouco mais de 19 meses, e nesse intervalo a ferramenta ganhou, uma depois da outra, as peças desta tabela:

Entre parênteses está a versão em que a peça entrou. Cada data é a da publicação dessa versão no npm, e a linha de cada peça está no changelog do repositório.

O CLAUDE.md e o MCP são a exceção: não têm linha de estreia, porque já estavam na documentação do dia do lançamento.

Eu leio essa tabela como uma escada, e em cada degrau faço a mesma pergunta: com isso eu conseguiria aquele painel? Para responder, uma distinção ajuda. O modelo é a IA, o Claude: lê texto e responde. O Claude Code é o programa que você abre no terminal: manda o texto ao modelo, executa as ferramentas que ele pede (ler um arquivo, rodar um comando) e desenha a tela. Um painel só pode vir do programa.

Mais um termo, que volta até o fim do post. Tudo o que o modelo tem na frente para responder (as instruções, a conversa, os arquivos lidos) é o contexto. Ele tem tamanho máximo e é medido em tokens, os pedaços de palavra em que o modelo conta o texto e pelos quais se cobra.

Cada peça e o que ela não alcança

CLAUDE.md. Um arquivo de texto, em geral na raiz do projeto, que o Claude Code entrega ao modelo no começo de toda sessão. É onde ficam as instruções permanentes: como rodar os testes, as convenções do time, o que nunca fazer. Use para o que vale sempre. Para o painel ele não serve: é texto para o modelo ler.

MCP. O Model Context Protocol liga o modelo a sistemas de fora: um servidor MCP entrega ferramentas novas, como consultar um banco de dados ou controlar um navegador. Use quando o modelo precisa alcançar algo que ele não enxerga. O painel continua fora de alcance: o MCP dá ferramentas ao modelo, e a tela segue a mesma.

Comando. Um prompt salvo num arquivo Markdown, que você chama digitando /nome. Serve para o pedido que se repete toda semana. Poupa a digitação, e só: o que chega ao modelo é o mesmo texto.

Hook. Na forma mais comum, um comando do sistema que o Claude Code roda sozinho num evento: no início da sessão, antes de uma ferramenta, depois de uma edição. É a peça para o que tem de acontecer sempre, sem depender de o modelo lembrar. O exemplo do kit é o responder-em-portugues, um echo no início da sessão. Das peças antigas, é a que vê os eventos passarem. Só que roda fora do Claude Code (nota: o mod vai rodar dentro), como um processo à parte, e não desenha nada.

Subagente. É o agente da pergunta do começo: um ajudante com papel próprio, ferramentas limitadas e um contexto só dele (quer dizer: não ocupa o da conversa), que faz a tarefa e devolve um resumo. Use para isolar o trabalho que encheria a conversa principal, como uma busca em dezenas de arquivos. No kit há dois, o pesquisador e o critico, cada um definido por um arquivo de instruções.

Linha de status. Uma linha no rodapé, impressa por um script seu, que recebe do Claude Code os dados da sessão, entre eles o custo. É a peça que mais se parece com o painel. Mas é uma linha só, sem clique, e o custo que chega a ela é o da sessão inteira.

Estilo de saída. Um jeito de responder: o papel, o tom e o formato das respostas de uma sessão. O professor do kit explica o porquê de cada passo. Muda o texto da resposta, não a tela.

Skill. Uma pasta com um arquivo SKILL.md: instruções que o modelo carrega quando o pedido combina com a descrição, ou quando você chama pelo nome. É a peça para o procedimento que você vive colando na conversa. Os comandos próprios, lá de cima, foram incorporados às skills, e os arquivos antigos continuam funcionando. No kit, a mensagem-de-commit escreve a mensagem de commit das mudanças já preparadas com git add.

Plugin. É a embalagem: uma pasta com skills, agentes, hooks, estilos e servidores MCP, que se instala de uma vez. Dentro dela, o arquivo .claude-plugin/plugin.json é o manifesto, que descreve o plugin. Use quando um segundo projeto, ou uma segunda pessoa, precisa da mesma configuração. O exemplos do kit leva uma skill, um agente, um hook e um estilo de saída. Sozinho, o plugin não acrescenta poder nenhum: empacota o que já existia.

Tema. As cores da interface, num arquivo JSON que parte de um tema pronto e troca algumas cores. O tinta-azul troca três. Muda a cor do que já está na tela.

Antes de chegar a ela, três seções sobre como as peças se instalam, porque foi ali que eu mais me perdi.

Skill, agente ou plugin: o que eu demorei a entender

Esta é a lista do que me confundiu, antes do detalhe. Marketplace é o catálogo de onde os plugins se instalam, e é o assunto da seção seguinte.

• Skill, agente e plugin não são alternativas. A skill é uma instrução. O agente é quem executa uma tarefa numa conversa à parte. O plugin é a pasta que entrega os dois.
• Mod é plugin, não skill. A skill é um texto que o modelo lê. O mod é código que o Claude Code executa. Os dois se instalam do mesmo jeito.
• Não há build. Nada de npm install nem de empacotador: o Claude Code lê o código direto da pasta.
• O que se instala é a pasta inteira. Cada item do catálogo aponta para uma pasta, e tudo o que está nela vem junto.
• Uma peça avulsa não precisa de plugin.json. Para instalar uma skill sozinha, basta a entrada dela no catálogo, que faz o papel de manifesto.
• O nome do repositório e o nome do marketplace são coisas diferentes. O meu repositório se chama claude-code-kit, e o marketplace, cesarschutz. O primeiro aparece na hora de cadastrar; o segundo, na hora de instalar.
• Não precisa de conta empresarial. Um marketplace é um repositório git. Um repositório público no GitHub basta.
• A sessão aberta continua na versão antiga. Depois de atualizar um plugin, a sessão que já estava aberta segue com a versão que carregou, até um /reload-plugins ou até ser reaberta.

Marketplace: o catálogo num repositório

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 meu, 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. A segunda é uma peça avulsa: não há plugin.json, e a própria entrada diz o que a pasta traz, no campo skills.

Instalar e atualizar seguem o caminho da lousa, em cinco passos, do repositório no GitHub à sessão aberta na sua máquina. O play desenha tudo desde o início, e um clique num passo da lista leva a lousa até ele.

conferido em out/2026

Os comandos

Estes são os comandos que eu usei. O resto está na referência dos comandos de plugin.

No terminal:

Dentro da sessão:

O que é um mod

O mod é um plugin com uma diferença. Num plugin comum, o arquivo hooks/hooks.json lista os hooks: que comando do sistema rodar em cada evento. No mod, o mesmo arquivo aponta um módulo, que é um arquivo de código.

{ "modules": ["./register.tsx"] } (nota: o código do mod)

Esse módulo exporta uma função register(on). Dentro dela, cada on(...) liga uma função a um evento do Claude Code: uma chamada de ferramenta, o início de um turno, um pedaço da interface sendo desenhado. A função recebe três coisas: $, a API dos mods; e, o evento; e next, que passa o evento adiante, como num middleware (nota: sem chamar next, o hook responde). Este é o hook do cockpit que registra um subagente novo, com o miolo resumido num comentário:

export const register: Register = on => {
  on('agent.spawn', async ($, e, next) => {
    const iniciado = await next(e) (nota: o evento segue adiante como chegou)
    // guarda o agente e o pedido dele no estado da sessão
    return iniciado
  })
}

A documentação também chama de hook cada função dessas. A ideia é a do hook de antes, reagir a um evento, só que agora é código rodando dentro do Claude Code, que pode observar o evento, reescrevê-lo ou responder no lugar do programa. Com isso, um mod:

• roda dentro do Claude Code, no processo dele, e não como um script à parte;
• guarda estado (lembra o que viu) entre um evento e outro, pelo tempo da sessão;
• registra um comando /nome que executa código na hora, sem passar pelo modelo;
• desenha: um painel ao lado da conversa e uma faixa acima do prompt, a caixa onde se digita o pedido.

Das peças da tabela, é a primeira que roda ali dentro e a primeira que desenha.

A figura junta as peças no lugar em que cada uma age. Do lado de fora ficam o texto que vai para o contexto do modelo (azul), as ferramentas do MCP (âmbar) e o script do hook (verde), quase tudo dentro da pasta do plugin (roxo). Do lado de dentro, só o mod (petróleo): o código dele vem na mesma pasta, recebe os eventos, guarda estado e desenha o painel e a faixa. Com o mouse numa cor da legenda, só aquele papel fica aceso.

conferido em out/2026

O cockpit

O csr-cockpit é um painel ao lado da conversa, aberto e fechado com /cockpit, com cinco abas. Cada uma responde a uma pergunta:

A aba Agentes responde à primeira pergunta do post. O custo de cada agente é a parte do custo da sessão que o cockpit atribuiu a ele. Na sessão das imagens, foram US$ 0,04 para um agente e US$ 0,02 para o outro:

Arraste para o lado para ver a imagem inteira.

A aba Turnos responde à segunda. Cada pedido meu é um turno, com o que ele 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.

Arraste para o lado para ver a imagem inteira.

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 fica uma linha de resumo, com o painel aberto ou fechado:

Arraste para o lado para ver a imagem inteira.

Ele não faz chamada de rede e não grava arquivo. Do disco, lê uma coisa só: o conteúdo antigo de um arquivo antes de uma escrita, para o diff mostrar o que mudou de verdade. O que ele registra fica no estado da sessão e some com ela.

Nada nele gasta token, porque o mod não chama o modelo. A única coisa que dispara requisições a mais é o botão “Contagem exata”, da aba Contexto, que troca a estimativa local pela contagem de verdade. Quem faz essas requisições é o Claude Code, e só quando eu aperto o botão.

Como se testa um mod

Testei o cockpit 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 faz à API, 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, de gravação de arquivo nem de processo; do disco, só aquela leitura.

Uma sessão de verdade. Abri o Claude Code 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.

O que ainda não dá

São os limites da versão 0.5.0, em 02/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, o que o custo da sessão subiu vai para quem deu a resposta. 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 dois agentes ficaram com US$ 0,06 dos US$ 0,15. É uma atribuição feita pelo mod 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.
• A API de mods ainda pode mudar de uma versão para outra.
• No aplicativo de desktop eu não conferi. Ele traz a própria cópia do Claude Code, que pode estar numa versão mais antiga que a do terminal, e o desenho do painel eu só conferi no terminal.

O repositório

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

Para instalar o cockpit são dois comandos, e ele pede o Claude Code 2.1.287 ou mais novo:

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

O README.md explica o catálogo, e o CONTRIBUTING.md, como acrescentar um item. Vou continuar colocando coisas lá.

Fontes

• Anthropic — Claude 3.7 Sonnet and Claude Code (o lançamento em prévia de pesquisa, em 24/02/2025) e a documentação daquele dia, guardada pelo Internet Archive (o CLAUDE.md e o MCP já no lançamento)
• Claude — Claude Code mods (o anúncio dos mods, em 01/10/2026), Customize Claude Code with plugins (os plugins e os marketplaces, em 09/10/2025) e Introducing Agent Skills (as skills, em 16/10/2025)
• Claude Code — Changelog e CHANGELOG.md no GitHub (a versão em que cada peça entrou)
• npm — @anthropic-ai/claude-code, versões (a data de publicação de cada versão)
• Claude Code no GitHub — o commit de 09/09/2026 que publicou a pasta mods/, com o aviso de acesso antecipado, e os mods de exemplo
• Claude Code — Extend Claude Code (quando usar CLAUDE.md, skills, subagentes, hooks, MCP e plugins) e Explore the context window (o contexto)
• Claude Code — How Claude remembers your project, Extend Claude with skills (com os comandos próprios) e Connect Claude Code to tools via MCP
• Claude Code — Automate actions with hooks, Create custom subagents e Output styles
• Claude Code — Customize your status line e Configure your terminal (os temas próprios)
• Claude Code — Plugins overview, 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 — Mods overview (o que é um mod, a versão mínima, o acesso antecipado e o que um mod alcança), Create a mod e Test a mod
• 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)