Overview
Pi exposes read, write, edit and bash by default. Subagent orchestration is added by extensions, which schedule child sessions and return their results to the parent.
Choose along three separate axes: where the child runs, what context it receives, and which files it may edit. A separate session does not automatically provide a separate working directory.
Compare by use case
Scroll the table horizontally; configuration and sources follow below.
| Resource & purpose | Mechanism | Dependencies & keys | Data sent | Failure behavior | Evidence |
|---|---|---|---|---|---|
| @tintinweb/pi-subagents SDK child sessions with background queuing, live TUI visibility and optional Git worktrees. | Ordinary agents call createAgentSession in the host process. Background work returns an ID and sends a completion notification; worktree isolation changes the child working directory. Workflow scripts run in a worker thread. | Pi ≥ 0.84.0 and an authenticated model. Only worktree mode requires Git, a repository and at least one commit; ordinary child sessions can run outside Git repositories. | Each child sends its task, selected context and tool results to its configured model provider. inherit_context is false by default; the general-purpose agent still inherits the parent system prompt. | A requested worktree that cannot be created fails the tool call instead of silently sharing the parent directory. Completed worktree changes are preserved on a local pi-agent-<id> branch; the temporary directory is removed. | Agent execution ↗ |
| pi-subagents Focused workers, parallel or chained tasks, and observable background runs. | Foreground children use SDK sessions in the parent process. Background children use a detached runner process hosting SDK sessions. Managed worktrees are optional here too, including per-child isolation in workflows. | A Pi host and authorized child models; npm Pi uses the detached Node runner for background work. Managed worktrees require Git and a clean source checkout. The documented standalone boundary is Pi 0.86.1 Linux x64. | Tasks, supplied or forked context and tool output reach each selected model provider. Forking a long parent conversation can repeat substantial input context. | Inspect failed runs and captured artifacts before retrying. Worktree handoff records preserve patches and cleanup status; a successful child result does not imply its changes were merged. | Foreground SDK execution ↗ |
Installation & operating boundaries
@tintinweb/pi-subagents
SDK child sessions with background queuing, live TUI visibility and optional Git worktrees.
pi install npm:@tintinweb/pi-subagents- Mechanism
- Ordinary agents call createAgentSession in the host process. Background work returns an ID and sends a completion notification; worktree isolation changes the child working directory. Workflow scripts run in a worker thread.
- Prerequisites
- Pi ≥ 0.84.0 and an authenticated model. Only worktree mode requires Git, a repository and at least one commit; ordinary child sessions can run outside Git repositories.
- Data scope
- Each child sends its task, selected context and tool results to its configured model provider. inherit_context is false by default; the general-purpose agent still inherits the parent system prompt.
- Failure behavior
- A requested worktree that cannot be created fails the tool call instead of silently sharing the parent directory. Completed worktree changes are preserved on a local pi-agent-<id> branch; the temporary directory is removed.
- Known limitations
- Background concurrency defaults to 10; excess work queues. Foreground capacity is separate and defaults to unlimited (0). Worktrees start from committed history and cannot see staged or uncommitted parent changes. Filesystem separation is not an OS sandbox.
Source / documentation reviewed · v0.19.0 · e955e29c51b7a6cce37e1108cd2d6c57a77e151c
pi-subagents
Focused workers, parallel or chained tasks, and observable background runs.
pi install npm:pi-subagents- Mechanism
- Foreground children use SDK sessions in the parent process. Background children use a detached runner process hosting SDK sessions. Managed worktrees are optional here too, including per-child isolation in workflows.
- Prerequisites
- A Pi host and authorized child models; npm Pi uses the detached Node runner for background work. Managed worktrees require Git and a clean source checkout. The documented standalone boundary is Pi 0.86.1 Linux x64.
- Data scope
- Tasks, supplied or forked context and tool output reach each selected model provider. Forking a long parent conversation can repeat substantial input context.
- Failure behavior
- Inspect failed runs and captured artifacts before retrying. Worktree handoff records preserve patches and cleanup status; a successful child result does not imply its changes were merged.
- Known limitations
- Separate context does not separate files. Without worktrees, coordinate writers explicitly. globalConcurrencyLimit defaults to 20 children inside a run, while maxSubagentSpawnsPerRun separately defaults to 64 total admissions. These are not a token budget.
Source / documentation reviewed · v0.70.1 · 1ac7b5e2652e9571164847ac2905ab4aded92791
Compare execution models
The current pi-subagents runs foreground children inside the parent SDK process and background children in a detached runner. @tintinweb/pi-subagents runs ordinary foreground and background agents inside the host SDK process; only its scripted workflow interpreter uses a worker thread.
Both packages now support optional worktrees. The useful distinction is lifecycle and handoff: Nico’s managed workflow worktrees capture patches and manifests; Tintin preserves completed changes on local branches. Neither merges those changes just because a child completed.
Choose for the work
For parallel reading or independent reviews, separate sessions in the same checkout avoid worktree setup and let reviewers see your uncommitted diff. For concurrent writers, assign disjoint files or explicitly request worktrees.
Choose Tintin when you want Agent/get_subagent_result, live widgets and steerable background agents. Choose Nico when you want its worker/reviewer profiles, chains, scripted workflows and detached background artifacts. Test the installed version in your own TUI or SDK host before relying on UI behavior.
Token cost and context isolation
Estimate total usage as parent input/output + every child’s input/output + result summaries. N parallel children can pay for N copies of the same supplied context. Process separation and worktrees do not reduce token prices.
Prefer a focused task and minimal context for a scout; fork history only when the child needs the discussion. Restrict tools, choose an appropriate model and cap concurrency. Compare reported child token/cache usage on the same task; no cross-package token benchmark was run for this guide.
Verify a first delegation
After installing one chosen package, restart Pi and first delegate a read-only inventory of the repository. Confirm that the parent receives a result, the child uses the expected model and the working tree stays unchanged.
For Tintin, the following Agent call requests background reading without a worktree. Open /agents to inspect the session. Only add isolation: "worktree" for a task that needs a separate committed checkout.
Agent({
subagent_type: "Explore",
prompt: "List the test commands and their source files. Do not edit files.",
description: "Find test commands",
run_in_background: true
})Primary sources & verification scope
Source review and runtime testing are distinguished above. Features, performance and savings not marked “Tested” are not measurements by Pi Index.