Pi Coding Agent

O bloco Pi Coding Agent roda o harness de coding Pi contra um repositório real. Você dá uma tarefa e um modelo; ele abre um pull request, posta uma review de PR ou altera seus arquivos no lugar. Create PR e Local Dev podem reutilizar suas skills e memória multi-turn. Review Code deliberadamente não carrega nenhuma das duas porque o conteúdo de pull requests não é confiável.

Tem três modos que decidem onde roda e como o trabalho aterrissa:

• Create PR — sobe um sandbox isolado, clona um repo GitHub conectado, edita e testa com shell + git nativos e abre um pull request.
• Review Code — faz checkout de um PR existente num sandbox, analisa com acesso read-only limitado pelo repositório e posta uma GitHub review (resumo + comentários inline opcionais).
• Local Dev — conecta à sua máquina via SSH e edita arquivos lá diretamente.

Modos

Escolha o modo no dropdown Mode. Os campos abaixo mudam para combinar.

Create PR

Create PR roda inteiramente dentro de um sandbox descartável, então nunca toca na sua máquina. Clona o repo, deixa o agente trabalhar com read/shell/edit/git completos, faz push de um branch e abre um PR que você revisa e faz merge.

• Exige que a execução em sandbox esteja habilitada (Create PR e Review Code só aparecem quando estiver).
• Exige sua própria API key de provedor (BYOK) — a chave do modelo é entregue ao sandbox.
• Precisa de um GitHub token com permissão para clonar, fazer push e abrir um PR (veja Setup).
• O entregável é um pull request — nada é commitado diretamente no seu branch padrão.

Review Code

Review Code usa um sandbox descartável para o repositório, mas o harness Pi e a credencial do modelo ficam no Zoen. Ele fixa os commits base e head do PR, dá ao agente só tools limitadas de read/search e valida coordenadas inline contra aquele diff local exato. O Zoen então submete uma GitHub review com um body de resumo e comentários inline opcionais.

• Exige execução em sandbox. A chave do provedor fica no Zoen, então hosted keys e BYOK são ambos suportados.
• Precisa de um GitHub token que possa clonar o repo e submeter reviews (veja Setup).
• Precisa do Pull Request Number a revisar.
• Não carrega skills nem memória, e nunca expõe shell, write, edit ou tools de rede arbitrárias ao reviewer.
• Recheca o PR imediatamente antes da submissão e fixa a review no commit head exato do checkout.
• O entregável é uma review submetida — leia reviewUrl e commentsPosted.

Local Dev

Local Dev roda o agente contra um repositório numa máquina que você controla, alcançada via SSH. Mudanças são escritas no lugar — não há PR; você as revisa como mudanças git normais naquela máquina.

• A máquina precisa ser alcançável num hostname público — localhost e endereços LAN/privados são bloqueados. Exponha com um tunnel (veja Setup).
• As tools de arquivo e shell do agente ficam confinadas ao Repository Path que você configurar.
• Você também pode expor tools do Zoen (Gmail, Slack, Exa, …) ao agente para que ele aja além do repo enquanto trabalha.

Configuração

Task

O que o agente deve fazer, em linguagem natural — por exemplo "Add input validation to the signup form and a test for it." ou "Review this PR for security and correctness issues." Insira uma connection tag para passar uma saída anterior, como <start.input>.

Model

O modelo que dirige o agente. O padrão é claude-sonnet-4-6. O dropdown contém a interseção dos modelos disponíveis no Zoen e das entradas exatas relativas ao provedor no catálogo Pi instalado. O Zoen nunca fabrica metadados de modelo de fallback.

API Key

Sua chave para o provedor escolhido. No Zoen hospedado é opcional para execuções Local Dev e Review Code (uma hosted key é usada e medida no seu workspace). Create PR exige sua própria chave porque o client do modelo roda no sandbox. Quando o provedor suporta BYOK de workspace, você pode guardar a chave em Settings → BYOK em vez de informá-la no bloco.

Repository (Create PR / Review Code)

• Repository Owner / Repository Name — o repo GitHub (por exemplo your-org / your-repo).
• GitHub Token — um personal access token usado para acesso ao GitHub. As permissões diferem por modo; veja setup Create PR ou setup Review Code.

Campos Create PR

• Base Branch — o branch contra o qual o PR é aberto e a partir do qual o clone é feito. O padrão é o branch padrão do repositório.
• Branch Name (advanced) — o branch para push. Gerado automaticamente quando em branco.
• Open as Draft PR (advanced) — abre o PR como draft. Ligado por padrão.
• PR Title / PR Body (advanced) — gerados a partir da execução quando em branco.

Campos Review Code

• Pull Request Number — o PR a revisar (por exemplo 42).
• Review Outcome — a ação de review do GitHub a submeter: Comment (padrão) ou Request changes. Review Code intencionalmente não submete approvals.

Connection (Local Dev)

• Host — o hostname público ou tunnel da máquina alvo (por exemplo 2.tcp.ngrok.io). Não localhost nem endereço LAN.
• Username — o usuário SSH (por exemplo ubuntu, root ou sua conta macOS).
• Authentication Method — Password ou Private Key.
• Password / Private Key — a credencial para aquele método. Prefira uma key quando puder.
• Repository Path — o caminho absoluto do repo na máquina alvo (por exemplo /home/user/my-repo). As tools do agente ficam confinadas a este diretório.
• Port (advanced) — a porta SSH. O padrão é 22; defina a porta do seu tunnel se for diferente.
• Passphrase (advanced) — para uma private key criptografada.

