@code-ops-ai/app-aops-cli

CLI de linha de comando para o CodeOps AI (AgentOps): dá a agentes de IA (Claude Code, Codex, etc.) contexto de continuidade entre sessões, um harness real de validação (roda comandos de build/teste de verdade em vez de aceitar autorrelato) e um fluxo remoto compartilhado para handoffs, tarefas e histórico entre desenvolvedores.

O binário instalado se chama aops.

Instalação

npm install -g @code-ops-ai/app-aops-cli
aops --version

Requer Node.js >= 20.

Fluxo remoto recomendado

O servidor é a fonte de verdade para o projeto, seus integrantes e a arquitetura canônica. O trabalho do time começa depois que o tech lead publica o projeto; isso evita que cada máquina use uma configuração ou arquitetura divergente.

Tech lead: preparar e publicar

1. No dashboard, crie a equipe, adicione os desenvolvedores e atribua a si o papel de tech_lead.
2. Em Projects, crie o projeto associado à equipe e copie seu ID.
3. No clone do repositório, instale a CLI e autentique-se:

npm install -g @code-ops-ai/app-aops-cli
aops login

4. Vincule explicitamente o clone ao projeto remoto e grave a configuração local:

aops configure --write --project-id <project-id>

5. Inicialize o projeto:

aops init --write
aops setup --write

Para um aplicativo mobile, use aops init mobile --write explicitamente quando o repositório também tiver backend ou frontend web. Sem perfil, aops init --write reconhece React Native/Expo, Flutter, Android nativo e iOS nativo apenas quando os sinais da stack são inequívocos. Repositórios híbridos exigem uma escolha explícita para não receber instruções erradas.

As validações continuam sendo definidas pelo próprio projeto em .aops/policy.json. Use somente comandos que já existam na stack, como testes Flutter, Gradle ou Xcode quando aplicáveis; não adicione toolchains mobile à policy padrão.

Com um projeto remoto configurado, aops init --write envia a análise do repositório, recebe a versão canônica da arquitetura, grava ARCHITECTURE.md somente com esse conteúdo e solicita a publicação. Caso o servidor esteja indisponível ou um requisito esteja pendente, ele não deve ser tratado como publicado: corrija a pendência e execute novamente o comando.

Desenvolvedor: entrar em um projeto já publicado

O desenvolvedor deve estar na equipe do projeto e receber o <project-id> do tech lead. Não crie outro projeto remoto para contornar falta de acesso.

npm install -g @code-ops-ai/app-aops-cli
aops login
aops configure --write --project-id <project-id>
aops setup --write
aops context

Se aops configure informar que o projeto não foi encontrado ou não está acessível, confirme a associação à equipe e peça ao tech lead para concluir a publicação. Projetos em rascunho ou configurando não são disponibilizados a desenvolvedores.

Para um projeto que já foi inicializado antes, use update para reaplicar o bloco gerenciado com a versão atual da CLI:

aops update --write
aops setup --write

Se o time também usa Claude Code, o tech lead ou cada desenvolvedor pode rodar o setup global do Claude além do setup do Codex:

aops setup --agent claude --write

Não é necessário rodar aops update --write logo após aops init --write: o init já escreve os arquivos do projeto. O codex setup configura o ambiente global da máquina, enquanto init/update configuram o projeto atual.

Conceito

O aops mantém seu estado local e a outbox em .aops/agentops.db, mas a colaboração é remote-first: acesso ao projeto, membros, arquitetura e histórico do time dependem do backend. Use aops sync --write durante e ao final do trabalho para enviar evidências ao contexto compartilhado. A arquitetura canônica é remota; ARCHITECTURE.md só é escrito após confirmação da API e não deve ser editado localmente como fonte alternativa.

Fluxo típico de uma sessão de agente:

aops context                              # carrega o resumo de continuidade
aops workflow check                       # verifica bloqueios operacionais
aops session check-in --agent claude      # abre uma sessão local
# ... trabalho normal do agente ...
aops session heartbeat --status "implementando validações"
aops validation add --command "pnpm test" --execute   # roda o comando de verdade
aops agent complete --summary "..." --files "a.ts,b.ts" --sync
aops session check-out --status completed
aops sync --write

