Pi Coding Agent

The Pi Coding Agent block runs the Pi coding harness against a real repository. You give it a task and a model; it either opens a pull request, posts a PR review, or changes your files in place. Create PR and Local Dev can reuse your skills and multi-turn memory. Review Code deliberately does not load either because pull request contents are untrusted.

It has three modes that decide where it runs and how its work lands:

• Create PR — spins up an isolated sandbox, clones a connected GitHub repo, edits and tests with native shell + git, and opens a pull request.
• Review Code — checks out an existing PR in a sandbox, analyzes it with bounded read-only access across the repository, and posts a GitHub review (summary + optional inline comments).
• Local Dev — connects to your own machine over SSH and edits files there directly.

Modes

Pick the mode with the Mode dropdown. The fields below it change to match.

Create PR

Create PR runs entirely inside a disposable sandbox, so it never touches your machine. It clones the repo, lets the agent work with full read/shell/edit/git, pushes a branch, and opens a PR you review and merge.

• Requires sandbox execution to be enabled (Create PR and Review Code only appear when it is).
• Requires your own provider API key (BYOK) — the model key is handed to the sandbox.
• Needs a GitHub token with permission to clone, push, and open a PR (see Setup).
• The deliverable is a pull request — nothing is committed to your default branch directly.

Review Code

Review Code uses a disposable sandbox for the repository, but the Pi harness and model credential stay in Zoen. It pins the PR base and head commits, gives the agent only bounded read/search tools, and validates inline coordinates against that exact local diff. Zoen then submits one GitHub review with a summary body and optional inline line comments.

• Requires sandbox execution. The provider key stays in Zoen, so hosted keys and BYOK are both supported.
• Needs a GitHub token that can clone the repo and submit reviews (see Setup).
• Needs the Pull Request Number to review.
• Does not load skills or memory, and never exposes shell, write, edit, or arbitrary network tools to the reviewer.
• Rechecks the PR immediately before submission and pins the review to the exact checked-out head commit.
• The deliverable is a submitted review — read reviewUrl and commentsPosted.

Local Dev

Local Dev runs the agent against a repository on a machine you control, reached over SSH. Changes are written in place — there's no PR; you review them as normal git changes on that machine.

• The machine must be reachable on a public hostname — localhost and LAN/private addresses are blocked. Expose it with a tunnel (see Setup).
• The agent's file and shell tools are confined to the Repository Path you configure.
• You can also expose Zoen tools (Gmail, Slack, Exa, …) to the agent so it can act beyond the repo while it works.

Configuration

Task

What the agent should do, in plain language — for example "Add input validation to the signup form and a test for it." or "Review this PR for security and correctness issues." Insert a connection tag to pass an earlier output, like <start.input>.

Model

The model that drives the agent. Defaults to claude-sonnet-4-6. The dropdown contains the intersection of models available in Zoen and exact provider-relative entries in the installed Pi catalog. Zoen never fabricates fallback model metadata.

API Key

Your key for the chosen provider. On hosted Zoen it is optional for Local Dev and Review Code runs (a hosted key is used and metered to your workspace). Create PR requires your own key because its model client runs in the sandbox. When the provider supports workspace BYOK, you can store the key in Settings → BYOK instead of entering it on the block.

Repository (Create PR / Review Code)

• Repository Owner / Repository Name — the GitHub repo (for example your-org / your-repo).
• GitHub Token — a personal access token used for GitHub access. Permissions differ by mode; see Create PR setup or Review Code setup.

Create PR fields

• Base Branch — the branch the PR is opened against and cloned from. Defaults to the repository's default branch.
• Branch Name (advanced) — the branch to push. Auto-generated when blank.
• Open as Draft PR (advanced) — opens the PR as a draft. On by default.
• PR Title / PR Body (advanced) — generated from the run when blank.

Review Code fields

• Pull Request Number — the PR to review (for example 42).
• Review Outcome — the GitHub review action to submit: Comment (default) or Request changes. Review Code intentionally does not submit approvals.

Connection (Local Dev)

• Host — the public hostname or tunnel for the target machine (for example 2.tcp.ngrok.io). Not localhost or a LAN address.
• Username — the SSH user (for example ubuntu, root, or your macOS account).
• Authentication Method — Password or Private Key.
• Password / Private Key — the credential for that method. Use a key where you can.
• Repository Path — the absolute path to the repo on the target machine (for example /home/user/my-repo). The agent's tools are confined to this directory.
• Port (advanced) — the SSH port. Defaults to 22; set this to your tunnel's port if it differs.
• Passphrase (advanced) — for an encrypted private key.

