Claude Agents Monitor

Mostra, ao lado da sua sessão do Claude Code, a sessão principal e todos os subagentes em execução: o modelo real de cada um, uma descrição em linguagem simples do que está fazendo agora (lendo um arquivo, rodando um comando, pesquisando na web...) e o tempo decorrido. Cada agente é um card estilo toast no topo da barra lateral direita, com a logo do Claude na cor da faixa de custo, o modelo num badge clicável e os tokens em uso; o painel aparece sozinho em toda janela do VS Code aberta e some quando não há nada rodando.

A extensão só lê os transcripts locais em ~/.claude/projects. Não faz chamadas de rede, não usa chave de API e não altera nenhuma configuração do Claude Code.

Como funciona

• O Claude Code grava, em tempo real, um arquivo .jsonl por sessão (e um por subagente, em subagents/agent-<id>.jsonl + agent-<id>.meta.json). A extensão lê só os bytes novos desses arquivos a cada verificação.
• O modelo mostrado vem, na ordem de preferência, do próprio transcript do agente, depois do meta.json e, por último, é marcado como "herdado" do agente pai.
• A detecção de término olha o tool_result de quem chamou o subagente (primeiro plano) ou a notificação de tarefa (task-notification) para agentes em segundo plano — não existe um evento único de "acabou" para todos os casos.
• Depois que um agente termina ou a sessão fica ociosa, o painel espera uma folga de alguns segundos (padrão 8 s) antes de sumir, para não piscar entre uma ferramenta e outra.
• Sessões sem nenhuma atividade há mais de 10 minutos são ignoradas.

Requisitos

• VS Code 1.106 ou mais recente.
• Extensão do Claude Code instalada (opcional). Sem ela, o painel aparece em um container próprio na barra lateral secundária, em vez de ficar empilhado com o chat.
• Windows, macOS ou Linux. Testado no Windows.

Instalação

Local, via arquivo .vsix:

code --install-extension claude-agents-monitor-0.3.0.vsix

Ou pela interface: Extensões → menu ... → Install from VSIX... e selecione o arquivo.

Pelo Marketplace ou Open VSX (quando publicada): procure por "Claude Agents Monitor" na aba Extensões do VS Code (ou no VSCodium/Cursor, no Open VSX) e clique em Instalar.

Uso

O painel aparece sozinho, em cada janela do VS Code, assim que algum agente entra em atividade — não é preciso abrir nada manualmente. Também estão disponíveis:

• Claude Agents: Atualizar — força uma nova verificação dos transcripts.
• Claude Agents: Mostrar painel de agentes — abre/foca o painel.
• Claude Agents: Abrir/fechar janela flutuante de agentes (Ctrl+Alt+X) — abre os cards de agentes numa janela própria, destacada da janela do VS Code (compacta e sempre por cima por padrão); o mesmo atalho fecha. Clicar num card abre o transcript na janela principal. O atalho pode ser trocado em Atalhos de Teclado.
• Clicar (ou apertar Enter) em uma linha de agente abre o transcript correspondente.
• A view pode ser arrastada para outra posição na barra lateral, como qualquer outra do VS Code.
• Um item na barra de status mostra a contagem de agentes ativos enquanto houver algum rodando.

Toasts por agente (painel à direita)

Cada agente em execução vira um card estilo toast no painel de agentes, no topo da barra lateral direita, e também na janela flutuante do Ctrl+Alt+X. O painel lateral só aparece sozinho quando um agente começa a rodar se claudeAgents.toasts.autoReveal estiver ligado (desligado por padrão). Como a extensão roda em cada janela do VS Code e, por padrão, monitora todas as pastas de projeto (claudeAgents.scope: all), o mesmo conjunto de toasts aparece duplicado em toda janela aberta, independente de qual projeto ela tem aberto.

Cada card mostra:

• Logo do Claude tingida pela cor da faixa de custo e a borda esquerda na mesma cor: 🟢 verde Haiku (barato), 🟡 amarelo Sonnet (médio), 🟠 laranja Opus (caro), 🔴 vermelho Fable (muito caro), cinza para modelo desconhecido.
• Nome do agente em destaque, com o modelo num badge colorido pela faixa de custo. Clicar no badge abre o seletor de modelo (veja abaixo). Ao lado ficam o tipo do subagente e a marca de 2º plano.
• Ponto de status (pulsando enquanto roda; verde concluído, vermelho falhou, amarelo aguardando ou sem resposta) e o tempo decorrido.
• Linha de tokens (se claudeAgents.showTokens): contexto atual com uma barra em relação à janela do modelo (200k, ou 1M para ids com [1m]), saída acumulada (↑) e número de mensagens. O tooltip detalha entrada, saída, cache lido e criado. Prefixo ≥ na saída quando o transcript foi lido parcialmente (arquivo > 2 MB).
• Atividade atual em linguagem simples, em até 3 linhas.
• Clique no card (ou Enter) abre o transcript do agente.

O cabeçalho de cada sessão traz a origem (VS Code ou CLI), a pasta do projeto (tooltip com o caminho completo), o título da sessão e o branch.

