fork

Spawn pi subagents in tmux windows. Each child is a separate pi process you can watch and type into; it reports back over a Unix socket and stays alive for revision requests. Assumes fluency with pi, tmux, and git worktrees, and stays out of the way — including silently doing nothing outside tmux.

Requirements

• pi 0.80.4 or newer (newest pi API used: agent_settled)
• tmux, with pi running inside it
• git, for branch worktree isolation
• Linux; macOS untested (nothing Linux-specific), Windows unsupported

Install

pi install npm:@resolveworks/fork

Or from git:

pi install git:github.com/resolveworks/fork

Or once, without installing:

pi -e npm:@resolveworks/fork

Then restart pi, or /reload.

What you get

The parent session gains three tools:

• spawn_agent({ task, branch? }) — writes the task to a file and opens a new tmux window running pi @<taskfile>. Returns immediately. The child sees the task plus normal project context, not the parent's conversation, so the task must be self-contained.
• message_agent({ id, text }) — steers a revision request into the child's current run, or starts a new turn when the child is idle.
• close_agent({ id }) — mechanical shutdown; no model turn spent.

The child gains report_result({ result }). The report travels over a Unix socket and arrives in the parent as a steering notification: immediately if the parent is idle, or injected into the parent's current run after its pending tool calls. The child stays alive after reporting, awaiting the verdict: revisions via message_agent, or closure. Reports are outcomes, not progress updates. If delivery fails, the child is told unambiguously and retries with the same payload — a retry cannot double-deliver. Interrupting the parent would drop its queued notifications, so fork re-delivers them once the interrupted run settles — an escape can no longer lose a report.

Don't poll. Navigate windows with your usual tmux keys.

Isolation

Without branch, the child shares the parent's working tree — fine for read-only or sequential work, a bad idea for concurrent editors.

With branch: "kebab-name", fork runs git worktree add ~/.pi/worktrees/<uuid> -b agent/<kebab-name> HEAD and spawns the child there. The child commits its work; close_agent force-removes the worktree (uncommitted work dies with it) and retains the branch for normal review and merge.

Fork deliberately does no environment setup and runs no checks. git worktree add fires the repo's post-checkout hook — put pnpm/uv/whatever setup there. Commit hooks validate.

Config

~/.pi/agent/fork.json, overridden per-project by .pi/fork.json (read only in trusted projects). All fields optional; passed through to the child as CLI flags:

{ "model": "glm-5.2", "provider": "zai", "thinking": "high" }

Runtime state

Under ~/.pi/agent/extensions/fork/ (sockets and task files are mode 0o600):

• sockets/<parent-session-id>.sock — result channel, child → parent
• agents/<uuid>.sock — verdict channel, parent → child
• tasks/<uuid>.md — the task handed to the child; a present task file marks an open agent and is authoritative across extension reloads

Development

Requires Node.js 22.18 or newer and pnpm 11.3.0.

pnpm install --frozen-lockfile
pnpm typecheck
pnpm format:check

Use pnpm format to apply formatting.

License

MIT