Skip to content
pi-code

subagent

Delegate tasks to specialized agents, each running as a separate pi-code process with its own context window. Three execution modes:

  • Single — one agent, one task, wait for result
  • Parallel — multiple independent tasks running concurrently
  • Chain — sequential steps where each receives the previous output via {previous} placeholder

Each subagent can use a different model, have a different role description, and work in a different directory. JSON mode captures structured output for the parent agent to process.

Why it matters: Complex tasks decompose naturally into independent subtasks. A refactor might need one agent exploring the codebase, another reviewing types, and a third writing tests — all running simultaneously instead of sequentially.

Foreground vs background agents

Subagents run in two modes:

  • Foreground — the parent agent blocks waiting for the result. Used in single mode and chain mode where the output feeds back into the next step.
  • Background — the agent runs independently. Used when the parent says background: true. The agent works while the conversation continues.

Both types appear in the tasks widget with colored @name identifiers, live activity status, and elapsed time. Background agents persist until their task completes or the session ends.

Relationships with other extensions

tasks

Subagents and the task board are deeply integrated. When a subagent claims a task (via manage_tasks with owner), the task widget shows (@agent-name) attribution in the agent’s color. The in-progress spinner animates only while the owning agent is actively running — if the agent finishes but the task isn’t marked complete, the spinner switches to a static ● indicator.

In-progress tasks show their activeForm text (e.g., “Writing tests”) instead of the subject, giving live visibility into what each agent is doing.

On wide terminals, running agents appear in a right column alongside the task list. On narrow terminals, they stack below. See tasks — responsive layout for the full breakdown.

background-tasks

Subagents and background bash tasks share display space in the tasks widget. When both are active, agents render above background tasks with a spacer between. Each gets independent truncation based on the available width.

The footer shows a (sub) count when subagents are running. The tasks extension adds a separate agent bar to the status area: @main @alice @bob · 2 teammates with colored names matching the widget display.