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 creates or updates a pull request, posts a PR review, or changes your files in place. Create PR and Update PR can optionally babysit their pull request. Create PR, Update PR, and Local Dev can reuse your skills and multi-turn memory. Review Code deliberately loads neither.

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

• Create PR — spins up an isolated sandbox, edits the repository, and opens a pull request. Its optional Babysit Mode requests bot reviews and works through trusted feedback and checks in bounded rounds.
• Update PR — checks out an existing branch in an isolated sandbox, edits it, pushes a new commit back to that branch, then creates or updates its pull request. Its optional Babysit Mode continues that PR.
• 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.
• 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.

Babysit Mode

When enabled, both modes ensure the branch has a ready-for-review PR before posting every required Reviewer Mention as its own issue comment and starting a second, strict sandbox against that PR. Update PR uses the exact open same-repository PR whose head is the target branch, or creates it when missing. They repeat this bounded host-controlled lifecycle:

1. Read every review thread and the complete check rollup for the pinned SHA.
2. Give Pi trusted block instructions plus clearly delimited, untrusted thread/check data and bounded diagnostics.
3. Let Pi edit the checkout and write a strict per-thread decision file.
4. Refuse detached/mismatched refs, multiple commits, cumulative bounds violations, or .github/ changes; then push one non-forced commit to the exact pinned head ref.
5. Post successful replies first, revalidate the PR, and resolve only threads whose reply succeeded.
6. Post each configured reviewer comment again, then wait for later bot review activity and for the checks that commit re-triggered. Babysit never re-runs CI itself — the push is what starts a new run.

Wait-only check/review polling does not consume Maximum Rounds. The sandbox stays alive—and is billed—during those waits.

Only complete threads are actionable. Every comment in a thread must come from an owner, member, collaborator, or GitHub App bot; otherwise the whole thread is skipped and threadsClean remains false. Bots operating through ordinary user accounts are skipped unless their association is trusted. Optional check failures are included when Pi runs a fixing round but do not block checksGreen; required failures, required pending/expected contexts, missing post-push contexts, incomplete reads, and unknown states all fail closed.

The continuation gives Pi no GitHub credential, GitHub tool, or Sim integration. GitHub API operations use block-configured coordinates on the host and are not filtered by workspace tool denylists. The model and optional search keys do enter the editing sandbox. The GitHub token enters only the clone and credentialed push commands. This is risk reduction, not credential isolation: the push still executes inside a previously agent-controlled root sandbox.

• Requires at least one Reviewer Mention, such as @greptile or @cursor review.
• Needs Contents, Pull requests, Issues, Actions, and commit-status/check read access as described in Create PR setup and Update PR setup.
• Does not support fork PRs, force-push/history rewriting, merge-conflict resolution, or .github/ edits. A base conflict is reported but does not prevent review-fix pushes.
• A round that posts replies but loses the pin before resolving can reply to the same unresolved thread again on a later run. Replies are intentionally safer than resolving stale feedback.

Update PR

Update PR uses the same disposable authoring sandbox and host-controlled PR operations as Create PR, but checks out a branch that already exists and pushes changes back to it.

• Requires sandbox execution and your own provider API key (BYOK).
• Needs the same GitHub token permissions as Create PR: permission to clone, push, and create or update a pull request.
• Never creates, rebases, merges, or force-pushes the branch. If another commit reaches the branch while Pi is working, the push fails rather than overwriting it.
• Finds the exact open same-repository PR whose head is the target branch and checks again after authoring. One match is updated; no open match—including when an earlier or preflight PR was closed—creates a new PR; multiple open matches fail as ambiguous.
• When explicitly set, Base Branch, PR Title, PR Body, and PR State update the existing PR. Blank metadata preserves it. A newly created PR uses generated metadata and the repository default base when those fields are blank.
• A no-change authoring pass still creates or updates the PR. A rejected initial push stops the run before any PR mutation or Babysit continuation.
• The deliverable is the updated branch and its PR — read prUrl, branch, changedFiles, and diff.

Review Code

Review Code uses a disposable sandbox for the repository, but the Pi harness and model credential stay in Sim. 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. Sim then submits one GitHub review with a summary body and optional inline line comments.