Para transportar o uso real informado pelo provedor durante o fluxo local:

aops session heartbeat --token-usage '{"inputTokens":1200,"outputTokens":300,"totalTokens":1500,"provider":"openai","model":"gpt-5"}'
aops session check-out --status completed --token-usage '{"inputTokens":1200,"outputTokens":300,"totalTokens":1500,"provider":"openai","model":"gpt-5"}'
aops sync --write

Consumo de tokens por sessão e task

Quando o provedor de IA retornar metadados de uso, o adaptador do agente deve enviar um snapshot cumulativo no heartbeat e no encerramento da sessão. O SDK aceita inputTokens, outputTokens, totalTokens, provider e model:

await client.operations.heartbeatSession(sessionId, {
  tokenUsage: {
    inputTokens: 1200,
    outputTokens: 300,
    totalTokens: 1500,
    provider: "openai",
    model: "gpt-5"
  }
});

await client.operations.completeSession(sessionId, {
  status: "completed",
  tokenUsage: { inputTokens: 1200, outputTokens: 300, totalTokens: 1500 }
});

O snapshot é cumulativo para evitar dupla contagem entre heartbeats. A API soma as sessões vinculadas e exibe o total na página da task. Não estime valores e nunca envie prompts, respostas, credenciais ou logs brutos.

Comandos

Setup do projeto

| Comando | Descrição | |---|---| | aops init [path] [profile] --agent <claude\|codex> | Detecta a stack e gera CLAUDE.md/AGENTS.md, .aops/policy.json e o skill tlc-spec-driven. Quando o clone já está vinculado a um projeto remoto e o tech lead usa --write, sincroniza a arquitetura canônica e publica o projeto após a validação do servidor. | | aops update --write | Reaplica o mesmo conteúdo gerenciado do init sobre um projeto já inicializado, preservando conteúdo customizado fora do bloco gerenciado. Use quando a CLI evoluir e o projeto precisar receber as instruções novas. | | aops configure --write --project-id <id> | Associa o diretório atual a um projeto remoto existente e grava .aops/config.json local. Para desenvolvedores, o projeto precisa estar publicado e a pessoa precisa pertencer à equipe. | | aops login | Login via navegador (device flow) contra o backend, grava accessToken na config global (~/.aops/config.json). | | aops doctor | Verificações de config/drift: package.json, lockfile, .gitignore, AGENTS.md/CLAUDE.md desatualizados em relação ao gerador, specs não sincronizadas. | | aops whoami | Mostra o usuário autenticado no backend. | | aops status | Resumo do projeto local (stack detectada, apps do monorepo, etc.). |

Sessão e continuidade

