agent-progress

Protocolo universal de progresso + HUD de terminal para agentes de codificação de IA (Claude Code, Codex). v0.1 — MVP local, ainda não publicado no npm.

Progresso verificável, nunca estimado:

% = tarefas concluídas / tarefas totais × 100

Sem plano/checklist confiável (nenhum task.created ainda), o HUD mostra Progresso: indeterminado — nunca um número inventado. Contrato completo dos eventos: PROTOCOL.md. Comportamento funcional: SPEC.md.

Uso

Standalone (sem memória persistente, você mesmo alimenta os eventos):

agent-progress init
agent-progress watch

Integrado com AI Universal Memory (auto-start real, comprovado com claude/codex de verdade — ver ai-universal-memory's README para o fluxo completo):

aum init
claude   # ou: codex

Sem agent-progress watch/hud-start manual — o HUD abre sozinho no SessionStart e fecha sozinho quando o run termina (Windows; nas demais plataformas, sem auto-open — agent-progress watch continua funcionando manualmente, ver "Auto-HUD" abaixo). .memory/ (memória do AUM) e .agent-progress/ (este pacote, estado efêmero de execução) nunca se misturam — ver AGENTS.md deste repo.

Instalação (local, provisória)

Ainda não publicado no npm (package.json tem "private": true de propósito). Duas formas locais testadas:

# a partir do checkout deste repo
npm link

# ou, empacotado
npm pack
npm install /caminho/para/agent-progress-0.1.0.tgz

Requer Node.js ≥ 18. Zero dependências externas.

CLI

agent-progress init      # cria .agent-progress/{state.json,events.jsonl} no projeto monitorado
agent-progress watch     # abre o HUD ao vivo, lendo .agent-progress/events.jsonl
agent-progress hud-start # garante que o HUD está rodando (idempotente); spawna uma janela nova se preciso
agent-progress status    # imprime um snapshot pontual do estado atual
agent-progress event ... # registra um evento do protocolo (uso interno dos adapters)
agent-progress mock      # reproduz TASKS.json como execução simulada (indeterminado → 0% → 100%)

Auto-HUD (hud-start)

agent-progress hud-start é idempotente: se já existe uma janela watch viva para o projeto (rastreada via .agent-progress/hud.lock, checando se o pid gravado ainda está de pé), não faz nada. Caso contrário, abre uma nova janela de terminal rodando agent-progress watch --auto-exit. Windows-first — nas demais plataformas é um no-op documentado (imprime instrução para rodar agent-progress watch manualmente; não quebra o pacote).

agent-progress watch --auto-exit (só usada pela janela auto-spawnada, não muda o comportamento do watch manual) encerra sozinha, sem deixar processo órfão, alguns segundos depois de ver o run mais recente chegar a um estado terminal (completed/failed) — tempo suficiente para o estado final ficar visível antes da janela fechar.

agent-progress init cria .agent-progress/ no projeto monitorado — adicione essa pasta ao .gitignore do projeto monitorado (é estado efêmero de execução, não deve ir para o controle de versão). Isso é diferente da memória persistente do próprio agent-progress (se você estiver usando AUM neste repo, ver AGENTS.md).

Adapter Claude Code

src/adapters/claude.js traduz hooks nativos do Claude Code (SessionStart, SessionEnd, TaskCreated, TaskCompleted, PostToolUse de TaskUpdate, SubagentStart, SubagentStop) para o Agent Progress Protocol. Configure em .claude/settings.json do projeto monitorado:

{
  "hooks": {
    "SessionStart":   [ { "hooks": [ { "type": "command", "command": "node \"/caminho/para/agent-progress/src/adapters/claude.js\"" } ] } ],
    "SessionEnd":     [ { "hooks": [ { "type": "command", "command": "node \"/caminho/para/agent-progress/src/adapters/claude.js\"" } ] } ],
    "TaskCreated":    [ { "hooks": [ { "type": "command", "command": "node \"/caminho/para/agent-progress/src/adapters/claude.js\"" } ] } ],
    "TaskCompleted":  [ { "hooks": [ { "type": "command", "command": "node \"/caminho/para/agent-progress/src/adapters/claude.js\"" } ] } ],
    "SubagentStart":  [ { "hooks": [ { "type": "command", "command": "node \"/caminho/para/agent-progress/src/adapters/claude.js\"" } ] } ],
    "SubagentStop":   [ { "hooks": [ { "type": "command", "command": "node \"/caminho/para/agent-progress/src/adapters/claude.js\"" } ] } ],
    "PostToolUse":    [ { "matcher": "TaskUpdate", "hooks": [ { "type": "command", "command": "node \"/caminho/para/agent-progress/src/adapters/claude.js\"" } ] } ]
  }
}

Limitações conhecidas (v0.1): sem hierarquia nativa de tarefas (o TaskCreate do Claude Code não tem parentId, então as tarefas do adapter Claude são sempre de nível raiz); sem task.failed nativo (TaskUpdate só tem pending/in_progress/completed/deleted); sem run.failed (SessionEnd não carrega indicador de erro).

Adapter Codex

src/adapters/codex.js lê o stream JSONL de codex exec --json via stdin e traduz para o protocolo:

codex exec --json "sua tarefa" | node /caminho/para/agent-progress/src/adapters/codex.js

Use AGENT_PROGRESS_CWD para apontar o .agent-progress/ de um projeto diferente do diretório atual, e AGENT_PROGRESS_CODEX_MODEL para exibir o nome do modelo no HUD (o stream do Codex não inclui essa informação — limitação conhecida, não inferida).

Limitação conhecida: codex exec é assumido single-turn (um run por thread); turn.failed foi implementado por analogia ao restante do protocolo mas nunca foi observado nas capturas reais usadas para construir o adapter.

HUD multiagente (Claude Code + Codex simultâneos)

Compartilhe um runId externo entre os dois adapters com AGENT_PROGRESS_RUN_ID (e AGENT_PROGRESS_CWD apontando para o mesmo .agent-progress/) para que agent-progress watch represente ambos no mesmo HUD. Quando ambos os lados recebem um runId externo, nenhum dos dois fecha o run automaticamente — um orquestrador externo deve emitir o run.completed/run.failed final via agent-progress event.

Desenvolvimento

npm test          # suíte node:test (core, progress, renderer, adapters)
node src/cli.js mock   # roda TASKS.json como demo local, sem agente real

Sem dependências, sem servidor, sem banco de dados — apenas Node.js ESM, node:test e ANSI puro via process.stdout. Ver AGENTS.md/CLAUDE.md para as regras operacionais deste projeto.