Coding Agent

Ações da Tool Process (para sessões background)

Quick Start: Tarefas One-Shot

Para prompts/chats rápidos, crie um repo git temporário e execute:

# Chat rápido (Codex precisa de um repo git!)
SCRATCH=$(mktemp -d) && cd $SCRATCH && git init && codex exec "Seu prompt aqui"

# Ou em um projeto real - com PTY!
bash pty:true workdir:~/Projects/meuproj command:"codex exec 'Adicionar tratamento de erros nas chamadas de API'"

Por que git init? Codex se recusa a rodar fora de um diretório git confiável. Criar um repo temporário resolve isso para trabalhos rápidos.

O Padrão: workdir + background + pty

Para tarefas mais longas, use modo background com PTY:

# Iniciar agente no diretório alvo (com PTY!)
bash pty:true workdir:~/project background:true command:"codex exec --full-auto 'Construir um jogo snake'"
# Retorna sessionId para rastreamento

# Monitorar progresso
process action:log sessionId:XXX

# Verificar se terminou
process action:poll sessionId:XXX

# Enviar input (se agente fizer pergunta)
process action:write sessionId:XXX data:"y"

# Submeter com Enter
process action:submit sessionId:XXX data:"yes"

# Matar se necessário
process action:kill sessionId:XXX

Por que workdir importa: Agente acorda em um diretório focado, não fica vagando lendo arquivos não relacionados.

Codex CLI

Modelo: gpt-5.2-codex é o padrão (configurado em ~/.codex/config.toml)

Flags

Build/Criação

# One-shot rápido (auto-aprova) - lembre do PTY!
bash pty:true workdir:~/project command:"codex exec --full-auto 'Criar toggle de dark mode'"

# Background para trabalho longo
bash pty:true workdir:~/project background:true command:"codex --yolo 'Refatorar módulo de auth'"

Claude Code

# Com PTY para output de terminal adequado
bash pty:true workdir:~/project command:"claude 'Sua tarefa'"

# Background
bash pty:true workdir:~/project background:true command:"claude 'Sua tarefa'"

Pi Coding Agent

# Install: npm install -g @mariozechner/pi-coding-agent
bash pty:true workdir:~/project command:"pi 'Sua tarefa'"

# Modo não-interativo (PTY ainda recomendado)
bash pty:true command:"pi -p 'Resumir src/'"

# Provider/modelo diferente
bash pty:true command:"pi --provider openai --model gpt-4o-mini -p 'Sua tarefa'"

⚠️ Regras

1. Sempre use pty:true - agentes de código precisam de terminal!
2. Respeite a escolha de tool - se usuário pedir Codex, use Codex.
3. Seja paciente - não mate sessões porque estão "lentas"
4. Monitore com process:log - verifique progresso sem interferir
5. --full-auto para building - auto-aprova mudanças
6. vanilla para review - sem flags especiais necessárias
7. Paralelo é OK - execute vários processos Codex de uma vez

Atualizações de Progresso (Crítico)

Quando você spawn agentes de código em background, mantenha o usuário informado.

• Envie 1 mensagem curta quando iniciar (o que está rodando + onde).
• Depois só atualize quando algo mudar:
  • um milestone completa (build terminou, testes passaram)
  • o agente faz pergunta / precisa de input
  • você encontrou erro ou precisa de ação do usuário
  • o agente termina (inclua o que mudou + onde)
• Se você matar uma sessão, diga imediatamente que matou e por quê.

Exemplos de Uso no Cleudocode

# Executar Codex one-shot
coding_agent action:exec agent:codex prompt:"Criar função de validação de email"

# Background com monitoramento
coding_agent action:start agent:pi workdir:~/project prompt:"Refatorar API"
# Retorna: sessionId: abc123

coding_agent action:log sessionId:abc123
coding_agent action:poll sessionId:abc123