CodeOps AI CLI (aops)
O sistema operacional de governança, continuidade e observabilidade para agentes de IA de codificação.
Plataforma Oficial: https://aops.kw13.com.br
CLI do CodeOps AI (AgentOps) para dar continuidade, governança e confiabilidade ao trabalho de agentes de inteligência artificial de codificação.
Compatível nativamente com Google Antigravity, Gemini CLI, Claude Code e Codex.
O binário instalado se chama aops.
[!IMPORTANT]
🤖 Como funciona: Você não precisa se preocupar com a execução de cada comando!
A CLI
aopsfoi projetada para ser o motor operacional autônomo do seu agente de IA.
- O que o agente faz de forma autônoma: Quase todos os comandos operacionais listados neste manual (como
aops context,aops workflow check,aops task start,aops session begin,aops validation add --execute,aops agent complete,aops handoffeaops sync --write) são executados diretamente pelo próprio agente durante o ciclo de trabalho dele.- O que você (desenvolvedor) faz: Você só precisa instalar a CLI, conectar ao seu projeto uma única vez (
aops logineaops configure) e conversar com o agente no chat. Você não precisa memorizar nem rodar comandos de ciclo de vida na mão.
Quem executa o quê? (Divisão de responsabilidades)
Para que sua experiência seja simples e sem sobrecarga, veja como as tarefas são divididas:
| Atividade | Quem executa? | Exemplos de comandos |
|---|---|---|
| Instalação global da CLI | 👤 Você (Desenvolvedor) | npm install -g @code-ops-ai/app-aops-cli |
| Login na plataforma | 👤 Você (Desenvolvedor) | aops login |
| Vincular o repositório ao projeto | 👤 Você ou Tech Lead | aops configure --write --project-id <id> |
| Inicializar regras do agente | 👤 Você (uma vez) | aops init --write |
| Carregar contexto de continuidade | 🤖 Agente de IA (automático) | aops context |
| Inicialização de sessão e tarefa (Bootstrap) | 🤖 Agente de IA (automático) | aops agent init --agent <nome> |
| Verificar bloqueios e tarefas prioritárias | 🤖 Agente de IA (automático) | aops workflow check |
| Reivindicar ou criar tarefa | 🤖 Agente de IA (automático) | aops task start --task-id <id> / aops task create --title "..." |
| Abrir e acompanhar sessão | 🤖 Agente de IA (automático) | aops session begin / aops session heartbeat |
| Executar testes e validações reais | 🤖 Agente de IA (automático) | aops validation add --command "pnpm test" --execute |
| Conclusão unificada, handoff e telemetria | 🤖 Agente de IA (automático) | aops agent complete --summary "..." --tests "..." --risks "..." |
| Sincronizar eventos pendentes | 🤖 Agente de IA (automático) | aops sync --write |
Guia Rápido (Quickstart em 3 passos)
1. Instale a CLI globalmente
Requer Node.js 20 ou superior.
npm install -g @code-ops-ai/app-aops-cli
aops --version
2. Inicialize o projeto ou conecte-se à sua equipe
Para iniciar a governança em um projeto novo:
Um único comando inicializa as regras de governança (GEMINI.md, AGENTS.md ou CLAUDE.md), políticas de teste, skills e configura o servidor MCP tanto para o Google Antigravity quanto para o Cursor:
aops init --write
Para conectar seu repositório à nuvem (Dashboard & Telemetria):
Faça login no terminal (autenticação segura via navegador na plataforma aops.kw13.com.br) e vincule o diretório do projeto ao ID fornecido no dashboard (aops.kw13.com.br/projects):
aops login
aops configure --write --project-id <seu-project-id>
3. Deixe o Agente Trabalhar!
Abra o seu assistente de IA favorito (Google Antigravity, Gemini CLI, Claude Code ou Codex) na raiz do projeto e faça sua solicitação normalmente pelo chat:
"Quais tarefas tenho para fazer hoje?" "Implemente a funcionalidade X com testes unitários"
O agente lerá o contexto com aops context, verificará bloqueios com aops workflow check, executará o código, rodará a suíte de testes de verdade e salvará as evidências de validação. Você não precisa se preocupar com a execução de cada comando operacional.
Configuração por Perfil
Tech lead: preparar e publicar um novo projeto
- No dashboard da plataforma, crie a organização e a equipe, adicionando os membros.
- Em Projects, crie o projeto e obtenha seu ID.
- No clone do repositório, instale a CLI, inicialize a governança e conecte-se:
npm install -g @code-ops-ai/app-aops-cli
aops init --write
aops login
aops configure --write --project-id <project-id>
Em terminais interativos, aops init permite escolher a orientação arquitetural (clean, hexagonal ou existing). A escolha orienta o agente sem criar código desnecessário.
Com o projeto remoto vinculado, aops init --write analisa o repositório, valida com a API e publica a arquitetura canônica em ARCHITECTURE.md.
Desenvolvedor: entrar em um projeto já publicado
Como o projeto já possui os arquivos de governança versionados no Git pelo tech lead, o desenvolvedor só precisa clonar o repositório e rodar:
npm install -g @code-ops-ai/app-aops-cli
aops login
aops configure --write --project-id <project-id>
aops context
Atalhos Opcionais de Shell (aops setup)
O comando aops setup é opcional. Ele serve para desenvolvedores que desejam adicionar atalhos de terminal (aliases no ~/.bashrc ou ~/.zshrc, como gminit, gmdebug, gmreview):
# Opcional: apenas se desejar aliases globais no seu terminal
aops setup --write
Como funciona nos bastidores
O aops mantém o estado local e uma fila de eventos (outbox) em .aops/agentops.db, operando em modo remote-first:
- As sessões, tarefas, integrantes e a arquitetura canônica vêm do backend da plataforma aops.kw13.com.br.
- A cada tarefa concluída, o agente executa
aops sync --write, garantindo que toda a equipe no dashboard (aops.kw13.com.br) veja em tempo real o que foi implementado, quais testes passaram e quais riscos foram identificados. - Telemetria de Tokens Privada: Snapshots cumulativos de tokens gastos na sessão são sincronizados sem jamais enviar prompts, códigos privados, respostas de IA ou logs brutos.
Referência Completa de Comandos
(Esta seção serve como referência técnica detalhada, para auditoria, scripts ou automação de CI/CD)
Setup do Projeto
| Comando | Descrição |
|---|---|
aops init [path] [profile] --agent <claude|codex|gemini> --architecture <clean|hexagonal|existing> | Detecta a stack e gera as instruções do agente, .aops/policy.json e skills TLC. |
aops update [--agent <claude|codex|gemini>] --write | Reaplica o bloco gerenciado de instruções preservando customizações do projeto. |
aops configure --write --project-id <id> | Vincula o clone ao projeto remoto no dashboard. |
aops login | Autenticação via navegador (device flow), persistindo o token em ~/.aops/config.json. |
aops doctor | Inspeciona sanidade local, drift de instruções, dependências e status das specs. |
aops scan | Executa o diagnóstico completo e avalia a nota de maturidade de IA (AI Readiness Score). |
aops whoami | Exibe o usuário atualmente autenticado. |
aops status | Exibe o resumo do projeto local (stack detectada, monorepo, etc.). |
aops next | Indica a próxima ação operacional recomendada. |
Ciclo Operacional Unificado (AgentOps Workflow)
Toda a governança de sessão, vinculação de tarefas, validações e handoff é executada através de dois pontos de contato atômicos pelos agentes:
| Comando | Descrição |
|---|---|
aops agent init --agent <nome> | Inicia a sessão puxando automaticamente a próxima tarefa prioritária da fila do usuário. |
aops agent init --agent <nome> --task-id <id> | Inicia a sessão vinculando uma tarefa específica pré-existente. |
aops agent init --agent <nome> --title "..." --priority <urgent|high|normal|low> | Task Creation Gate: inicializa a sessão criando uma tarefa instantânea no backend para demandas ad-hoc. |
aops agent complete --summary "..." --tests "..." --risks "..." [--sync] | Detecta arquivos alterados no git, valida políticas, registra riscos, efetua handoff e conclui a sessão. |
Arquitetura Canônica
| Comando | Descrição |
|---|---|
aops architecture analyze | Analisa a arquitetura do projeto a partir do código fonte (sem gravar arquivos). |
aops architecture analyze --write | Publica a arquitetura analisada no backend e atualiza o ARCHITECTURE.md local. |
aops architecture publish --file ARCHITECTURE.md | Publica um documento aprovado e grava a versão canônica oficial. |
Sessão e Ciclo de Vida do Agente
| Comando | Descrição |
|---|---|
aops context | Carrega o resumo de continuidade da sessão anterior, tarefas ativas e riscos. (Executado automaticamente pelo agente) |
aops workflow check | Valida tarefas prioritárias e bloqueios antes de iniciar código. (Executado pelo agente) |
aops session begin --agent <nome> | Inicia ou retoma a sessão ativa do agente no projeto. |
aops session heartbeat --status "..." | Registra progresso intermediário durante o raciocínio ou execução do agente. |
aops session complete --status completed | Encerra a sessão local ativa. |
aops session list | Lista as sessões remotas do projeto. |
aops session close-stale --timeout 60m --write | Encerra sessões inativas ou órfãs. |
aops handoff --summary "..." | Registra um repasse de contexto estruturado para o próximo agente/desenvolvedor. |
aops agent complete --summary "..." --files "a.ts,b.ts" --tests "..." --risks "..." [--sync] | Conclui formalmente a tarefa e registra as evidências de código e testes. |
Validações e Harness de Qualidade
| Comando | Descrição |
|---|---|
aops validation add --command "..." --status passed|failed|skipped | Registra o resultado de uma validação declarada. |
aops validation add --command "..." --execute [--timeout <ms>] | Harness Real: executa o comando real no sistema operacional e captura o exit code verdadeiro. |
aops loop check | Executa sequencialmente todos os comandos de requiredValidations da policy do projeto como critério de parada. |
aops harness analyze | Analisa a maturidade do harness com base em metadados sanitizados. |
aops harness plan --dry-run | Apresenta a prévia de melhorias de harness propostas. |
aops harness apply --plan-id <id> --plan-file <path> | Aplica um plano de harness aprovado pela liderança técnica. |
Sincronização Remota
| Comando | Descrição |
|---|---|
aops sync --dry-run | Exibe o que seria sincronizado com o servidor sem enviar dados. |
aops sync --write | Envia todos os eventos locais pendentes para a nuvem. (Executado pelo agente ao concluir) |
aops sync inspect | Inspeciona eventos pendentes, rejeitados e diagnósticos de conectividade. |
aops sync retry --write | Repete o envio de eventos pendentes em caso de falha transitória de rede. |
Tarefas e Spec-Driven Development (TLC)
| Comando | Descrição |
|---|---|
aops task next / aops task list --mine | Lista tarefas atribuídas ao desenvolvedor logado. |
aops task show --task-id <id> | Exibe os requisitos detalhados de uma tarefa específica. |
aops task start --task-id <id> | Reivindica e vincula a tarefa à sessão ativa. |
aops task create --title "..." --description "..." --priority <p> | Cria uma nova tarefa operacional diretamente no projeto. |
aops task download-attachment --task-id <id> --key <key> | Baixa anexos de especificação vinculados à tarefa para .aops/attachments/. |
aops task done --task-id <id> --reason "..." | Marca a tarefa como concluída no backend. |
aops tasks import --from .specs/features/<feature>/tasks.md --write | Importa tarefas atômicas geradas pelo skill TLC. |
aops spec sync [--write] | Sincroniza artefatos de especificação e reconcilia evidências de validação. |
Cache de Contexto
| Comando | Descrição |
|---|---|
aops cache build --write | Constrói o cache local indexado da base de código em .aops/context-cache.db. |
aops cache brief --query "..." | Gera um resumo conciso direcionado para o objetivo ou tarefa da sessão. |
aops cache search --query "..." [--include-content] | Realiza busca semântica no cache de contexto. |
aops cache list --scope <área> | Lista os arquivos e módulos mapeados por escopo no cache. |
aops cache check / aops cache status | Inspeciona integridade, cobertura e frescor do cache local. |
Hooks de Segurança (aops-guards)
O CodeOps AI inclui guardas automáticas de segurança instaladas no ambiente dos agentes (.agents/hooks/ e .agents/hooks.json):
- PreToolUse: Bloqueia comandos destrutivos (
rm -rf /, formatações), impede chaining perigoso de shell (&&,|,;), protege arquivos de credenciais e exige confirmação para deploys. - SessionStart: Garante a injeção da tarefa ativa do usuário no contexto do agente.
- Stop: Impede o agente de encerrar sem sincronizar os eventos pendentes (
pendingEvents > 0).
Arquivos de Governança
| Arquivo | Versionado? | Finalidade |
|---|---|---|
.aops/config.json | Não (.gitignore) | Identificadores de projeto, organização e credencial local. |
.aops/agentops.db | Não (.gitignore) | Banco SQLite local para outbox e sessões offline. |
.aops/policy.json | Sim | Comandos de teste/build obrigatórios compartilhados pelo time. |
ARCHITECTURE.md | Conforme o time | Espelho local da arquitetura canônica do projeto. |
GEMINI.md / AGENTS.md / CLAUDE.md | Sim | Regras de governança que ensinam o agente a usar a CLI e seguir os padrões do repositório. |
.agents/skills/ | Sim | Habilidades especializadas que os agentes executam sob demanda. |
Variáveis de Ambiente
As seguintes variáveis sobrescrevem a configuração local em ambientes de CI ou contêineres:
AOPS_API_URL: URL base da API do CodeOps AI.AOPS_ACCESS_TOKEN: Token de autenticação (mantenha em secrets seguros).AOPS_ORGANIZATION_ID: ID da organização.AOPS_PROJECT_ID: ID do projeto remoto.
Licença
MIT