Codex Delegate

Quando Usar

• Você quer delegar uma tarefa de codificação delimitada para um codex implementador separado (OpenAI Codex) e, em seguida, revisar o diff dele.
• O usuário pediu explicitamente a delegação para este implementador.

Você é o orquestrador. Esta habilidade permite que você entregue uma tarefa de codificação delimitada a um implementador separado — o OpenAI Codex CLI — depois, revise o que ele produziu e finalize você mesmo. Você escreve o resumo e é o responsável pelo julgamento; o Codex faz a digitação em seu próprio sandbox; você verifica e confirma.

Nada aqui é específico para um agente orquestrador. O loop precisa apenas da capacidade de executar um comando de shell e ler um arquivo, então funciona da mesma forma, quer você seja Claude Code, OpenCode com um modelo selecionado ou qualquer agente comparável. (Ele é projetado para e executado no Claude Code; trate outros orquestradores como projetados para, mas ainda não comprovados.)

Quando NÃO Usar Isto

• A tarefa é pequena o suficiente para ser feita inline — a sobrecarga da delegação não vale a pena.
• O CLI codex não está instalado ou não autenticado (execute codex login).
• Você quer escrever o código você mesmo, ou só precisa de uma revisão (use o comando review do próprio Codex).

Pré-requisitos (verificar uma vez)

1. codex --version é bem-sucedido. Se não, instale (npm i -g @openai/codex) e codex login.
2. Confirme qual codex está no PATH. Múltiplas instalações são comuns (por exemplo, uma cópia atual do npm/nvm e uma antiga do Homebrew). command -v codex mostra o ativo e codex --version sua versão — um binário antigo precede flags das quais esta habilidade depende (codex exec --json, -o, exec resume). O relay também registra a versão com a qual ele se deparou em result.json, então um binário desatualizado fica visível após o fato.
3. Você está (ou apontará --cd para) o repositório git de destino.

O Loop

Execute estas cinco etapas por tarefa. As etapas 1, 4 e 5 são seu julgamento; 2 e 3 são mecânicas.

1. Escreva o Resumo

O Codex vê apenas o texto que você envia — sem memória do repositório, sem histórico de chat, sem contexto compartilhado. Tudo o que a tarefa precisa vai no resumo: o objetivo, o estado atual, o que mudar, o que deixar intocado, os comandos de portão reais do projeto (descubra-os em CLAUDE.md/AGENTS.md/Makefile do repositório — não presuma), e um contrato de relatório. Diga ao Codex que ele não fará o commit (você fará). Mantenha uma tarefa por resumo. Orientação completa e um modelo: references/writing-the-brief.md.

2. Despacho

Envie o resumo para o Codex com o helper empacotado. Ele envolve codex exec, captura a execução e escreve um result.json estruturado — então seu único trabalho é "executar um comando, ler um arquivo". (<skill-dir> abaixo é o diretório instalado desta habilidade — a pasta contendo este SKILL.md, ou seja, o diretório de onde você carregou a habilidade. Claude Code o imprime como "Base directory for this skill" quando a habilidade carrega; em outros orquestradores, use o mesmo diretório — se tiver dúvidas de onde ele pousou, execute find ~ -name relay.mjs -path '*codex-delegate*' e substitua o diretório acima dele.)

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
# read-only (review/diagnosis, no edits):   add --read-only
# continue the exact Codex session:         add --session <threadId>  (from result.json; send only the delta brief)
# fallback when no thread id is available:  add --resume-last
# hard time limit (watchdog):               add --timeout 2h  (default: off; implementation runs routinely need 1-2h)
# see all options:                          node .../relay.mjs --help

O helper usa por padrão um sandbox capaz de escrever (workspace-write) e escreve seus artefatos em um diretório temporário, então o repositório em revisão permanece limpo. Ele nunca faz commit — veja a etapa 5. Mecânicas, flags e o formato result.json: references/dispatch-and-poll.md.

3. Aguarde a Conclusão

O helper bloqueia até que o Codex termine, então o apoie com o que quer que seu orquestrador ofereça e retome quando ele retornar:

• Claude Code: execute a chamada Bash com run_in_background: true; você é notificado na conclusão.
• Shell puro / outros agentes: execute-o em primeiro plano para tarefas curtas, ou coloque-o em segundo plano e consulte o arquivo de resultado — … & em bash/zsh (incluindo Git Bash/WSL), ou o equivalente do seu shell (Start-Job em PowerShell, start /b em cmd). A execução é concluída quando result.json existe com um status. (Um erro de uso pré-execução — argumentos ruins ou um resumo vazio — em vez disso, sai com o código 2 e uma mensagem de stderr e

…