Tools (Local Dev)

Tools do Zoen que o agente pode chamar enquanto trabalha — buscar numa base de conhecimento, enviar uma mensagem no Slack, chamar qualquer uma das integrações. Rodam pelo Zoen com suas credenciais conectadas, exatamente como o bloco Agent. MCP e custom tools ainda não são suportados aqui (aparecem acinzentados).

Skills (Create PR / Local Dev)

Skills de agentes que o agente pode usar — pacotes reutilizáveis de instruções como um padrão de código ou um playbook de review. São compartilhadas com o bloco Agent, então uma skill que você cria uma vez funciona nos dois.

Thinking Level

Para modelos com raciocínio estendido, quanto o modelo pensa antes de agir. Mais alto é mais completo, mas mais lento e custa mais tokens. O padrão é medium.

Memória (Create PR / Local Dev)

Memória multi-turn indexada por um conversation ID, compartilhada com o bloco Agent:

• None. Cada execução é independente.
• Conversation. O histórico completo daquele conversation ID.
• Sliding window (messages). As N mensagens mais recentes.
• Sliding window (tokens). Mensagens recentes até um orçamento de tokens.

Reutilize o mesmo Conversation ID entre execuções para continuar um thread. Cada turno armazena sua tarefa e o resumo final do agente, que são dobrados no prompt da próxima execução. Review Code nunca carrega nem salva memória.

Limites de contexto

Para Create PR e Local Dev, a memória é dobrada no primeiro prompt do agente, e duas camadas a mantêm dentro da janela de contexto do modelo:

• O Zoen trim antes da execução. O tipo de memória selecionado limita o que é injetado: Conversation é automaticamente limitado a uma fração da janela de contexto do modelo (para modelos no catálogo do Zoen), Sliding window (messages) mantém as últimas N mensagens, e Sliding window (tokens) mantém histórico até um orçamento explícito de tokens.
• O Pi compacta durante a execução. Conforme o agente trabalha (lendo arquivos, rodando comandos), o Pi resume automaticamente turnos mais antigos para ficar sob a janela — em todos os modos, ligado por padrão. Você não precisa configurar nada para crescimento de contexto no meio da execução.

O único caso que nenhuma camada consegue salvar é um primeiro prompt que já excede a janela — o Pi só pode compactar quando há turnos mais antigos para resumir. Isso só é alcançável com memória Conversation mais um modelo digitado manualmente (não no catálogo do Zoen), onde o teto automático não consegue buscar uma janela de contexto. Para históricos longos — e sempre que usar um modelo digitado manualmente — escolha Sliding window (tokens): o orçamento se aplica independentemente do modelo, então o primeiro prompt sempre cabe.

Saídas

Setup

Create PR

Create PR roda numa imagem de sandbox com o CLI Pi e git embutidos.

1. Habilite a execução em sandbox. No Zoen self-hosted, defina E2B_ENABLED=true, E2B_API_KEY, E2B_PI_TEMPLATE_ID (o id do template Pi) e NEXT_PUBLIC_E2B_ENABLED=true (isso revela Create PR e Review Code na UI). Construa o template com bun run apps/sim/scripts/build-pi-e2b-template.ts. Ambos os modos ficam ocultos até NEXT_PUBLIC_E2B_ENABLED estar definido.
2. Traga sua própria chave de modelo. Defina a API key do provedor no campo API Key do bloco, ou guarde em Settings → BYOK quando o provedor suportar BYOK de workspace.
3. Crie um GitHub token com permissão para clonar, fazer push e abrir um PR:
   • Fine-grained: selecione o repo e depois Contents: Read and write + Pull requests: Read and write.
   • Classic: o escopo repo. Para repos de org, autorize o token para SSO.

Review Code

Habilite a execução em sandbox como no Create PR. BYOK é opcional porque a credencial do modelo permanece no Zoen. O GitHub token precisa de acesso suficiente para clonar o repo e submeter uma review — permissão de push não é necessária:

• Fine-grained: selecione o repo e depois Contents: Read + Pull requests: Read and write.
• Classic: o escopo repo (ou um token mais estreito que possa ler contents e escrever reviews de pull request). Para repos de org, autorize o token para SSO.

Local Dev

1. Habilite SSH na máquina alvo (no macOS: System Settings → General → Sharing → Remote Login).
2. Exponha num host público. O Zoen bloqueia localhost/LAN, então use um tunnel TCP — por exemplo ngrok tcp 22, que dá um host:port para colocar em Host e Port.
3. Use um modelo que seu provedor suporte (por exemplo um modelo Claude com uma chave Anthropic). Defina o método de credencial e o Repository Path, e rode.

Boas práticas

• Escopo a tarefa. Uma instrução específica ("fix the failing auth test and add a regression case") produz resultados bem melhores que uma vaga.
• Combine o modo com o entregável. Create PR para mudanças desacompanhadas, Review Code para feedback num PR existente, Local Dev para iterar num repo que você já tem em checkout.
• Prefira auth por key e derrube tunnels. Um tunnel SSH público é superfície de ataque real — use uma private key e pare o tunnel quando terminar.
• Reutilize um Conversation ID para follow-ups de Create PR ou Local Dev. Ele carrega a tarefa e o resultado anteriores para a próxima execução, para o agente construir sobre o próprio trabalho.