OpenCode agents: como rodar vários agentes em paralelo no mesmo projeto?

Fala aí, beleza? A página oficial do OpenCode não vende "assistente de código", ela vende outra coisa: iniciar vários agentes em paralelo no mesmo projeto

É uma promessa gostosa de ouvir e fácil de entender errado

O OpenCode é software livre com licença MIT e sem custo de licença, então a ferramenta em si é de graça: o que pesa no bolso é o consumo de modelo no provedor que você conectar

E aqui vai o aviso que muda o post inteiro: paralelismo de verdade não é só apertar tecla e abrir janela, depende de entender três coisas separadas (agentes primários, subagentes e isolamento do que roda em disco)

Bora destrinchar isso?

Agentes primários e subagentes do OpenCode: qual usar em cada frente

Primeiro a divisão que confunde todo mundo

O OpenCode traz dois agentes primários embutidos, Build e Plan, e três subagentes embutidos, General, Explore e Scout

Agente primário é com quem você conversa na sessão

Subagente é quem o primário chama pra fazer um recorte do trabalho, ou quem você chama na unha com uma menção @nome

Formação Recomendada

Formação Agentes de IA

Domine a criação de Agentes de IA e Venda para Empresas

• 402 aulas
• 32 projetos
• 38h 19min

Conhecer formação

Repara no detalhe que faz diferença: quando o subagente é despachado pela ferramenta task, ele abre uma sessão filha independente, com system prompt e ferramentas dele

Ou seja, o contexto dele não polui o seu

Se você já brincou com subagents no Claude Code, a ideia de aproximação é essa mesma: delegar um pedaço fechado pra um contexto separado, em vez de empilhar tudo numa conversa só

A invocação automática acontece pela descrição do subagente, então o primário decide chamar quando acha que encaixa

E a manual é você escrevendo @nome no meio da mensagem, sem cerimônia =)

O que você precisa antes de abrir a segunda sessão

Nada de PC da Nasa aqui, a lista é curta

• OpenCode instalado: o código vive no repositório da organização Anomaly no GitHub, em github.com/anomalyco/opencode, e a instalação é por script de uma linha
• Um provedor de modelo conectado: a licença é MIT e gratuita, mas o gasto é o uso de API do seu provedor, e ele multiplica por sessão simultânea
• Projeto em Git: sem repositório você não isola frente nenhuma em worktree, e isolamento é o que segura a onda quando dois agentes escrevem
• Saber qual é a tecla líder: no TUI do OpenCode o leader padrão é ctrl+x, com leader_timeout padrão de 2000 milissegundos

A instalação:

curl -fsSL https://opencode.ai/install | bash

Esse negócio do leader vale um parágrafo à parte

"Tecla líder?" É a tecla que você aperta ANTES do atalho, tipo prefixo

Então quando eu escrever ctrl+x depois n, é isso literalmente: aperta o prefixo, solta, aperta a letra

E tem janela de tempo (os 2000 ms padrão), então enrolar demais entre uma tecla e outra faz o atalho simplesmente não acontecer

Como iniciar vários agentes em paralelo no mesmo projeto

Agora o caminho na ordem que faz sentido, do mais leve pro mais isolado

1. Troque de agente primário dentro da sessão com Tab

Tab cicla entre os primary agents (é o keybind switch_agent), então você sai do Build e cai no Plan sem sair de onde está

O erro comum deste passo: achar que Tab abre uma sessão nova

Não abre, ele só troca quem está no volante da MESMA sessão

2. Abra uma sessão nova de verdade e navegue entre elas

No TUI os keybinds padrão são session_new = <leader>n e session_list = <leader>l

Com o leader padrão, fica assim:

ctrl+x  n     # nova sessão
ctrl+x  l     # lista de sessões

O erro comum deste passo: apertar ctrl+x e ficar pensando na vida

Passou do leader_timeout, o combo morre e você acha que o atalho está quebrado

3. Delegue pedaços fechados pros subagentes

Ou você chama na mão com @nome na mensagem, ou deixa o primário despachar sozinho pela ferramenta task

Em qualquer um dos dois, o trabalho vai pra sessão filha com prompt e ferramentas próprias

O erro comum deste passo: tratar subagente como "mais uma janela"

Ele é um recorte com contexto próprio, então mandar tarefa vaga pra lá é desperdício de token puro

4. Rode fora do TUI, em segundo plano, com opencode run

Esse é o pulo do gato pra automação: opencode run executa um prompt em modo NÃO interativo, feito pra script

opencode run --agent plan "levanta as hipóteses do bug do login"
opencode run -m provider/model "gera os testes do módulo de sessão"
opencode run -c "continua de onde parou"
opencode run -s <id-da-sessao> "retoma essa sessão específica"

As flags são –agent pra escolher o agente, -m/–model pro par provider/model, -c/–continue pra última sessão e -s/–session pra um id específico

O erro comum deste passo: disparar vários opencode run no mesmo diretório achando que cada um vive na própria bolha (já já eu mostro por que isso morde)

5. Isole quem ESCREVE código em git worktree

Uma frente de escrita por diretório, cada uma no seu branch

git worktree add ../meuprojeto-refactor -b refatora-auth

Depois é abrir o OpenCode dentro de ../meuprojeto-refactor e tocar a refatoração ali, longe do diretório principal

O erro comum deste passo: tentar deixar o mesmo branch em checkout em dois worktrees

O Git barra na cara dura:

fatal: 'branch-name' is already checked out at '/path/to/other-worktree'

E isso é BOM, viu? É o Git te impedindo de criar uma bagunça que você só ia descobrir três commits depois

Casos de uso reais: refatorar em uma sessão enquanto outra investiga um bug

