Agentes paralelos do Codex: como executar várias tarefas do Codex ao mesmo tempo

Você tem uma tarefa do Codex em execução, uma correção de bug que quer repassar para outra pessoa, uma suíte de testes que precisa de cobertura e uma refatoração que você vive adiando. As quatro são independentes. Não há motivo para que não rodem ao mesmo tempo — exceto o motivo prático: aponte duas sessões do Codex para o mesmo checkout e elas começam a sobrescrever as edições uma da outra. O paralelismo que você queria vira um merge que você não pediu.

Rodar várias tarefas do Codex ao mesmo tempo é menos um recurso que você ativa e mais uma configuração que você monta. Existem três caminhos: as tarefas em nuvem do Codex, várias sessões locais da CLI e subagentes dentro de uma única sessão. Cada um entrega concorrência de verdade, e cada um tem um modo de falha que aparece no instante em que as escritas se sobrepõem. Este guia percorre os três, com os comandos e a falha nomeada a cada passo, e depois mostra onde um quadro de tarefas assume o controle.

Esse quadro de tarefas é o Sharkly. Você já tem o Codex. O Sharkly fica acima dele: executa o Codex como um Runtime e transforma cada execução paralela em uma Task com seu próprio checkout isolado, seu próprio log e seu próprio revisor. O artigo começa pela configuração manual, porque você precisa entender o que está automatizando antes de automatizar.

TL;DR

Agentes paralelos do Codex significa rodar várias tarefas do Codex ao mesmo tempo, em vez de uma por vez. Há três formas de fazer isso: tarefas em nuvem do Codex (cada uma em um ambiente isolado, segundo a documentação da OpenAI), várias sessões locais da CLI codex ou subagentes dentro de uma única sessão. A regra que rege todas elas é uma cópia de trabalho por unidade de trabalho: dê a cada tarefa seu próprio git worktree, para que edições simultâneas nunca toquem os mesmos arquivos. Isso escala bem até um punhado de tarefas. A partir daí, acompanhar qual agente fez o quê e revisar cada resultado separadamente vira o gargalo — e é aí que entra a camada que o Sharkly adiciona.

As três formas de rodar o Codex em paralelo

Escolha o caminho pelo lugar onde o trabalho roda e por quanto você precisa enxergar, não pelo que soa mais poderoso.

Use as tarefas em nuvem do Codex quando o trabalho estiver bem delimitado e você não se importar em verificar depois. Use sessões locais da CLI quando quiser conduzir cada execução enquanto ela acontece. Use subagentes quando o trabalho for basicamente leitura, já que os agentes gerados compartilham um único diretório de trabalho e, conforme o comportamento dos subagentes do Codex, a sessão espera todos eles e retorna uma única resposta consolidada. Esse último formato não serve para escrita em paralelo: agentes editando código ao mesmo tempo criam conflitos, e um resumo único não pode ser revisado peça por peça.

Passo a passo: rode várias tarefas do Codex localmente sem colisões

O caminho local é o que a maioria das pessoas busca primeiro — e o que quebra primeiro. Aqui está a configuração que sobrevive.

Passo 1. Dê a cada tarefa seu próprio checkout. Um git worktree é um segundo diretório de trabalho apoiado no mesmo repositório, em seu próprio branch. Crie um por tarefa:

git worktree add ../app-authfix -b fix/token-refresh
git worktree add ../app-tests   -b test/checkout-coverage
git worktree add ../app-refactor -b refactor/api-client

Falha se você pular esta etapa: duas sessões do codex na mesma pasta editam os mesmos arquivos, a escrita mais recente vence em silêncio e as duas relatam sucesso. Você descobre a perda na revisão — ou em produção.

Passo 2. Inicie uma sessão do Codex por worktree. Abra um terminal em cada diretório e execute o Codex ali:

cd ../app-authfix && codex

Falha se você pular esta etapa: uma sessão com quatro objetivos no contexto fica vagando entre eles e perde o rastro de qual mudança pertence a qual tarefa.

Passo 3. Scripte as tarefas que não precisam de uma pessoa no teclado. Para uma tarefa autocontida, o modo não interativo roda até o fim sem pedir confirmação:

cd ../app-tests && codex exec "add tests for the checkout flow until coverage passes"

Falha se você pular esta etapa: você fica tomando conta de sessões que nunca precisaram de você, o que anula a razão de rodá-las em paralelo.

Passo 4. Faça o merge com cuidado, um branch por vez. Cada worktree é um branch, então revise e faça o merge deles separadamente. Nunca deixe os agentes fazerem o merge do trabalho uns dos outros. Falha se você pular esta etapa: três branches chegam de uma vez, um conflito aparece no commit de merge e você não consegue mais dizer qual mudança de qual agente causou isso.

Para entender a mecânica de limpar worktrees corretamente depois, veja gerenciar worktrees para agentes de código sem a dor da limpeza. O mesmo padrão de worktree também viabiliza rodar vários agentes do Claude Code; ele é neutro em relação ao runtime por design.

Onde a configuração faça-você-mesmo para de escalar

Os worktrees resolvem as colisões. Não resolvem tudo, e o limite está mais perto do que parece.

