| name | claude-pi-orchestrate |
| description | Use when a task is mechanical, parallelizable, requires a different model's strengths, or where delegating preserves tokens — file generation, boilerplate, batch transforms, research, summarization, or any subtask independent of the current conversation context. |
Pi Orchestration
Model Tiers
Tiers are populated from the [pi-models] notification at session start.
| Tier | Examples | Use when |
|---|
| fast | gemini-2.0-flash, claude-haiku-4-5, gpt-4o-mini | Formatting, boilerplate, mechanical transforms |
| balanced | gpt-4o, claude-sonnet-4-6, o3-mini | Standard coding, analysis, research |
| frontier | gemini-2.5-pro, claude-opus-4-7, o3 | Novel reasoning, architecture, state-of-the-art tasks |
Model keys use provider/id format when calling tools:
google/gemini-2.5-pro (frontier)google/gemini-2.0-flash (fast)anthropic/claude-haiku-4-5 (fast)openai/gpt-4o (balanced)
Session-Start Awareness
At session start, Claude receives a [pi-models] notification from the monitor. Two forms:
[pi-models] Available: <model> (<tier>), ... — use pi_list_models to refresh — use the listed models[pi-models] No models available — configure Pi auth with \pi auth` or set provider env vars` — no Pi available, handle locally
If no [pi-models] notification arrived, call pi_list_models before delegating; if that also fails, handle the task locally.
Always use the models listed in the notification. Do not assume availability of unlisted models.
When to Delegate
Delegate when ALL of these are true:
- Task is independent of current conversation context
- Task is mechanical, repetitive, or parallelizable
- A cheaper or more capable model is better suited
- Subtask runtime is likely > 30s (below this, Pi startup overhead isn't worth it)
Do NOT delegate when:
- Task requires reasoning about this specific conversation
- Task needs Claude's own tools (Bash, Edit, Write, Read, etc.)
- Task is trivially short (< 30s estimated runtime)
Tool Reference
| Tool | Purpose |
|---|
pi_list_models | Refresh available models |
pi_run_task | Run task and wait for result (blocking) |
pi_spawn_agent | Spawn agent, returns session_id immediately |
pi_steer_agent | Send mid-task steering message (delivered after current turn) |
pi_followup_agent | Queue non-interruptive message (delivered after agent finishes) |
pi_poll_agent | Check status and partial output |
pi_get_result | Wait for spawned agent to finish |
pi_terminate_agent | Abort a running agent |
Message Delivery
steer: Interrupt-style. Sent to running agent, delivered after the current assistant turn finishes its tool calls. Use for corrections, pivots, or priority changes mid-task.followUp: Non-interruptive. Queued until the agent finishes all work. Use when you do not want to disturb the agent at all.
When using pi_run_task or pi_spawn_agent, pass followUp: true to queue the task as a follow-up rather than an immediate prompt.
Parallel Pattern (primary)
1. pi_spawn_agent × N → get N session_ids
2. pi_poll_agent loop → check progress, steer if going off-track
3. pi_get_result × N → collect final outputs
4. synthesize → combine results in this session
Cap parallel spawns at 6. Beyond that, provider rate limits and context overhead from tracking session IDs and partial outputs outweigh the parallelism gains. For larger batches, spawn in waves of 6, collect results, then spawn the next wave.
Use pi_run_task only for single-task, time-bounded work where you need the result before continuing.
Steering Rule
Poll running agents for long tasks. If output is going off-track, call pi_steer_agent immediately with a correction message. If steering is insufficient, call pi_terminate_agent and respawn with a more precise task description.
