Pi Orchestrator

Pi Orchestrator manages multiple pi coding-agent terminals from a VS Code sidebar. Pi still runs as its normal interactive TUI in a real integrated terminal; the extension adds names, lifecycle visibility, Git/worktree context, and diff links.

Requirements

• VS Code 1.100 or newer.
• pi 0.80.7 or newer installed in the environment where the VS Code extension host runs.
• git for branch, worktree, origin, and change information.
• For WSL, open a Remote–WSL window first. Install/enable Pi Orchestrator in WSL when prompted; pi and git must be available inside WSL.

Use

1. Open Pi Orchestrator in the Activity Bar.
2. Select +.
3. Enter an optional name (empty uses the folder name).
4. Select any filesystem folder accessible to the current extension host.
5. For Git repositories, choose the selected checkout, the main checkout, an existing worktree, or Create a new worktree with Pi Orchestrator. The last option uses the bundled portable /pio-wt new command and supported Pi session handoff.
6. Work with pi normally in its terminal. Create as many sessions as required.

Select a live session to focus its terminal. Use its context menu to rename, stop, remove, or relaunch it. The reporter links each entry to pi's exact persisted session file and updates that link when /pio-wt new or /pio-wt join switches into the target worktree session. Relaunch resumes that conversation with pi --session, preserving its conversation tree and worktree context. If the linked file was deleted, Orchestrator falls back to its saved Pi session ID when available; otherwise it asks before starting fresh. Definitions are saved across reloads, but agents are deliberately not relaunched automatically. A restored definition is shown as stopped until you choose Relaunch.

Spawn tasks from a parent pi

Every root managed pi exposes generic local tools: pi_orchestrator_spawn, pi_orchestrator_resume, pi_orchestrator_list, pi_orchestrator_inspect, and pi_orchestrator_send. After discussing any set of tasks, explicitly ask the parent to “spin these up in Pi Orchestrator.” The parent supplies normalized names and complete prompts; Orchestrator creates one real terminal per task and, by default, runs each through its bundled /pio-wt new handoff. Task sources are deliberately irrelevant—conversation, issue tracker, or pasted text all behave identically.

Spawn mode worktree is the default and requires a Git repository. Explicit mode nt (“no tree”) launches directly in the requested absolute directory, creates that directory when missing, and does not require Git. Agents may use nt only when the user explicitly requests a direct/no-worktree folder; this keeps isolated worktrees as the safe default.

Supply only the task to perform. Do not instruct the child to create a worktree or invoke /pio-wt or /wt; Orchestrator performs that handoff automatically. Spawned children cannot recursively spawn more sessions by default. Recursive orchestration requires the explicit piOrchestrator.allowRecursiveSpawning opt-in.

Ownership is selected per task:

• user (default): launch and hand the unique terminal to the user.
• supervised: preserve the parent/child relationship so the parent can list, inspect, and message the child when asked.
• managed: also notify and wake the parent when a child settles or needs an answer. The parent is instructed to relay user questions rather than invent answers.

The control transport is an authenticated-by-possession, instance-private atomic file queue under VS Code global storage; no public port or terminal text injection is used. External references are optional and deduplicate repeated spawn requests from the same parent.

Recover conversations as children

If terminals are lost after a reload, extension replacement, WSL shutdown, or another interruption, relaunch the original parent and ask it to recover the conversations as children. When the exact Pi session file or ID is known, pi_orchestrator_resume launches it directly with no human selection. Otherwise Orchestrator opens Pi’s startup resume picker (pi -r) in the original project/worktree cwd. Once linked, the reporter preserves the parent/child ownership relationship and marks it as a resumed child rather than a newly spawned task.

The same flow is available without an agent tool: right-click the intended parent in the sidebar and choose Resume Conversation as Child, then select the folder where the conversation appears in /resume. Cancelling the picker leaves a stopped/exited recovery definition that can be relaunched to try again. Stable externalRef values deduplicate retried recovery requests.

Bundled worktree handoff

Every Orchestrator-managed terminal loads a portable /pio-wt Pi command in addition to the status reporter:

/pio-wt new <task>
/pio-wt join <directory, branch, or absolute path>

new asks the agent to create a registered worktree using repository-local conventions, then switches to a new Pi session rooted there before starting the task. join resolves only registered Git worktrees and forks the current conversation into the selected checkout. The command is loaded with Orchestrator’s -e argument, so it is visible only in managed terminals and does not install globally or replace an existing /wt command. It has no fixed home directory, repository name, base branch, package manager, setup command, or port assumptions.

