AI Agent Factory (AI Monitor Agent)

Skill e monitor local para Claude Code, Codex e Grok. A distribuição é feita como pacote Python: instala-se pelo PyPI e, em seguida, registra-se a skill nos assistentes disponíveis no usuário atual.

A página principal é uma fábrica visual: cada sessão do Claude Code (e cada subagente) é um robô numa linha de produção, animado conforme eventos reais recebidos em tempo real por WebSocket.

O monitor não inicia tarefas de IA por conta própria. O conector do Claude Code está implementado via hooks oficiais; Codex e Grok ainda não têm conector (só via SDK).

Requisitos

• Python 3.11 ou superior.
• Acesso à Internet para baixar o pacote e suas dependências.

Instalação pelo PyPI

Quando o pacote estiver publicado:

python -m pip install ai-monitor-agent
ai-monitor-agent install

No Windows:

py -m pip install ai-monitor-agent
ai-monitor-agent install

Para uma instalação isolada, use pipx install ai-monitor-agent e depois ai-monitor-agent install.

Instalação local durante o desenvolvimento

Na raiz deste repositório, instale o pacote e suas dependências diretamente:

python -m pip install .
ai-monitor-agent install

No Windows:

py -m pip install .
ai-monitor-agent install

O comando install instala também os hooks HTTP do Claude Code em ~/.claude/settings.json (fusão que preserva os seus hooks; backup em settings.json.bak). Para os remover: ai-monitor-agent uninstall-hooks.

O comando install copia a skill para os diretórios pessoais do Claude Code (~/.claude/skills/ai-monitor-agent/) e dos assistentes compatíveis com o diretório padrão de skills (~/.agents/skills/ai-monitor-agent/). Reinicie o aplicativo de IA após a instalação se a skill não aparecer.

Utilização

Inicie o monitor dentro do repositório que deseja acompanhar:

ai-monitor-agent start

Ou invoque a skill no assistente:

• Claude Code: /ai-monitor-agent
• Codex: $ai-monitor-agent
• Grok: /ai-monitor-agent

Para verificar ou encerrar:

ai-monitor-agent status
ai-monitor-agent stop

A página é criada em <raiz-do-repositório>/agents-monitor/index.html; a raiz é identificada pelo Git. Fora de um repositório Git, é usado o diretório atual. O servidor tenta usar a porta 6999 e escolhe outra porta livre se necessário — mas os hooks apontam para 6999 (ou FACTORY_PORT no momento do install), por isso a CLI avisa se a porta mudou. O painel atualiza em tempo real via WebSocket.

Fábrica visual

• Linhas agrupam agentes por sessão (sessão + subagentes), projeto, plataforma ou estado; Entrada mostra pedidos em curso e Expedição os concluídos/falhados.
• Estados: repouso, a iniciar, a trabalhar, a pensar, à espera, precisa de aprovação, bloqueado, erro, concluído, offline — sempre com ícone + texto, não só cor. Se um agente "ativo" fica 90 s sem eventos, a animação para e aparece "Sem sinal há…".
• Progresso e ETA só aparecem quando reportados; caso contrário, "Desconhecido".
• Clique num robô para ver identidade, atividade, eventos completos (entrada/saída das ferramentas), comandos suportados e histórico.
• Pesquisa, filtros, zoom (Ctrl+roda), arrastar, colapsar linhas, vista em lista, "Reduzir movimento" (respeita prefers-reduced-motion).
• Emergency Stop bloqueia novos comandos e a entrega de instruções em fila; não interrompe processos já em curso.

Conector Claude Code

Hooks usados: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, Notification, SubagentStart, SubagentStop, Stop, StopFailure, SessionEnd, PreCompact (testado com Claude Code 2.1.224). Falhas de ligação são não-bloqueantes: com o monitor parado o Claude Code continua normal.

• Instruções: send_instruction é entregue no próximo hook da sessão (como contexto após uma ferramenta/pedido, ou continuando o turno no Stop).
• Não suportado: pausar, retomar, cancelar, aprovar remotamente, deep link para a sessão.
• Privacidade: são guardados localmente (SQLite em ~/.ai-agent-factory/data) o texto dos pedidos, entradas e saídas das ferramentas (truncados a ~4 KB) e a última mensagem de cada turno. Nada sai da máquina.

O runtime, o banco de dados e os logs ficam em ~/.ai-agent-factory/.

Desenvolvimento e publicação

Execute os testes:

python -m unittest discover -s test

Para construir o pacote localmente, use python -m pip install build e python -m build. A publicação no PyPI requer uma conta PyPI e deve ser feita por um mantenedor autorizado. Publicado em https://pypi.org/project/ai-monitor-agent/.

API

• GET /health — estado do serviço
• POST /api/v1/agents, GET /api/v1/agents — registar/listar agentes
• POST /api/v1/tasks, GET /api/v1/tasks — criar/listar tarefas
• POST /api/v1/events, GET /api/v1/events — publicar/listar eventos
• POST /api/v1/commands, GET /api/v1/commands?agent_id= — enfileirar/listar comandos (rejeita comandos fora das capacidades do agente)
• GET|POST /api/v1/emergency-stop — estado / ativar-desativar
• POST /api/v1/connectors/claude-code/hook — receção de hooks do Claude Code
• GET /api/v1/events?agent_id= — eventos de um agente
• GET /api/v1/commands/pending/{agent_id} — consultar comandos
• POST /api/v1/commands/{command_id}/ack — confirmar comando
• WS /ws — atualizações em tempo real

Segurança e limitações

O serviço escuta apenas em 127.0.0.1 e não tem autenticação. Não o exponha à Internet ou a redes não confiáveis. Os comandos enviados pela API são apenas enfileirados; um conector compatível precisaria buscá-los e executá-los. A skill não coleta prompts e o monitor não fica executando chamadas aos modelos em segundo plano.