Pi Delegate

Use Pi as a separate non-interactive subagent when you want fresh context, a different model, or isolated task execution.

Use this skill when

• you want to delegate a bounded task to Pi
• you want a different model for the task
• you want an independent second pass or critique
• you want to isolate noisy work from the current conversation

Preset agents

Preset agent profiles live in agents/ relative to this skill. Read the agent file and pass its content via --append-system-prompt.

Using a preset agent

1. Read the agent file (e.g. agents/oracle.md) to get the system prompt.
2. Pass it via --append-system-prompt "$(cat agents/oracle.md)".
3. Set --model per the table above.

cd "/path/to/project" && pi --offline --no-prompt-templates --no-themes --append-system-prompt "$(cat {skill_dir}/agents/oracle.md)" --model {model} -p "Your task" 2>&1

Ad-hoc delegation (no preset) still works — just omit --append-system-prompt.

Command rules

• Change to the target working directory first (quote paths with spaces).
• Default to --offline --no-prompt-templates --no-themes for reproducible, low-noise runs.
• Choose a model with: --model {model} when model choice matters.
• Use pi --help if exact flags are unclear.

Fresh run vs continuation

• Fresh run (default): Start a new isolated session. Use this for independent delegation.
• Continuation (-c): Resume the most recent delegated session. Only use when intentionally continuing the same thread — e.g., refining a previous result or adding follow-up instructions to the same task.

Pattern (ad-hoc):

cd "/path/to/project" && pi --offline --no-prompt-templates --no-themes [--model {model}] [-c] -p "Your task" 2>&1

Model selection

Discover available models dynamically — do not rely on memorized model IDs:

pi --list-models [search]

Without [search], lists all available models. With a search term, filters by keyword.

Examples: pi --list-models, pi --list-models gpt, pi --list-models claude, pi --list-models gemini.

Selection guide

Pick a model by matching the task to the right family and tier.

When to pick what

• Complex reasoning, planning, critique — pick the best tier (opus, pro, or highest codex).
• Coding tasks — prefer GPT codex variants or Claude opus/sonnet.
• General purpose / balanced — Claude sonnet or GPT without codex.
• Fast, cheap, high-volume — Claude haiku or Gemini flash.
• Vision / image understanding — Gemini flash is good enough and cost-effective; prefer it over heavier models.

Execution workflow

1. Run Pi via bash and capture stdout+stderr (always append 2>&1).
2. Read the output — treat it as input for your judgment, not automatic truth.
3. Summarize findings back into the main task context.
4. Decide whether to act on, discard, or refine the delegated result.

Error handling

If Pi fails or returns unexpected results:

1. Verify the working directory exists and is correct.
2. Run pi --list-models to confirm the model ID is valid.
3. Retry without --model to use the default model.
4. Run pi --help to check for flag changes.

Examples

# Oracle: architecture review (preset agent)
cd "/path/to/project" && pi --offline --no-prompt-templates --no-themes --append-system-prompt "$(cat {skill_dir}/agents/oracle.md)" --model {opus-model} -p "Review this architecture and recommend improvements" 2>&1

# Reviewer: code review (preset agent)
cd "/path/to/project" && pi --offline --no-prompt-templates --no-themes --append-system-prompt "$(cat {skill_dir}/agents/reviewer.md)" --model {opus-model} -p "Review the changes in src/auth/ for security issues" 2>&1

# Worker: general task (preset agent, full tools)
cd "/path/to/project" && pi --offline --no-prompt-templates --no-themes --append-system-prompt "$(cat {skill_dir}/agents/worker.md)" --model {sonnet-model} -p "Refactor the logger module to use structured logging" 2>&1

# Ad-hoc delegation (no preset)
cd "/path/to/project" && pi --offline --no-prompt-templates --no-themes --model {sonnet-model} -p "Think through this decision and recommend the best option" 2>&1

# Continue a previous delegated session
cd "/path/to/project" && pi --offline --no-prompt-templates --no-themes -c -p "Refine the recommendation from the previous run" 2>&1

Prompt guidance

Keep prompts direct. Ask Pi for the output you want back, such as:

• findings
• risks
• options
• recommendation
• next actions