Posição. O VS Code não permite desenhar um overlay flutuante por cima do editor; o lugar que uma extensão controla no canto superior direito é a barra lateral secundária. Com claudeAgents.placement: claudeSidebar (padrão) o painel entra no container do Claude Code, abaixo do chat: arraste a seção "Agentes" para cima do chat uma vez e o VS Code guarda a ordem. Com ownContainer o painel tem um ícone próprio na barra lateral secundária.

Modo compacto. claudeAgents.compact: true volta ao layout de uma linha por agente (badge de modelo e tokens continuam, sem barra).

Notificações nativas (opcional)

Com claudeAgents.notifications.enabled: true, cada agente também ganha uma notificação nativa de progresso no canto inferior direito. É a única forma de mostrar algo por cima do editor com a API pública, mas com limites que a extensão não consegue contornar:

1. Posição e layout fixos. Sempre no canto inferior direito, texto em uma linha (título: mensagem), sem imagem, badge ou cor de fundo; a cor entra como emoji no início.
2. Máximo de ~3 notificações visíveis ao mesmo tempo. As demais viram um resumo +N agentes… na central de notificações.
3. Modo "Não perturbe" do VS Code as silencia (ficam só na central).
4. Título não muda depois de criado. Se o modelo de um agente for resolvido ou a faixa mudar, a notificação é recriada (pisca uma vez).
5. O corpo não é clicável. O botão "Cancelar" abre um menu de ações (trocar modelo, abrir transcript, ocultar); o agente continua rodando.

Trocar modelo padrão

O botão "Cancelar" numa notificação abre um menu com a opção "Trocar modelo…". Na lista lateral, o badge do modelo também é um botão.

O que faz

• Grava model em ~/.claude/settings.json (ou em CLAUDE_CONFIG_DIR/settings.json se configurado).
• Cria um backup automático: settings.json.claude-agents.bak.
• Vale apenas para novas sessões — o CLI lê a configuração apenas ao iniciar.
• Em sessões CLI rodando num terminal integrado, se a opção claudeAgents.modelSwitch.sendToTerminal estiver ligada, oferece enviar /model <id> diretamente ao terminal (apenas com a sessão ociosa, após validação da árvore de processos e confirmação do usuário).

O que NÃO faz

• Não altera a sessão em andamento no painel do Claude Code — ela continua no modelo atual. Para trocar, copie /model <id> e cole no chat (a extensão oferece isso automaticamente).
• Não afeta subagentes em execução — o modelo de um subagente é fixado no spawn e não pode ser alterado.
• Não lê "managed" ou "policy" settings do seu sistema ou organização.
• Overrides têm prioridade: se ~/.claude/.claude/settings.json do projeto, ~/.claude/settings.local.json ou a variável ANTHROPIC_MODEL definirem um modelo, eles ganham precedência sobre o arquivo editado. A extensão avisa quando detecta esses overrides.

Seletor de modelos

Um seletor nativo do VS Code mostra:

• Modelos configurados (padrão: Haiku, Sonnet, Opus, Fable), marcados com emoji de custo.
• Atual desta sessão e padrão atual aparecem destacados.
• Subagente: o menu mostra um aviso de que o modelo do subagente não pode ser alterado em execução; permite apenas trocar o padrão.
• Opção de retornar ao padrão do Claude Code (remover a chave model), se houver um arquivo gravado.

Configurações

Limitações conhecidas

• O Claude Code não expõe uma API pública para isso; a detecção é feita lendo os arquivos de transcript, então há uma latência equivalente ao intervalo de verificação (por padrão, até 1,5 s).
• A descrição da atividade é baseada em regras fixas sobre a última ferramenta usada, não em uma análise inteligente do que o agente está fazendo.
• Uma extensão não consegue desenhar dentro do webview de outra: o painel fica ao lado do chat do Claude Code, empilhado no mesmo espaço, mas não dentro dele.
• Não existe API para um overlay flutuante por cima do editor; o "canto superior direito" que uma extensão controla é a barra lateral secundária. A ordem das seções dentro do container do Claude Code é decidida pelo usuário (arrastar), não pela extensão.
• Sessões sem atividade há mais de 10 minutos não aparecem, mesmo que o transcript ainda exista.
• Transcripts apagados pela limpeza automática do Claude Code (configuração cleanupPeriodDays) somem do painel também.
• Se o VS Code for fechado no meio de um turno do Claude, a sessão pode continuar aparecendo como "rodando" até completar o tempo de sessionIdleMinutes.

Desenvolvimento

npm install
npm run watch      # build incremental em segundo plano

Aperte F5 no VS Code para abrir um Extension Development Host com a extensão carregada.

npm test           # testes unitários (vitest)
npm run package    # gera o .vsix

Privacidade

A extensão lê apenas arquivos locais em ~/.claude/projects (ou na pasta indicada por CLAUDE_CONFIG_DIR/claudeAgents.claudeConfigDir). Não há chamadas de rede nem coleta de dados. Comandos de shell (Bash) nunca são exibidos por inteiro no painel — apenas a primeira palavra do comando, ou a descrição curta que o próprio agente forneceu.

Licença

MIT. Veja o arquivo LICENSE na raiz do repositório.