• Requires sandbox execution. The provider key stays in Sim, 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, or edit tools to the reviewer. Its only network access is Internet Search, and only when you select a provider.
• 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 Sim 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 Sim and exact provider-relative entries in the installed Pi catalog. Sim never fabricates fallback model metadata.

API Key

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

Internet Search

Off by default. Pick a provider — Exa, Serper, Parallel AI, or Firecrawl — and the agent gains a single web_search tool that returns a handful of results, each with a title, URL, snippet, and (where the provider reports one) a publication date. It works the same way in all four modes, and it is the agent's only network access in Review Code. The tool accepts at most 20 calls per block execution, which bounds accidental tool loops. A Pi block inside a Loop or Parallel gets that allowance again on every iteration, so bound the iteration count too if you care about what a single workflow run can spend.

Search always uses your own key for the selected provider, entered in the block's Search API Key field. That field is the only source: there is no workspace BYOK fallback and Sim never supplies a hosted search key, so unlike the model key this field appears on every deployment. Leave it empty and the run fails with a setup error before any sandbox is created. Changing the provider in the editor clears the field, so re-enter the key that belongs to the provider you picked — a workflow you import, fork, or update through the API keeps whatever key was saved, so check it there.

Results are third-party data. The agent is instructed to treat them as quoted evidence and never to follow instructions found inside them — the same posture Pi takes toward repository contents.

Traffic goes both ways: the agent writes its own queries after reading the repository, so leave search on None in Review Code when the pull request comes from an untrusted fork of a private repo. Injected instructions in a diff could otherwise put repository text into a query sent to the provider.

Repository (Create PR / Update 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, Update 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.
• Babysit Mode — creates a ready-for-review PR, requests bot reviews, and monitors trusted feedback and required checks.
• Reviewer Mentions — required when Babysit Mode is enabled. A bounded comma-separated list of issue-comment commands; each entry is posted immediately and after every pushed fix.
• Maximum Rounds (advanced) — fixing rounds that invoke Pi, from 1 to 10; defaults to 3. Wait-only polling does not consume this count.
• 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 and hidden when Babysit Mode is enabled, because those PRs are always ready for review.
• PR Title / PR Body (advanced) — generated from the run when blank.

Update PR fields

• Target Branch — the existing remote branch to update. The run fails if it does not exist, is protected against the token, or changes before Pi pushes.
• Base Branch — changes an existing PR's base when set, or becomes a new PR's base. A new PR defaults to the repository's default branch when blank.
• Babysit Mode / Reviewer Mentions / Maximum Rounds — the same controls as Create PR. Babysit makes the PR ready for review and creates it first when the target branch has no open PR.
• PR State (advanced) — preserves an existing PR's draft state, converts it to draft, or marks it ready for review. A missing PR opens as a draft for Leave unchanged or Draft, and ready for Ready for review. Hidden during Babysit because Babysit always requires a ready PR.
• PR Title / PR Body (advanced) — update an existing PR only when set. For a missing PR, blank values are generated from the task and run summary.

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)

Sim tools the agent can call while it works — search a knowledge base, send a Slack message, call any of the integrations. They run through Sim 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 / Update 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. Create PR and Update PR pass explicitly selected Sim skills to their Babysit continuation, while repository skills, Pi extensions, prompt templates, and project trust remain disabled there.

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 / Update 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 initial authoring or Local Dev summary, which is folded into the next run's prompt. Review Code never loads or saves memory. A Babysit continuation starts with empty memory, and its review-derived report is not saved to memory.

Context limits

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

• Sim 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 Sim'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 Sim'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, Git, Node.js, and Bun baked in. Repository dependencies are not preinstalled; Pi can run bun install when a repository needs them.