Tools (Local Dev)

Zoen tools the agent can call while it works — search a knowledge base, send a Slack message, call any of the integrations. They run through Zoen with your connected credentials, exactly like the Agent block. MCP and custom tools aren't supported here yet (they appear greyed out).

Skills (Create PR / Local Dev)

Agent skills the agent can use — reusable instruction packages like a coding standard or a review playbook. They're shared with the Agent block, so a skill you author once works in both.

Thinking Level

For models with extended reasoning, how much the model thinks before acting. Higher is more thorough but slower and costs more tokens. Defaults to medium.

Memory (Create PR / Local Dev)

Multi-turn memory keyed by a conversation ID, shared with the Agent block:

• None. Each run is independent.
• Conversation. The full history for that conversation ID.
• Sliding window (messages). The most recent N messages.
• Sliding window (tokens). Recent messages up to a token budget.

Reuse the same Conversation ID across runs to continue a thread. Each turn stores your task and the agent's final summary, which are folded into the next run's prompt. Review Code never loads or saves memory.

Context limits

For Create PR and Local Dev, memory is folded into the agent's first prompt, and two layers keep it within the model's context window:

• Zoen trims before the run. The selected memory type bounds what's injected: Conversation is automatically capped to a fraction of the model's context window (for models in Zoen's catalog), Sliding window (messages) keeps the last N messages, and Sliding window (tokens) keeps history up to an explicit token budget.
• Pi compacts during the run. As the agent works (reading files, running commands), Pi automatically summarizes older turns to stay under the window — in all modes, on by default. You don't need to configure anything for context growth mid-run.

The one case neither layer can rescue is a first prompt that already exceeds the window — Pi can only compact once there are older turns to summarize. This is only reachable with Conversation memory plus a model typed in manually (not in Zoen's catalog), where the automatic cap can't look up a context window. For long histories — and whenever you use a manually entered model — choose Sliding window (tokens): its budget applies regardless of the model, so the first prompt always fits.

Outputs

Setup

Create PR

Create PR runs in a sandbox image with the Pi CLI and git baked in.

1. Enable sandbox execution. On self-hosted Zoen, set E2B_ENABLED=true, E2B_API_KEY, E2B_PI_TEMPLATE_ID (the Pi template id), and NEXT_PUBLIC_E2B_ENABLED=true (this reveals Create PR and Review Code in the UI). Build the template with bun run apps/sim/scripts/build-pi-e2b-template.ts. Both modes stay hidden until NEXT_PUBLIC_E2B_ENABLED is set.
2. Bring your own model key. Set the provider API key in the block's API Key field, or store it in Settings → BYOK when the provider supports workspace BYOK.
3. Create a GitHub token with permission to clone, push, and open a PR:
   • Fine-grained: select the repo, then Contents: Read and write + Pull requests: Read and write.
   • Classic: the repo scope. For org repos, authorize the token for SSO.

Review Code

Enable sandbox execution as for Create PR. BYOK is optional because the model credential remains in Zoen. The GitHub token needs enough access to clone the repo and submit a review — push permission is not required:

• Fine-grained: select the repo, then Contents: Read + Pull requests: Read and write.
• Classic: the repo scope (or a narrower token that can read contents and write pull-request reviews). For org repos, authorize the token for SSO.

Local Dev

1. Enable SSH on the target machine (on macOS: System Settings → General → Sharing → Remote Login).
2. Expose it on a public host. Zoen blocks localhost/LAN, so use a TCP tunnel — for example ngrok tcp 22, which gives a host:port to put in Host and Port.
3. Use a model your provider supports (for example a Claude model with an Anthropic key). Set the credential method and Repository Path, then run.

Best Practices

• Scope the task. A specific instruction ("fix the failing auth test and add a regression case") produces far better results than a vague one.
• Match the mode to the deliverable. Create PR for unattended changes, Review Code for feedback on an existing PR, Local Dev for iterating on a repo you already have checked out.
• Prefer key auth and tear down tunnels. A public SSH tunnel is a real attack surface — use a private key and stop the tunnel when you're done.
• Reuse a Conversation ID for Create PR or Local Dev follow-ups. It carries the prior task and outcome into the next run so the agent can build on its own work.