Paralelismo bonito no papel é fácil, o que vale é o arranjo

Separei quatro cenários que casam com o que a ferramenta realmente oferece

1. Refatorar em worktree isolado enquanto o Plan caça a causa do bug

A frente de escrita fica no Build, dentro do worktree com branch próprio

A investigação fica no Plan, que é primário restrito e analisa sem modificar o código

Por que separar? Permissões diferentes e gravação isolada: a sessão que investiga não tem como "consertar" nada no meio do caminho e atropelar sua refatoração

2. Varredura de código rodando em paralelo à escrita

Enquanto você escreve, manda a varredura pra um subagente (General, Explore ou Scout)

Como ele roda em sessão filha, o resultado volta pra você sem despejar meio repositório no contexto da sessão principal

Contexto limpo é performance e é dinheiro, os dois juntos

3. Tarefas de script e automação sem TUI

Aqui entra o opencode run –agent <nome> "prompt"

É o caminho de execução não interativa, então serve pra pendurar em script, em hook, no que você quiser

Esse arranjo é o mais próximo de "agente trabalhando enquanto eu faço outra coisa"

4. Revisão numa sessão separada

Revisar dentro da mesma sessão que escreveu é pedir pro modelo concordar consigo mesmo

Abre ctrl+x depois n, joga a revisão lá com o Plan e pronto: contexto limpo, sem o histórico inteiro de decisões enviesando a leitura

Se você quer comparar como outras ferramentas resolvem isso, dá uma olhada em como funciona gerenciar agentes paralelos no Antigravity, o painel de lá ataca o mesmo problema por outro ângulo

Quando o paralelismo atrapalha em vez de ajudar no OpenCode

Agora a parte que ninguém coloca no thread de hype

Sintoma: sessões de instâncias simultâneas se misturando

Causa provável: existe relato público (issue #31307, aberta em 08/06/2026) de que instâncias simultâneas no MESMO projeto compartilham estado, porque usam o mesmo banco SQLite em ~/.local/share/opencode/opencode.db, em modo WAL, e um project_id derivado do diretório de trabalho

Ou seja: mesmo diretório, mesmo project_id, leitura e escrita concorrente das mesmas sessões

Solução: separar o DIRETÓRIO de trabalho, e não só a janela

É exatamente pra isso que o worktree serve aqui: dois caminhos diferentes em disco, duas frentes que não se cruzam

O relato está no repositório do OpenCode no GitHub, aquele mesmo da organização Anomaly, e vale ler antes de montar sua rotina em cima disso

Sintoma: você despacha vários task de uma vez e nada acontece ao mesmo tempo

Causa provável: há relatos públicos (issues #14195 e #29638) de que várias chamadas da ferramenta task numa mesma resposta do modelo são executadas em SEQUÊNCIA, não simultaneamente

Então aquele "despacha um monte de subagente de uma vez" pode virar uma fila educada, um depois do outro

Solução: despachar em turnos, ou levar as frentes pra processos separados com opencode run

Processo separado é paralelismo do sistema operacional, esse ninguém enfileira por você

Sintoma: dois agentes escrevendo nos mesmos arquivos

Causa provável: clássico, duas sessões de escrita apontando pro mesmo diretório

Um salva por cima do outro e você só descobre no git diff, quando já perdeu trabalho

Solução: um branch por worktree, sempre

O próprio Git te protege barrando o checkout duplicado, então use isso a seu favor em vez de contornar

Como prevenir, resumindo

• Uma frente de escrita por worktree: se duas coisas gravam, elas moram em diretórios diferentes
• Leitura e análise no Plan ou nos subagentes: quem só lê não precisa de isolamento pesado
• Conta o custo: sessão simultânea multiplica consumo de modelo no provedor, a licença é MIT mas a API não é de graça

Vale rodar agentes em paralelo no seu projeto?

Veredito honesto: vale quando as frentes são INDEPENDENTES e isoladas em worktree

Refatorar num branch enquanto outra sessão só analisa é ganho real, porque as duas nunca disputam o mesmo arquivo

Agora, duas sessões mexendo no mesmo diretório e no mesmo estado é retrabalho disfarçado de produtividade

Você paga dobrado em token e ainda gasta tempo desfazendo conflito, não compensa

Meu próximo passo sugerido pra quem tá começando: instala, abre uma segunda sessão com ctrl+x depois n e usa ela SÓ pra leitura com o Plan

Sentiu o fluxo? Aí sim você isola uma frente de escrita num worktree e sobe o nível

Conclusão

Recapitulando o que dá pra montar hoje, sem inventar moda:

• Tab troca o agente primário dentro da MESMA sessão (Build escreve com acesso completo, Plan só analisa e propõe)
• ctrl+x depois n abre sessão nova de verdade, e ctrl+x depois l lista o que já existe
• subagente (General, Explore ou Scout) roda em sessão filha, chamado pelo primário via task ou na mão com @nome
• opencode run tira o trabalho do TUI em modo não interativo, e é aí que mora o paralelismo de processo
• git worktree é o que impede duas frentes de escrita de se atropelarem, o próprio Git barra o mesmo branch em dois lugares

Vale a pena quando as frentes são independentes e cada uma que ESCREVE tem seu próprio diretório

Vira bagunça quando você só multiplica janela na mesma pasta: tem relato público de estado compartilhado pelo mesmo banco SQLite e pelo mesmo project_id (issue #31307), e ainda os relatos de task despachado em sequência (issues #14195 e #29638)

Ou seja: janela a mais não é agente a mais, isolamento é que é 🙂

Código e issues ficam no repositório da organização Anomaly no GitHub, em github.com/anomalyco/opencode, e ler as issues antes de montar rotina em cima disso te poupa dor de cabeça…

Até o próximo post!