# Pi Delegator > Delegate approved coding tasks to Pi subprocesses with free opencode defaults, model setup, live progress, and metrics. Don't use for direct edits, CI, or non-Pi agents. - Skill: `luongnv89/pi-delegator` (Agent Skill, multi-file: 6 files) - Install (CLI): `npx skillmds@latest add luongnv89/pi-delegator` - Raw SKILL.md: https://api.skillmd.com/api/skills/luongnv89/pi-delegator/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - License: MIT - Author: luongnv89 (https://skillmd.com/u/luongnv89) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/luongnv89/pi-delegator --- # Pi Delegator Use this skill when another AI agent should delegate a clearly scoped task to a separate Pi instance, monitor Pi while it works, and report exact session metrics. The main agent stays the orchestrator: it captures intent, gets user approval, selects a model, runs Pi, and summarizes the result. ## Repo Sync Before Edits (mandatory) If the delegated Pi task may modify a git repository, sync the target repo before starting Pi so the delegated work begins from current code: ```bash branch="$(git rev-parse --abbrev-ref HEAD)" git fetch origin git pull --rebase origin "$branch" ``` If the working tree is dirty, stash first, sync, then pop. If `origin` is missing or conflicts occur, stop and ask the user before continuing. ## Safety contract - Never start Pi until the user approves the exact run preview. - Prefer free `opencode-cli` models whenever that provider is available. - Do not hide that a non-free model will be used; ask for explicit approval. - Do not invent token, cost, or duration metrics. Report only collected values. - Keep Pi's task prompt clear and bounded; Pi should know what to do, where to work, what tools are allowed, and what output is expected. ## Prerequisites Before any delegation, verify: ```bash which pi python3 --version ``` If either command fails, stop and tell the user what to install. Resolve the bundled helper relative to this skill directory, then use it for model discovery, config persistence, execution, event monitoring, and metrics collection: ```bash helper="/scripts/pi_delegate.py" ``` ## Step 1 — Check models and configure default Run model discovery first on every skill invocation: ```bash python3 "$helper" models --prefer-free ``` The helper reads Pi's available models and highlights free `opencode-cli` models. Configuration is stored in: ```text ~/.pi/agent/skills/pi-delegator/config.json ``` If no config exists, or the configured model is no longer available: 1. Show the model list or the helper's recommended free default. 2. Ask the user to select a default model and thinking level. 3. Save it with: ```bash python3 "$helper" configure \ --model "provider/model" \ --thinking "low" ``` Default policy: if `opencode-cli` is available, recommend and use an `opencode-cli` model unless the user explicitly chooses another provider. ## Step 2 — Capture clear input Build a delegation brief before asking for approval: - Task: the exact work Pi should perform. - Target cwd: absolute path where Pi will run. - Permissions: read-only, edit files, run tests, install deps, or other limits. - Tools: allowed Pi tools, such as `read,bash,edit,write` or read-only tools. - Constraints: files to avoid, coding standards, time limits, expected tests. - Expected output: summary only, changed files, patch, report path, etc. - Complexity: `simple`, `medium`, or `complex`. If any field is unclear, ask a concise clarifying question before continuing. ## Step 3 — Select model and thinking Read `references/model-selection.md` when choosing a model. In short: - Simple tasks: free `opencode-cli` if available, thinking `off` or `minimal`. - Medium tasks: free capable model if available, thinking `low` or `medium`. - Complex/risky tasks: strongest available free model first; if a paid model is recommended, ask the user to approve the paid model explicitly. Respect user overrides. If the run will use a non-free provider while `opencode-cli` is available, include that warning in the approval preview. ## Step 4 — Approval gate Show this preview and wait for explicit approval: ```text ◆ Pi Delegation Preview ┄┄┄┄┄┄┄┄┄┄┄┄┄ Task: Cwd: Model: Thinking: Tools: Permissions: Complexity: Run Pi with this task? [y/N] ``` Default to **No**. If the user declines, stop without launching Pi. ## Step 5 — Run and monitor Pi After approval, write the delegation prompt to a temporary file and run: ```bash python3 "$helper" run \ --approved \ --task-file /tmp/pi-task.md \ --cwd "" \ --model "" \ --thinking "" \ --tools "read,bash,edit,write" \ --approve-project \ --session-name "pi-delegated-task" ``` The helper uses Pi RPC mode, streams progress events, and requests final session stats. Read `references/event-monitoring.md` for the event-to-progress mapping. Use `--verbose` only when the user asks for raw streaming detail. ## Step 6 — Report result and metrics Return a compact report: ```text ◆ Pi Delegation Complete ┄┄┄┄┄┄┄┄┄┄┄┄┄ Result: DONE | FAILED | ABORTED Duration: Model: Thinking: Tokens: input , output , cache read , cache write Cost: Tool calls: Session: Summary: ``` If Pi changed files, list them from `git status --short` after the run. Do not claim tests passed unless Pi or the main agent actually ran them. ## Error handling - Missing `pi`: ask the user to install Pi and stop. - No models available: ask the user to authenticate Pi or configure providers. - Configured model unavailable: rerun model selection and update config. - User declines approval: stop cleanly. - Pi process fails: show stderr, partial progress, and any collected metrics. - Metrics unavailable: write `not reported` instead of guessing. ## Step Completion Reports After each major phase, print a compact status block: ```text ◆ ([step N of 6]) ┄┄┄┄┄┄┄┄┄┄┄ Models checked: ✓ pass Free default: ✓ pass (opencode-cli available) User approval: ✓ approved Result: PASS ```