1. Enable sandbox execution. On self-hosted Sim, 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, Update PR, and Review Code in the UI). Build the template with bun run apps/sim/scripts/build-pi-e2b-template.ts. These modes stay hidden until NEXT_PUBLIC_E2B_ENABLED is set.

   The template requests 4 vCPU and 8 GB of RAM (within the per-build maximum on every E2B plan). Sizing is fixed when the template is built — E2B has no per-sandbox override — so changing it means rebuilding the template, not restarting Sim. Sandboxes are billed per second against the resources they are allocated, not the ones they use. Both numbers live in apps/sim/scripts/pi-sandbox-packages.ts and are shared with the Daytona snapshot so the failover image cannot drift from the primary.

   Sim sizes each Pi sandbox to the execution's own remaining time, so a run never holds a sandbox longer than the platform would let it run. E2B also imposes a 24-hour continuous-sandbox ceiling on the Professional plan, so one Pi sandbox is capped there even when an Enterprise workflow policy is longer. PI_SANDBOX_LIFETIME_MS may lower that ceiling but has a 31-minute minimum; lower values are raised to the minimum. A run that outlives the sandbox loses its work before the push, and an orphaned sandbox — one whose Sim process died mid-run — bills until the lifetime expires, which is why that lifetime tracks the deadline. Babysit Mode uses a second sequential sandbox after the creation sandbox has been destroyed; it is billed while polling checks and reviews. Daytona remains unchanged because its auto-stop setting is inactivity-based rather than an absolute lifetime.

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.

When Babysit Mode is enabled in either authoring mode, use an asynchronous schedule, webhook, or background execution where possible because the continuation can spend several minutes waiting for CI or review bots. The token must additionally read checks and Actions logs, reply to and resolve review threads, and post issue comments:

• Fine-grained: add Issues: Read and write, Actions: Read, and Commit statuses: Read (plus check-suite read access if your organization exposes it separately).
• Classic: the repo scope, SSO-authorized for organization repositories. A classic token or GitHub App installation may be required where a fine-grained token cannot access every check endpoint.

clean is the only stop reason that means the PR reached the goal state: no actionable or skipped unresolved threads, no failing, pending, or missing required checks, and a later bot review signal after the most recent review request. Every other value is a partial success or a stop, so compare against clean rather than assuming a returned report means the PR is done.

awaiting_checks is an expected partial-success outcome after a push: GitHub may not finish CI within the remaining execution budget. Other stop reasons are awaiting_review, no_pr_created, closed_or_merged, fork_pr, skipped_threads, stuck_threads, stuck_checks, check_read_failed, startup_failure, head_moved, push_rejected, pushed_awaiting_confirmation, refused_content, bounds_exceeded, agent_failure, and budget/round exhaustion. Once the PR exists, these outcomes preserve prUrl and branch; always inspect the explicit booleans and counters rather than treating a returned report as proof that the PR is clean.

Babysit enforces fixed bounds that are not configurable, and they behave differently depending on which one you hit:

• Rejected before the run starts. Reviewer Mentions accepts at most 10 entries, each at most 200 characters, and at most 2000 characters of input in total. Each entry must begin with @. Exceeding any of these fails the block with a validation error rather than a stopReason.
• Trimmed silently. At most 30 review threads are shown to Pi per round. Extra actionable threads are carried to a later round, so threadsClean stays false until they are handled.
• Stops the run with bounds_exceeded. More than 20 failing required checks in a round, or a cumulative change across the run exceeding 50 files or 200,000 diff bytes.

Update PR

Enable sandbox execution and BYOK as for Create PR. Update PR also uses the same GitHub permissions because it always creates or updates a pull request after authoring:

• Fine-grained: select the repo, then grant Contents: Read and write + Pull requests: Read and write.
• Classic: the repo scope. For org repos, authorize the token for SSO.

The target branch must already exist. GitHub branch protection remains authoritative, and a branch that advances during the run rejects Pi's normal non-force push.

Update PR accepts one exact open same-repository PR for the target branch, creates one when none exists, and fails if the match is ambiguous. It does not support fork PRs. With Babysit Mode, the token also needs the Issues, Actions, commit-status, and check permissions listed above.

Review Code

Enable sandbox execution as for Create PR. BYOK is optional because the model credential remains in Sim. 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. Sim 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 a new reviewable branch, Update PR for continuing existing remote work and managing its PR, Review Code for feedback on a PR, and Local Dev for a repo you already have checked out.
• Use Babysit Mode for automated review follow-through. Run it asynchronously and expect partial success; a pushed fix followed by awaiting_checks is normal.
• 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, Update 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.