Agentes Observam: Painel em Tempo Real para Monitoramento de Equipes de Agentes de Código Claude

O que o Agents Observe faz

Agents Observe é um painel de observabilidade em tempo real especificamente construído para equipes de agentes Claude Code. Ele aborda a lacuna de visibilidade quando o Claude Code é executado autonomamente—gerando subagentes, chamando ferramentas, lendo arquivos e executando comandos—capturando cada evento de hook conforme ocorre e transmitindo-o para um painel ao vivo.

Recursos Principais e Arquitetura

A ferramenta usa hooks do Claude Code em vez de OTEL (OpenTelemetry) para capturar o que o desenvolvedor descreve como "a imagem completa das ações do agente". A arquitetura segue este fluxo:

• Claude Code Hooks → observe_cli.mjs → Servidor API (SQLite) → Painel React
• O script de hook lê eventos brutos do stdin, adiciona o nome do projeto e os envia via POST para o servidor
• O servidor analisa eventos, armazena metadados do agente (nome, tipo, hierarquia) e encaminha eventos para clientes WebSocket
• O painel React deriva todo o estado do agente a partir do fluxo de eventos

Com o painel, você pode:

• Assistir chamadas de ferramentas chegando em tempo real (PreToolUse → PostToolUse com resultados)
• Ver a hierarquia completa do agente—qual subagente foi gerado por qual pai
• Filtrar por agente, tipo de ferramenta ou buscar em todos os eventos
• Expandir qualquer evento para ver o payload completo, comando e resultado
• Clicar nos ícones da linha do tempo para pular para eventos específicos no fluxo
• Navegar por sessões históricas com nomes legíveis por humanos (ex: "twinkly-hugging-dragon")

Instalação e Configuração

Pré-requisitos:

• Docker (obrigatório—o servidor é executado como um contêiner)
• Node.js (obrigatório—os scripts de hook são executados via node)

Etapas de instalação do plugin:

claude plugin marketplace add simple10/agents-observe
claude plugin install agents-observe

Após reiniciar o Claude Code, o servidor inicia automaticamente como um contêiner Docker na sua próxima sessão, e os hooks começam a capturar eventos. O painel está disponível em http://localhost:4981.

Habilidades do Plugin

• /observe — Abre a URL do painel e verifica se o servidor está em execução
• /observe status — Verifica a saúde do servidor e mostra a URL do painel

Insights de Desempenho do Desenvolvimento

O desenvolvedor compartilhou vários aprendizados técnicos da construção e uso da ferramenta:

• Os hooks do Claude Code são bloqueantes—o desempenho degrada rapidamente com muitos plugins que usam hooks
• Os hooks fornecem informações mais úteis do que os dados OTEL
• Os arquivos jsonl do Claude fornecem a imagem completa
• O gerenciamento do ciclo de vida dos processos MCP iniciados por plugins é "um pouco improvisado na melhor das hipóteses"
• Mudar para hooks em segundo plano (disparar e esquecer) e remover outros plugins melhorou significativamente o desempenho do Claude

O desenvolvedor implementou uma solução de gerenciamento de processos onde o servidor rastreia conexões ativas e desliga automaticamente quando não está em uso, então o plugin o reinicia quando uma nova sessão começa. Esta abordagem baseada em Docker é observada como um padrão que poderia melhorar a segurança isolando serviços.