Codex CLI como Subagente

Quando Usar

• Use quando uma tarefa de codificação, revisão ou verificação com limites bem definidos puder ser executada em uma sessão separada do Codex CLI.
• Use quando o trabalho paralelo precisar de propriedade explícita de arquivos e uma definição clara de "concluído".

O Codex CLI é o agente de codificação de terminal da OpenAI. codex exec o executa de forma não interativa: ele funciona autonomamente em um sandbox, transmite o progresso para stderr e imprime apenas a mensagem final para stdout. A autenticação reutiliza a assinatura do ChatGPT do usuário — nunca uma chave de API.

Quando Delegar

• Tarefa de codificação autônoma com critérios claros de sucesso (correção, recurso, refatoração, revisão).
• Trabalho paralelo: várias tarefas independentes ao mesmo tempo (veja Execuções Paralelas).
• Segunda opinião / verificação independente de suas próprias alterações.

NÃO delegue tarefas que necessitem de contexto de conversa que você não consiga escrever completamente no prompt.

Pré-voo

codex --version       # missing? npm i -g @openai/codex  (or: brew install --cask codex)
codex login status    # exit 0 + "Logged in using ChatGPT" = ready

Não logado → pare e diga ao usuário para executar codex login (OAuth no navegador, uma vez). Nunca leia, imprima ou copie credenciais (~/.codex/auth.json).

Lançamento

OUT=$(mktemp /tmp/codex-out.XXXXXX)
codex exec \
  --cd /path/to/repo \
  --sandbox workspace-write \
  --output-last-message "$OUT" \
  "Full task prompt: goal, constraints, files to touch, definition of done." \
  </dev/null

• </dev/null é OBRIGATÓRIO quando stdin não é um terminal real (shells em segundo plano, scripts): o codex trata stdin aberto como contexto adicional e espera indefinidamente por EOF.
• O Codex não vê NADA da sua conversa. Coloque todo o contexto no prompt: objetivo, caminhos relevantes, restrições e como verificar se está concluído.
• Prompt longo? Envie-o via stdin em vez disso: codex exec [flags] - < /tmp/task.md.
• Envolva o comando em um subagente Bash/em segundo plano se o seu agente host tiver um (Cursor: Ferramenta de Tarefa com um subagente de shell) para que o fluxo detalhado do Codex fique fora do contexto pai. Alternativa: um terminal simples em segundo plano.
• As execuções levam minutos e não têm tempo limite embutido — execute em segundo plano e monitore.
• Opcional: -m <model> para substituir o modelo, --json para o fluxo de eventos JSONL.

Coletar Resultados

cat "$OUT"                            # final message = the deliverable
git -C /path/to/repo status --short   # see what Codex actually changed

Acompanhamento na mesma sessão (execute a partir do mesmo cwd — retoma filtros por cwd):

codex exec resume --last "follow-up instruction" </dev/null

Execuções Paralelas

Paralelize apenas tarefas genuinamente independentes e atribua a propriedade dos arquivos antecipadamente para que os resultados se mesclem de forma limpa. Um worktree git por execução do Codex — nunca dois na mesma árvore:

git worktree add /tmp/wt-taskA -b codex/task-a
codex exec --cd /tmp/wt-taskA --sandbox workspace-write -o /tmp/outA.md "task A" </dev/null

Modos de Falha

• Trava indefinidamente sem saída → stdin foi deixado aberto. Mate-o, reinicie com </dev/null.
• codex login status com código diferente de zero → o usuário deve executar codex login. Não contorne isso.
• Limite de taxa do plano ChatGPT atingido → informe ao usuário; nunca tente novamente em loop.
• Erro "Não é um repositório git" → adicione --skip-git-repo-check ou inicialize um repositório primeiro.
• A rede é bloqueada dentro do sandbox de gravação do workspace por padrão. Se a tarefa precisar disso (instalações, chamadas de API): -c sandbox_workspace_write.network_access=true.
• NUNCA use --dangerously-bypass-approvals-and-sandbox.

Regras

• Uma tarefa por lançamento. Divida trabalhos grandes em vários lançamentos.
• Revise o diff do Codex você mesmo antes de declarar a tarefa como concluída.

Wrapper nativo do Cursor (opcional)

Para roteamento automático e invocação de /codex dentro do Cursor, adicione ~/.cursor/agents/codex.md — um subagente personalizado cuja descrição é "delegação de tarefas de codificação para Codex CLI" e cujo corpo aponta para esta habilidade.

Limitações

• Adaptado de davidondrej/skills; verifique caminhos locais, ferramentas, credenciais e recursos do agente antes de agir.
• Para comandos, acesso remoto, agendamento, automação de navegador ou fluxos de trabalho de alteração de arquivos, obtenha aprovação explícita do usuário e confirme o ambiente de destino primeiro.