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

CLI do CodeOps AI (AgentOps) para dar continuidade e governança ao trabalho de agentes de IA, como Claude Code e Codex. Ela mantém o contexto entre sessões, executa validações reais de build e testes e sincroniza handoffs, tarefas e histórico em um fluxo compartilhado pelo time.

O binário instalado se chama aops.

Instalação

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

Requer Node.js 20 ou superior.

Fluxo remoto recomendado

O servidor é a fonte de verdade para projeto, participantes e arquitetura canônica. Publique o projeto antes de o time começar: assim, todos trabalham com a mesma configuração e a mesma arquitetura.

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 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 execute aops update --write logo após aops init --write: o init já escreve os arquivos do projeto. aops setup configura o ambiente global da máquina; init e update configuram apenas o projeto atual.

Como funciona

O aops mantém estado local e uma outbox em .aops/agentops.db, mas a colaboração é remote-first: acesso, integrantes, arquitetura e histórico compartilhado vêm do backend. Use aops sync --write durante e ao final do trabalho para enviar evidências. A arquitetura canônica é remota; ARCHITECTURE.md só é atualizado após confirmação da API e não deve ser uma fonte alternativa editada manualmente.

Limite entre uso local e serviço hospedado

A CLI continua útil sem login para trabalho individual no clone: inicialização e leitura de arquivos, diagnósticos, validação de links, cache de contexto, sessão e outbox locais funcionam no disco do projeto. Esses dados não criam uma colaboração remota por si só.

Login, organização e projeto configurados são necessários para sincronizar eventos, consultar ou persistir histórico compartilhado, colaborar em equipe, publicar a arquitetura canônica e criar, aprovar ou aplicar planos de harness. A API revalida a identidade, o acesso ao projeto e o entitlement em cada operação remota; a CLI apenas apresenta o estado e as orientações de upgrade.

Um fork pode, portanto, manter o fluxo local para uso individual, mas não recebe acesso automático ao serviço hospedado nem às suas capacidades associadas a plano. A licença e a política para forks comerciais continuam decisões separadas, sujeitas à revisão jurídica.

Fluxo recomendado para uma sessão de agente:

aops context                              # carrega o resumo de continuidade
aops workflow check                       # verifica bloqueios operacionais
aops session begin --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 complete --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 complete --status completed --token-usage '{"inputTokens":1200,"outputTokens":300,"totalTokens":1500,"provider":"openai","model":"gpt-5"}'
aops sync --write

Uso de tokens por sessão e tarefa

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 deve ser cumulativo para evitar dupla contagem entre heartbeats. A API soma as sessões vinculadas e exibe o total na página da tarefa. Não estime valores nem envie prompts, respostas, credenciais ou logs brutos.

Comandos

Setup do projeto

| Comando | Descrição | |---|---| | aops init [path] [profile] --agent <claude\|codex\|gemini> | 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.). | | aops next | Indica a próxima ação operacional segura a partir da configuração, outbox e estado local. |

Arquitetura canônica

| Comando | Descrição | |---|---| | aops architecture analyze | Gera uma prévia da análise arquitetural a partir das fontes do projeto, sem gravar arquivos. | | aops architecture analyze --write | Publica a arquitetura analisada no backend e atualiza o ARCHITECTURE.md local após confirmação remota. | | aops architecture publish --file ARCHITECTURE.md | Publica um documento de arquitetura aprovado e grava a versão canônica retornada pelo backend. |

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 begin --agent <nome> | Abre uma sessão local ativa depois de executar workflow check. Se já existir uma sessão remota ativa do mesmo usuário/projeto, a CLI a recupera e grava o remoteSessionId local em vez de falhar. aops start e aops session check-in continuam como aliases de compatibilidade. | | 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 complete --status completed | Encerra a sessão local. aops finish e aops session check-out continuam como aliases de compatibilidade. | | 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 | Mostra, sem alterar nada, as sessões remotas ativas sem heartbeat recente. Usa lastHeartbeatAt como fonte principal de atividade e updatedAt apenas como fallback para registros legados. Use --write para encerrá-las. | | 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 risk block --risk-id <id> --reason "..." | Registra o bloqueio auditável de um risco, com suporte offline e sincronização posterior. | | aops workflow check | Verifica riscos, tarefas prioritárias e demais bloqueios operacionais antes de iniciar trabalho. |

