Pi has two ways to delegate work to other AI coding agents:
Foreground Subagents
Dispatch Subagents
Background Subagents
Tool
interactive_shell
interactive_shell
(dispatch)
subagent
Visibility
User sees overlay
User sees overlay (or headless)
Hidden from user
Agent model
Polls for status
Notified on completion
Full output captured
Default agent
pi
(others if user requests)
pi
(others if user requests)
Pi only
User control
Can take over anytime
Can take over anytime
No intervention
Best for
Long tasks needing supervision
Fire-and-forget delegations
Parallel tasks, structured delegation
Foreground subagents
run in an overlay where the user watches (and can intervene). Use
interactive_shell
with
mode: "hands-free"
to monitor while receiving periodic updates, or
mode: "dispatch"
to be notified on completion without polling.
Dispatch subagents
also use
interactive_shell
but with
mode: "dispatch"
. The agent fires the session and moves on. When the session completes, the agent is woken up via
triggerTurn
with the output in context. Add
background: true
for headless execution (no overlay).
Background subagents
run invisibly via the
subagent
tool. Pi-only, but captures full output and supports parallel execution.
When to Use Foreground Subagents
Use
interactive_shell
(foreground) when:
The task is
long-running
and the user should see progress
The user might want to
intervene or guide
the agent
You want
hands-free monitoring
with periodic status updates
You need a
different agent's capabilities
(only if user specifies)
Use
subagent
(background) when:
You need
parallel execution
of multiple tasks
You want
full output capture
for processing
The task is
quick and deterministic
User doesn't need to see the work happening
Default Agent Choice
Default to
pi
for foreground subagents unless the user explicitly requests a different agent:
User says
Agent to use
"Run this in hands-free"
pi
"Delegate this task"
pi
"Use Claude to review this"
claude
"Have Gemini analyze this"
gemini
"Run aider to fix this"
aider
Pi is the default because it's already available, has the same capabilities, and maintains consistency. Only use Claude, Gemini, Codex, or other agents when the user specifically asks for them.
Foreground Subagent Modes
Interactive (default)
User has full control, types directly into the agent.
interactive_shell
(
{
command
:
'pi'
}
)
Interactive with Initial Prompt
Agent starts working immediately, user supervises.
interactive_shell
(
{
command
:
'pi "Review this codebase for security issues"'
}
)
Dispatch (Fire-and-Forget) - NON-BLOCKING, NO POLLING
Agent fires a session and moves on. Notified automatically on completion via
triggerTurn
.
// Start session - returns immediately, no polling needed
interactive_shell
(
{
command
:
'pi "Fix all TypeScript errors in src/"'
,
mode
:
"dispatch"
,
reason
:
"Fixing TS errors"
}
)
// Returns:
// → Do other work. When session completes, you receive notification with output.
Dispatch defaults
autoExitOnQuiet: true
. The agent can still query the sessionId if needed, but doesn't have to.
Background Dispatch (Headless)
No overlay opens. Multiple headless dispatches can run concurrently:
interactive_shell
(
{
command
:
'pi "Fix lint errors"'
,
mode
:
"dispatch"
,
background
:
true
}
)
// → No overlay. User can /attach to watch. Agent notified on completion.
Hands-Free (Foreground Subagent) - NON-BLOCKING
Agent works autonomously,
returns immediately
with sessionId. You query for status/output and kill when done.
// 1. Start session - returns immediately
interactive_shell
(
{
command
:
'pi "Fix all TypeScript errors in src/"'
,
mode
:
"hands-free"
,
reason
:
"Fixing TS errors"
}
)
// Returns:
// 2. Check status and get new output
interactive_shell
(
{
sessionId
:
"calm-reef"
}
)
// Returns:
// 3. When you see task is complete, kill session
interactive_shell
(
{
sessionId
:
"calm-reef"
,
kill
:
true
}
)
// Returns:
This is the primary pattern for
foreground subagents
- you delegate to pi (or another agent), query for progress, and decide when the task is done.
Hands-Free Workflow
Starting a Session
const
result
=
interactive_shell
(
{
command
:
'codex "Review this codebase"'
,
mode
:
"hands-free"
}
)
// result.details.sessionId = "calm-reef"
// result.details.status = "running"
The user sees the overlay immediately. You get control back to continue working.