Com três ou quatro tarefas, a configuração se mantém. Com oito, a grade de terminais deixa de ser um espaço de trabalho e vira um teste de memória. As falhas não são dramáticas; elas se acumulam:

• Você perde o mapa. Qual janela é a correção de autenticação? Qual terminou? Qual falhou vinte minutos atrás e está parada desde então? O estado existe só na sua cabeça e some da tela conforme você rola.
• A revisão não tem costuras. A saída de cada sessão é uma parede de histórico de rolagem. Não há um registro por tarefa do que ela tocou, do que executou e de onde parou, então você não consegue aceitar um resultado e rejeitar outro de forma limpa.
• Nada é compartilhado. No momento em que alguém do time precisa ver o progresso, você está copiando diffs para uma thread no Slack. O trabalho é real, mas invisível.

Esses são os mesmos três problemas com que todo fluxo de trabalho com agentes paralelos acaba esbarrando, e são o motivo pelo qual as equipes recorrem a ferramentas dedicadas para gerenciar agentes de código paralelos quando a quantidade aumenta. O isolamento é um problema resolvido. Visibilidade e revisão não são — pelo menos não com uma grade de terminais.

O que um quadro de tarefas acrescenta

É aqui que a camada acima do agente justifica seu lugar. Uma Task é o registro compartilhado de uma unidade de trabalho no Sharkly, e rodar tarefas do Codex em paralelo passa a ser rodar Tasks em paralelo.

Cada Task reserva automaticamente um git worktree isolado, então agentes paralelos em worktrees isolados deixam de ser algo que você scripta e passam a ser o padrão. Dez Tasks contra um único repositório, zero estado compartilhado, nenhum git worktree add digitado à mão. O Runtime que faz as edições continua sendo o Codex; o isolamento é oferecido ao redor dele.

A divisão do trabalho é o ponto central. Agentes pesquisam, executam, testam e relatam. Pessoas definem a direção, concedem autoridade e aceitam o resultado. A automação para onde o julgamento da equipe é necessário. Assim, cada execução mantém seu próprio log de execução com o gatilho, as chamadas de ferramentas e onde parou, e seu resultado final volta para a Task em vez de passar rolando por um terminal. Contexto, progresso, bloqueios, resultados e revisão humana permanecem visíveis da solicitação até a entrega, e você revisa cada um individualmente em vez de ler um resumo de resumos. Para o lado de relatórios disso, veja como acompanhar o trabalho concluído por agentes de código com IA.

O Sharkly não substitui o Codex. Ele adiciona a camada compartilhada de tarefas, checkout, contexto e revisão em volta do agente que você já executa. Se você só roda uma sessão do Codex por vez, não precisa dele. Se você roda várias contra uma mesma base de código e está perdendo o fio da meada, é para esse problema que ele foi feito. Você pode montar a configuração de worktrees acima à mão, ou rodar suas tarefas atuais do Codex pelo Sharkly e deixar que o fluxo de trabalho guarde o estado para você.

Uma lista de verificação para usar hoje mesmo

• Um git worktree por tarefa, cada um em seu próprio branch. Nenhuma dupla de tarefas compartilha um checkout.
• Uma sessão do Codex por worktree, ou codex exec para tarefas que não precisam de você.
• Use subagentes apenas para trabalho com muita leitura; mantenha as escritas simultâneas em checkouts separados.
• Faça o merge de um branch por vez e revise cada um antes de integrá-lo.
• Mantenha um registro de qual tarefa é qual, o que cada uma tocou e seu resultado, em algum lugar que alguém do time possa ver.
• Quando a grade de terminais deixar de caber na sua cabeça, leve o acompanhamento e a revisão para um quadro de Tasks, para que cada execução devolva seu resultado a um único lugar compartilhado.

FAQ

O Codex consegue rodar várias tarefas ao mesmo tempo? Sim. O Codex em nuvem roda tarefas em ambientes isolados, conforme a documentação da OpenAI, e localmente você pode rodar várias sessões do codex ao mesmo tempo. A restrição é o checkout, não o Codex: dê a cada tarefa local seu próprio git worktree para que as edições não colidam.

Quantos agentes do Codex em paralelo eu consigo rodar? Quantos sua máquina e sua cota de modelo permitirem. O teto prático é mais baixo: é o número de resultados simultâneos que uma pessoa consegue realmente revisar. Além de um punhado, o limite passa a ser o acompanhamento e a revisão, não o poder de processamento.

Preciso de worktrees, ou posso simplesmente abrir mais terminais? Mais terminais no mesmo diretório significam escritas simultâneas nos mesmos arquivos e sobrescritas silenciosas. Os worktrees dão a cada sessão seu próprio diretório e branch, e é isso que torna o paralelismo local seguro. Veja git worktrees para agentes de código com IA.

Qual é a diferença entre subagentes do Codex e tarefas paralelas? Os subagentes rodam dentro de uma sessão, compartilham seu diretório de trabalho e retornam uma única resposta consolidada, o que serve para leitura e triagem. As tarefas paralelas são execuções separadas, com checkouts separados, que é o que você quer para escrita simultânea e revisão independente.