Heavy-work capacity and enforced leases

Orchestrator enforces a shared semaphore for expensive child work. Select the server-process button in the Pi Sessions view title to set the limit, pause/resume admission, manage named reservations, or inspect active and queued work. The view title always shows used/limit, plus queue and paused indicators. The same controls are available through Pi slash commands:

/orch capacity 5
/orch status
/orch pause
/orch resume
/orch reserve 1 deploy
/orch reserve 0 deploy   # remove the reservation

piOrchestrator.majorProcessLimit persists capacity at workspace scope (or globally when no workspace is open). Pause and named external reservations are live for the current Orchestrator instance. Reservations subtract from child capacity.

Before heavy work, an agent calls pi_orchestrator_request_lease with kind, estimatedMinutes, commands, and an optional preferredPort. The result is either granted with a unique allocated port or queued with its FIFO position. A queued child is notified automatically when promoted. It must tear down exact PIDs/browser resources and call pi_orchestrator_release_lease; a granted lease is also released when the agent settles. Heartbeats and a TTL recover capacity after crashes.

The bundled child extension blocks matching bash tool calls, interactive ! commands, browser tools, and /drp without a granted lease. Built-in categories cover dependency installs, dev servers, builds/typechecks, broad tests, emulators, browsers, and /drp. Control those categories with piOrchestrator.heavyCommandPresets; remove presets that do not apply to the workspace. Add project-specific case-insensitive regular expressions with piOrchestrator.heavyCommandPatterns.

Sidebar information

If a pi command such as /pio-wt new or /pio-wt join moves the live session into a worktree, the bundled reporter sends pi's updated working directory and the sidebar automatically switches its folder, branch, worktree, origin, task, and change metadata to that location.

The sidebar is repository-scoped: it shows roots owned by the current workspace’s repositories and all children in those roots’ lineage. A child explicitly spawned into another repository remains with its originating parent, while unrelated roots from other workspaces stay hidden. Sessions are collapsed by default and grouped into Parent sessions followed by a separate Children of … section for each spawning parent. The colored state icon and description show state · Δchanged-files · branch without expanding the session. Select a row to focus its terminal, or use the inline pencil and close actions to rename or remove it. Hover for exact additions/deletions and task details. Disable icon colors with piOrchestrator.colorizeStatusIcons if you prefer theme-neutral icons.

A session shows one of:

• starting — terminal created and reporter starting
• working — pi is processing
• idle — pi settled and awaits normal input
• waiting-question — a question tool or final question was detected
• stopped — no live terminal, usually explicitly stopped or restored
• exited — the observed terminal closed
• failed — pi reported an agent error or launch failed

A question icon and Activity Bar badge highlight sessions that need an answer. Expand a session for its folder, current goal/task or latest prompt, branch/detached commit, main-checkout/worktree classification, inferred Git origin, and changed-file totals. Child sessions also show their parent and whether the relationship came from a task spawn or conversation resume. Select a changed file to open VS Code's native diff.

Diffs show the net HEAD ↔ working tree state. This includes both staged and unstaged changes. Untracked files compare with an empty document; deleted files compare their HEAD version with an empty document.

Configuration

Arguments are transported as an array, not composed into a shell string, so folders and arguments containing spaces or shell metacharacters remain intact.

Status integration

Every managed terminal is launched with the bundled pi-extension/status-reporter.ts through pi's supported -e option. The reporter listens to documented pi lifecycle events and atomically writes a small per-session status snapshot under VS Code extension storage. It neither changes pi's tools/UI nor consumes terminal input.

Structured agent and question-tool events are high confidence. When pi ends with ordinary assistant text asking a question, a narrow final-message heuristic supplies a lower-confidence waiting-question fallback. VS Code does not expose integrated terminal output, so raw ANSI/output scraping is not used. If the reporter cannot load, the extension can still observe terminal creation/closure but cannot reliably identify working or question states.

See docs/architecture.md for design details and limitations.

Development

npm install
npm run build
npm run typecheck
npm run lint
npm test
npm run test:integration
npm run test:real-pi
npm run package

Press F5 in this repository to open an Extension Development Host. A manual smoke-test checklist is in docs/smoke-test.md.

Known limitations

• Parent/base is explicitly inferred: upstream is preferred, then a merge-base with main or master; it may remain unknown.
• Plain assistant questions are heuristic and may be missed or misclassified.
• VS Code/WSL shutdown does not guarantee terminal process survival.
• The first release targets local and Remote–WSL filesystem workspaces, not arbitrary virtual filesystem providers.