@tintinweb/pi-subagents: Background Subagents

Overview

This extension adds Agent, get_subagent_result and steer_subagent to Pi. It supports background work by default and live TUI inspection through /agents.

Worktree isolation is an explicit option, not the default behavior of every child. Separate conversations alone do not prevent two writers from editing the same files.

Session and concurrency model

Ordinary children are SDK sessions inside the host process. Background calls return an ID, queue when capacity is occupied and notify the parent when done. Foreground calls wait for the result.

maxConcurrent defaults to 10 background agents. maxConcurrentForeground defaults to 0 (unlimited) and is a separate limit. Live widgets report activity and token counts; UI features depend on an interactive Pi host. SubagentWorkflow scripts use a worker thread, so “all execution is single-threaded” would also be inaccurate.

What worktree isolation guarantees

Add isolation: "worktree" to the Agent call or agent frontmatter. The child works in a temporary checkout from committed history. Git and an initial commit are required; worktree creation errors fail the call rather than falling back to the parent checkout.

Staged and uncommitted parent changes are absent. Use the shared checkout for reviewing such diffs. A worktree separates working files, but a child with shell access can still leave that directory; it is not a security sandbox.

On completion, unchanged worktrees are removed. Changed work is committed or retained on a local pi-agent-<id> branch, and the temporary directory is removed. Review the named branch and run project checks before merging; there is no automatic merge into the parent branch.

Try a bounded task

Use the install command below, confirm Pi ≥ 0.84.0, and restart. First run Explore without isolation to validate tools, model access and completion delivery. For a writer, request a worktree explicitly and give it one independently testable change.

The example creates an isolated writer. After it completes, inspect the branch reported by get_subagent_result and compare it against the original base. The example is a recipe; no model task was executed during this source review.

Agent({
  subagent_type: "general-purpose",
  prompt: "Fix the documented failing test. Run the relevant tests and report the changed files.",
  description: "Fix one failing test",
  isolation: "worktree",
  run_in_background: true
})

Control context and spend

inherit_context defaults to false; general-purpose still receives the parent system prompt. Agent frontmatter can lock context inheritance, model and isolation settings, overriding call parameters. Check /agents when a requested option seems ignored.

Every child has its own model usage. Copying a long conversation to several agents can multiply input costs; worktree creation adds filesystem work, not a token discount. Use focused prompts, suitable models and lower concurrency before expanding the fleet.

How it differs from pi-subagents

Nico’s pi-subagents also supports worktrees. Its foreground execution uses in-process SDK sessions, while background work uses a detached runner and exposes run artifacts. The difference is orchestration and lifecycle, not simply “worktrees versus no worktrees.”

Choose the tool interface and result handoff you prefer, then test a small read-only run in your actual host. Installing both can create overlapping orchestration choices for the model.