| Comando | Descrição | |---|---| | aops context | Carrega o resumo de continuidade: última tarefa, última sessão, riscos pendentes, sessões conflitantes de outros devs, última validação. Rodar no início de toda sessão de agente. | | aops session check-in --agent <nome> (= aops start) | Abre uma sessão local ativa. Se já existir uma sessão remota ativa do mesmo usuário/projeto, a CLI recupera essa sessão e grava o remoteSessionId local em vez de falhar. | | aops session start --agent <nome> | Executa workflow check antes de abrir a sessão. Se houver bloqueio operacional, informa o próximo passo e não inicia a sessão. | | aops session heartbeat --status "..." | Registra progresso intermediário durante o trabalho. No sync remoto, atualiza lastHeartbeatAt da sessão e também mantém um handoff resumido no histórico. | | aops session check-out --status completed (= aops finish) | Encerra a sessão local. | | aops session list | Lista sessões remotas do projeto configurado. Útil para diagnosticar sessões ativas antes de sincronizar. | | aops session close <session-id> --status completed\|failed\|canceled | Encerra uma sessão remota específica usando o endpoint oficial da API. | | aops session close-stale --timeout 60m | Encerra sessões remotas ativas sem heartbeat recente. Usa lastHeartbeatAt como fonte principal de atividade e updatedAt apenas como fallback para registros legados. | | aops handoff --summary "..." | Registra um handoff (repasse de contexto) local. | | aops handoff suggest | Sugere arquivos alterados e validações aprovadas para apoiar a criação do handoff, sem gravar estado. | | aops handoff check --summary "..." --next-steps "..." --tests "..." --risks "..." --files "..." | Verifica a completude do handoff e emite avisos para campos ausentes, sem bloquear o comando. | | aops event send <nome> --payload '{...}' | Registra um evento arbitrário local. | | aops task create --title "..." | Registra a criação de uma tarefa operacional local. | | aops tasks import --from .specs/features/<feature>/tasks.md --write | Importa diretamente tasks geradas pelo tlc-spec-driven a partir de um tasks.md, criando tarefas operacionais locais com source=spec. | | aops risks sync --write | Promove risks acionáveis encontrados em handoffs/eventos para tarefas operacionais locais com source=risk, mantendo idempotência local. | | aops workflow check | Verifica riscos, tarefas prioritárias e demais bloqueios operacionais antes de iniciar trabalho. |

Validação (harness) e conclusão

| Comando | Descrição | |---|---| | aops validation add --command "..." --status passed\|failed\|skipped | Autorrelato: registra que uma validação foi executada, sem rodar nada. | | aops validation add --command "..." --execute [--timeout <ms>] | Harness real: executa o comando de verdade e deriva status do exit code (0 → passed, senão failed). Qualquer --status informado junto é ignorado. | | aops loop check | Executa sequencialmente todas as requiredValidations da policy, registra um evento por comando e retorna exit code 0 apenas quando todas passam. Sem policy ou validações configuradas, retorna 0 com aviso. | | aops agent complete --summary "..." --files "a.ts,b.ts" --tests "..." --risks "..." [--sync] | Registra a conclusão da tarefa (resumo do que mudou, arquivos, testes, riscos). Com --sync, sincroniza imediatamente com o backend. |

Gate de qualidade opcional: se o projeto tiver um .aops/policy.json versionado com requiredValidations, aops agent complete --sync bloqueia até existir, na sessão atual, uma validação passed para cada comando obrigatório:

{ "requiredValidations": ["pnpm test", "pnpm build"] }

Um driver externo pode usar aops loop check como critério objetivo de parada:

if aops loop check; then
  echo "critério de parada atingido"
fi

Sincronização remota

| Comando | Descrição | |---|---| | aops sync --dry-run | Mostra o plano de sincronização (o que seria enviado) sem tocar o backend. | | aops sync --write | Envia os eventos locais pendentes (validações, handoffs, tarefas, heartbeats, conclusão de sessão) para o backend configurado. Antes de criar uma sessão remota nova, tenta reutilizar uma sessão ativa recuperável do mesmo usuário/projeto. | | aops sync retry --write | Repete uma sincronização pendente de forma explícita; o --write é obrigatório. |

O sync é sempre explícito — nada é enviado à rede sem --write. Isso não substitui a configuração e a publicação remotas: elas são pré-requisitos para o acesso compartilhado ao projeto.

Diagnóstico e documentação

| Comando | Descrição | |---|---| | aops profile suggest | Sugere o perfil documentation quando os arquivos alterados forem somente Markdown; caso haja código, sugere behavior. A sugestão não grava estado nem substitui uma escolha explícita. | | aops docs check-links | Valida links relativos locais em arquivos Markdown. URLs externas e âncoras são ignoradas; links inexistentes retornam o arquivo, a linha e o destino. | | aops metrics | Exibe métricas locais disponíveis: duração de sessão, eventos pendentes e sincronizados e data do último sync. Campos sem dado são reportados como indisponíveis. |

Ofertas da plataforma