Em .aops/policy.json, workflow.blockOnBlockedRisks controla riscos cuja task de origem está explicitamente blocked: o padrão false mantém o risco visível no handoff e libera trabalho técnico independente; true mantém o bloqueio total do workflow. Tasks de risco bloqueadas continuam correlacionadas por sourceKey e não são recriadas por aops risks sync --write.

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

Governança do harness

O harness de melhoria segue um fluxo protegido: primeiro analise somente os metadados sanitizados, revise a prévia, crie o plano, obtenha aprovação de owner/admin e aplique exclusivamente o plano aprovado. A aplicação valida o escopo, hash, catálogo, expiração e as validações declaradas.

| Comando | Descrição | |---|---| | aops harness status | Exibe a disponibilidade da análise, do plano local e a próxima ação segura. | | aops harness analyze | Gera .aops/harness-analysis.json a partir de metadados sanitizados do projeto. | | aops harness plan --dry-run | Mostra as alterações propostas, sem criar plano nem modificar arquivos. | | aops harness plan create --write | Cria o plano local e o registra como rascunho no projeto remoto configurado. | | aops harness approve --plan-id <id> --plan-file .aops/harness-plan.json | Registra a aprovação remota de owner/admin para o plano íntegro e não expirado. | | aops harness apply --plan-id <id> --plan-file .aops/harness-plan.json | Aplica um plano remoto aprovado e executa somente suas validações declaradas. | | aops harness watch --once --apply-approved --agent <agent-id> | Executa um ciclo controlado de busca e aplicação de planos aprovados. Para automação contínua, habilite explicitamente harness.applyApproved em .aops/config.json. |

Mantenha CI em modo informativo e revise o diff antes da aprovação. Quando disponíveis, a aplicação registra commitSha, pipelineId e evidenceId; uma melhoria permanece aguardando novo scan até a chegada de evidência recente do CI.

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 inspect | Mostra os eventos pendentes e rejeitados, a data do último sync e a próxima ação recomendada, sem enviar dados. | | 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.

Cache de contexto local

O cache reduz pesquisas repetidas sem substituir o código, os testes ou as fontes canônicas. O índice é estritamente local: armazena caminhos, hashes, tipos e palavras-chave das fontes permitidas; não armazena conteúdo bruto nem é enviado pelo sync.

| Comando | Descrição | |---|---| | aops cache build --write | Cria ou atualiza incrementalmente o índice local. | | aops cache status | Mostra se o índice existe e quando foi atualizado. | | aops cache brief --query "..." | Retorna referências locais relevantes e limitadas para uma tarefa. | | aops cache list --scope <área> | Lista entradas válidas dentro de um escopo. | | aops cache search --query "..." --include-content | Pesquisa conhecimento manual; use conteúdo somente quando necessário e confirme a fonte primária. | | aops cache check | Verifica a validade das entradas antes da reutilização. |

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. |

Evidência de qualidade no CI

Para preparar a coleta de Harness Score sem alterar o pipeline, gere primeiro a prévia e revise seus arquivos e secrets esperados:

aops ci init --provider gitlab
aops ci init --provider github

Após a revisão explícita, --write adiciona um bloco gerenciado ao GitLab ou um workflow dedicado ao GitHub. A integração usa apenas os nomes CODEOPS_API_URL, CODEOPS_PROJECT_ID e CODEOPS_INGESTION_TOKEN; seus valores devem permanecer nos secrets protegidos do provedor. O job publica quality-evidence.json e continua em modo inform.

Métricas locais

| Comando | Descrição | |---|---| | aops metrics | Exibe duração de sessão, eventos pendentes/sincronizados e data do último sync. Campos sem dados 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, session begin e sync --write recuperam automaticamente a 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
# depois de revisar a prévia:
aops session close-stale --timeout 60m --write
# 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. | | aops risk block --risk-id <id> --reason "..." | Bloqueia o risco persistido no handoff, registra autor/data/motivo localmente e sincroniza para a API com aops sync --write. Repetições são idempotentes. |

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.

aops codex install-hooks --write instala os hooks Git e a configuração .codex/hooks.json para o ciclo de vida do Codex. Os hooks locais aplicam feedback e guardas de segurança, mas não substituem a aprovação remota exigida para aplicar planos de harness.

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/context-cache.db | Não (.gitignore) | Índice local e derivado do cache de contexto; nunca é sincronizado. | | .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 e AOPS_PROJECT_ID sobrescrevem os valores de .aops/config.json. Forneça AOPS_ACCESS_TOKEN apenas pelo ambiente seguro do processo; nunca o versione.

Licença

MIT