Usuários autenticados de organizações no plano Free podem receber uma oferta discreta após init, configure, sync ou context concluírem com sucesso. A mensagem é emitida somente em stderr, no máximo uma vez a cada 7 dias, e aponta para a URL segura de billing retornada pela API. Ela nunca aparece em JSON, CI, pipes, erros ou para planos pagos.

Use aops plan para consultar o plano e a URL de billing, aops promotions status para conferir a preferência e a próxima elegibilidade e aops config set promotions false para desativar as ofertas (reative com true). A CLI não mede cliques; falhas de rede ou do cache são silenciosas e jamais alteram o exit code do comando solicitado.

Sessões remotas e conflitos

O backend mantém no máximo uma sessão ativa por usuário/projeto. Isso evita histórico fragmentado e mantém cada mudança rastreável pelo userId.

Quando a sessão ativa pertence ao mesmo usuário autenticado, check-in e sync --write fazem recuperação automática da sessão remota. Quando a sessão ativa pertence a outro usuário, aops context continua emitindo warning para evitar mistura de trabalho entre desenvolvedores.

Para limpar sessões órfãs:

aops session list
aops session close-stale --timeout 60m
# ou, se precisar encerrar uma sessão específica:
aops session close <session-id> --status completed

Spec-Driven Development

| Comando | Descrição | |---|---| | aops spec sync [--write] | Importa artefatos gerados pelo skill tlc-spec-driven (.specs/features/<feature>/) para o histórico local/remoto. Depois da aprovação de tasks.md, cria tarefas operacionais; depois de validation.md, reconcilia evidências do verifier. | | aops tasks import --from .specs/features/<feature>/tasks.md [--write] | Importação direta de um arquivo tasks.md quando o techlead quer trazer tasks TLC sem depender do scan completo de specs. Sem --write, roda em dry-run. |

Risks

| Comando | Descrição | |---|---| | aops risks sync [--write] | Analisa risks em handoffs/eventos locais e sincronizados, promove itens acionáveis para tarefas operacionais com source=risk e evita duplicação por sourceKey. Sem --write, roda em dry-run. |

Codex Toolkit

aops codex <subcomando> cobre o bootstrap e a migração de configurações do Codex CLI (perfis, modos, sincronização de AGENTS.md, geração de relatórios, etc.). O aops setup --write configura arquivos globais da máquina, incluindo ~/.codex/parts/agentops.md, aliases e ~/.codex/config.toml. Para Claude, aops setup --agent claude --write escreve ~/.claude/CLAUDE.md e .claude/settings.json. Os blocos de AgentOps/Spec usados aqui são os mesmos gerados por aops init/aops update, evitando drift entre setup global e projeto.

Subcomandos: setup, build, mode, status, project-info, profile, sync, restore, run, flow, test-gen, ci-run, pr-review, architecture-report, changelog-gen, auto-refactor, new-mode, new-profile, lint-agents, doctor. Veja aops codex doctor e aops help para o detalhe de cada um.

Utilitário

| Comando | Descrição | |---|---| | aops --version / aops -v / aops version | Imprime a versão instalada. | | aops help | Lista todos os comandos e flags. |

Toda saída aceita --json para uso em scripts/outros agentes.

Arquivos de configuração

| Arquivo | Versionado? | Conteúdo | |---|---|---| | .aops/config.json | Não (.gitignore) | apiUrl, accessToken, organizationId, projectId — por máquina/dev. | | .aops/agentops.db | Não (.gitignore) | Sessão local, estado operacional e outbox de eventos. | | .aops/policy.json | Sim | requiredValidations — comandos obrigatórios para agent complete --sync, compartilhado pelo time. | | ARCHITECTURE.md | Conforme a política do repositório | Cópia local da arquitetura canônica retornada pelo servidor. O tech lead a gera pela CLI; a versão canônica fica disponível no dashboard. |

Variáveis de ambiente

AOPS_API_URL, AOPS_ACCESS_TOKEN, AOPS_ORGANIZATION_ID, AOPS_PROJECT_ID sobrescrevem os valores lidos de .aops/config.json.

Licença

MIT