pi-dev
/pi-dev
Use when dispatching the pi coding agent for a sub-task — code review, analysis, edits, or multi-agent orchestration. Triggers on "use pi", "run pi", or "pi <model>" (codex, terra, opus, sonnet, gemini, haiku, grok).
Assessment and security
- Files in this package
- 13
- Scripts
- 1
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 1 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/pi-watch/pi-watch.mjs
What it does and when to use it
Use when dispatching the pi coding agent for a sub-task — code review, analysis, edits, or multi-agent orchestration. Triggers on "use pi", "run pi", or "pi <model>" (codex, terra, opus, sonnet, gemini, haiku, grok).
Triggers from the description
Original author description
Use when dispatching the pi coding agent for a sub-task — code review, analysis, edits, or multi-agent orchestration. Triggers on "use pi", "run pi", or "pi <model>" (codex, terra, opus, sonnet, gemini, haiku, grok).
How it works
- TL;DR — call pi-watch with an alias
- Validate before dispatching
- Aliases
- Common flags
- Disambiguate before dispatching
- Setup (one-time per workstation)
- Escape hatches
- Don't
SKILL.md preview
---
name: pi-dev
description: Use when dispatching the pi coding agent for a sub-task — code review, analysis, edits, or multi-agent orchestration. Triggers on "use pi", "run pi", or "pi <model>" (codex, terra, opus, sonnet, gemini, haiku, grok).
---
# pi-dev
## TL;DR — call `pi-watch` with an alias
```bash
pi-watch --alias codex "Explain the auth flow in src/auth.ts"
```
`pi-watch` is the shipped wrapper at `scripts/pi-watch/`. It picks the first authed model from the alias's preference ladder, runs pi in-process via the SDK (no DefaultResourceLoader cwd scan), and splits the stream:
- **stdout** = assistant text only — capturable via `result="$(pi-watch ...)"`
- **stderr** = `▶ resolved <provider>/<model>:<thinking>` header, `⚙ tool args` progress, `✔ done`
That's the whole interface. Don't construct `--provider`/`--model`/`--thinking` triples by hand or invoke the `pi` binary directly unless one of the [escape hatches](#escape-hatches) below applies.
## Validate before dispatching
An alias only works if a model in its ladder is authed on *this* machine. Don't assume — preflight with `--check`, which resolves the alias against `pi --list-models` **without** running a prompt (or spending tokens):
```bash
pi-watch --check codex && pi-watch --alias codex "<prompt>" # dispatch only if codex resolves
pi-watch --check # ✓/✗ report for every alias
```
`pi-watch --check <alias>` exits **0** when the alias resolves to an authed/shipping model and **non-zero** otherwise — so gate real dispatches on it (`--check … && pi-watch …`) to never fire a doomed run. With no alias it checks all of them and prints which are ready. `--list-aliases` shows the *static* ladders; `--check` tells you which actually work right now.
The ✓/✗ report prints to **stderr** (like pi-watch's other progress output) and the gate keys off the **exit code** — so wrapping the whole gate in a capture (`result="$(pi-watch --check codex && pi-watch --alias codex '…')"`) keeps `result` to the assistant text only.
| Exit | Meaning |
|---|---|
| 0 | Every checked alias resolves to an authed model |
| 2 | Named alias is unknown |
| 4 | Can't query `pi` (binary missing — see [Setup](#setup-one-time-per-workstation)) |
| 5 | At least one checked alias won't run — no authed/shipping model (run `pi /login`), or SDK skew: pi lists the model but the bundled pi-ai catalog lacks it (run `pnpm update` in the pi-watch dir) |
## Aliases
| Alias | Default thinking | Routes to |
|---|---|---|
| `codex` (default coding) | `medium` | gpt-6.1-sol → 6-sol → 5.6-sol → 5.5 (across `openai-codex`/`openai`/`github-copilot`) |
| `codex-max` | `max` | gpt-6.1-sol → 6-sol → 5.6-sol, at `max` effort |
| `codex-mini` | `medium` | gpt-6-luna → 5.6-luna |
| `codex-spark` | `high` | gpt-5.3-codex-spark |
| `terra` (balanced) | `high` | gpt-5.6-terra → 5.4 |
| `sonnet` | `high` | claude-sonnet-5-5 → 5 → 4-6 (anthropic + copilot) |
| `opus` | `high` | claude-opus-5-5 → 5 → 4-8 → 4-7 |
| `haiku` | `medium` | claude-haiku-5-5 → 4-5 |
| `fable` (opt-in) | `high` | claude-fable-5-1 → 5 |
| `gemini` | `high` | gemini-3.1-pro-preview |
| `flash` | `medium` | gemini-flash-latest → 3.8-flash → 3-flash-preview |
| `grok` | `medium` | grok-4.7 → 4.6 (xai, then copilot) |
GPT-6 ships three tiers: **Sol** (flagship, $2/$10) backs `codex` and `codex-max`, **Luna** (fastest and cheapest, $0.10/$0.50) backs `codex-mini`, and **Astra** ($10/$50) is excluded like a pro tier. GPT-6 has no Terra tier, so `terra` stays on GPT-5.6 Terra ($2/$12), which now costs more than GPT-6 Sol. Claude **Fable** ($10/$50, 2.5× Opus 5.5) gets the opt-in `fable` alias and never appears in the `opus` ladder.
Aliases auto-upgrade as new models ship — newest entries at the top of each ladder are speculative and skipped if not yet in `pi --list-models`. **OpenAI pro / deep-research tiers are deliberately excluded** from alias ladders: `gpt-5-pro`, `gpt-5.x-pro`, `o1-pro`, `o3-pro`, `o3-deep-research`, `o4-mini-deep-research` (~10–30× cost, multi-minute latency), and `gpt-6-astra` (5× GPT-6 Sol). GPT-5.6's **Sol Pro** and **Ultra mode** are the same lever — they're request-time params (`reasoning.mode`), not separate model IDs, so there's no alias for them. Dispatch pro-tier only on explicit user request via `--provider`/`--model`. *(Note: `gemini-*-pro-preview` is Google's standard tier, not a pro tier — it routes via the `gemini` alias.)*
To see the full ladders: `pi-watch --list-aliases`.
## Common flags
```bash
pi-watch --alias <alias> "<prompt>" # default tools: read,bash
pi-watch --alias <alias> --tools read "<prompt>" # restrict tools
pi-watch --alias <alias> --no-tools "<prompt>" # LLM only — review/analysis
pi-watch --alias <alias> --thinking medium "<prompt>" # override default thinking
pi-watch --alias <alias> --cwd <dir> "<prompt>" # run with <dir> as cwd (must exist; else exit 2)
pi-watch --alias <alias> --require-trailer STATUS "<prompt>" # exit 6 if no STATUS: <value> trailer in last 3 output lines
pi-watch --check <alias> # preflight one alias (exit 0 = authed model resolves)
pi-watch --check # preflight all aliases — ✓/✗ report
```
Thinking levels: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. `max` is the opt-in ceiling above `xhigh`, native on GPT-5.6 Sol and adaptive Claude models (it's the `codex-max` default); other models silently clamp it — and any unsupported level — down.
### Tools
Pi's built-in tool names (pass to `--tools`, comma-separated):
| Tool | Capability | Off by default? |
|---|---|---|
| `read` | Read file contents | no — pi-watch enables |
| `bash` | Execute bash commands | no — pi-watch enables |
| `edit` | Edit files with find/replace | yes |
| `write` | Write files (create/overwrite) | yes |
| `grep` | Search file contents (read-only) | yes |
| `find` | Find files by glob pattern (read-only) | yes |
| `ls` | List directory contents (read-only) | yes |
Pick by what the worker needs to *do*, not what would be "complete":
- **Read-only review / analysis / summarization** → `--tools read,grep,find,ls` (no shell, no writes).
- **Pure LLM judgment, no filesystem** → `--no-tools` (e.g., reviewer worker scoring a diff that's already in the prompt).
- **Code edits** → `--tools read,grep,find,edit,write` (omit `bash` if you don't want shell execution; add it back when running tests is part of the worker's job).
- **Default coding worker** (build, test, edit, commit) → omit `--tools` (uses `read,bash`) and add `edit,write` if it needs to mutate files: `--tools read,bash,edit,write`.
Tool grants are an allowlist; whatever you don't list is unavailable to the model. Pi has **no built-in sandbox** — `bash`, `edit`, and `write` give the worker full user-level filesystem access. Run mutating workers in a worktree or container if isolation matters.
## Disambiguate before dispatching
Stop and ask the user (multiple-choice via AskUserQuestion) when:
- They say "best" / "most capable" — never silently jump to a `*-pro` model.
- They name a generic family with no alias-table match.
- They request a model that isn't in `pi --list-models <id>` output.
- The choice is between an alias and an explicit pin.
## Setup (one-time per workstation)
Install the launcher **as a copy** on your PATH. The launcher resolves the
*currently installed* quirk version on every run (from `installed_plugins.json`),
so it keeps tracking `claude plugin update` — unlike a symlink into a versioned
cache dir, which freezes at install-time and dangles when that version is pruned.
```bash
# Resolve the install dir directly — there is no `claude plugin path` command.
QUIRK="$(node -e 'const fs=require("fs"),os=require("os"),p=require("path");const P=JSON.parse(fs.readFileSync(p.join(os.homedir(),".claude/plugins/installed_plugins.json"),"utf8")).plugins;const k=P["quirk@quirk-dev"]?"quirk@quirk-dev":Object.keys(P).find(x=>x.startsWith("quirk@"));process.stdout.write(k?P[k][0].installPath:"")')"
install -m755 "$QUIRK/skills/pi-dev/scripts/pi-watch/pi-watch" ~/.local/bin/pi-watch # or any PATH dir
```
Verify: `pi --version` → expect ≥ 0.65.1, and `node --version` → expect ≥ 22.19 (the pi SDK's floor). `pi /login` for any subscription provider you want (Claude, ChatGPT, Copilot). Then `pi-watch --check` to confirm which aliases resolve to an authed model — the first run also auto-installs the current version's Node deps if they're missing or outdated.
**Updating:** `claude plugin update quirk` is enough — `pi-watch` auto-follows. Run `pi-watch --where` to see which version/dir it resolves to (and whether that copy has the current alias ladder). Re-run the `install` line above only if the launcher script itself changes (rare); mjs/alias updates are picked up automatically.
*(Dev checkout: point the launcher at a working tree instead — `ln -sf "$(pwd)/pi-watch" ~/.local/bin/pi-watch` from `skills/pi-dev/scripts/pi-watch`, or set `PI_WATCH_DIR`. A launcher whose own dir holds the code and sits outside the plugin cache runs that tree, so local edits are live.)*
## Escape hatches
Use the raw `pi` binary or the SDK directly only for these cases:
| Need | Use | Reference |
|---|---|---|
| One-off script, just want final text, no streaming | `pi -p "..."` | `reference/print-mode.md` |
| Tooling that consumes JSONL events | `pi --mode json` | `reference/json-mode.md` |
| Non-Node host (Python/Go/Rust) needing bidirectional control | `pi --mode rpc --no-session` | `reference/rpc-mode.md` |
| Embedding pi in a Node.js app with type safety | `@earendil-works/pi-coding-agent` SDK | `reference/sdk-mode.md` |
| Multi-agent orchestrator (decompose → dispatch → review → integrate) | RPC subprocess workers + SDK orchestrator | `reference/orchestration.md` |
| Need a model not covered by an alias, or pinning an exact version | `pi-watch --provider <p> --model <m> [--thinking <l>]` | `reference/models.md` (full catalog, separator quirks, fallback algorithm) |
When invoking the raw `pi` binary in scripts always pass `--no-session --offline` and wrap with `gtimeout` (macOS) / `timeout` (Linux). Pi has no `--cd` flag (caller must `cd` first), no built-in sandbox, no built-in timeout. Full headless dispatch recipe: `reference/print-mode.md#canonical-headless-recipe`.
## Don't
- **Don't** construct `--provider`/`--model`/`--thinking` triples manually when an alias would work — you'll miss fallback and lose auto-upgrade.
- **Don't** modify `~/.pi/agent/auth.json` or `~/.pi/agent/AGENTS.md`.
- **Don't** dispatch parallel `git worktree add` calls when running pi workers — they race on `.git/config.lock`. Serialize creation; only the workers run parallel.
- **Don't** run multiple workers in the same working directory — pi has no sandbox; they will overwrite each other.
- **Don't** silently fall back across providers when running raw `pi`. Always log the resolved triple (`pi-watch` does this automatically via the `▶ resolved` line).
- **Don't** use Node's `readline` to parse RPC stdout — see `reference/rpc-mode.md` for the U+2028/U+2029 framing trap.
Files in this package (13)
- SKILL.md 11 KB
- reference/json-mode.md 3 KB
- reference/models.md 21 KB
- reference/orchestration.md 6 KB
- reference/print-mode.md 5 KB
- reference/rpc-mode.md 5 KB
- reference/sdk-mode.md 5 KB
- scripts/pi-watch/.gitignore 1 KB
- scripts/pi-watch/README.md 7 KB
- scripts/pi-watch/package.json 1 KB
- scripts/pi-watch/pi-watch 5 KB
- scripts/pi-watch/pi-watch.mjs 21 KB
- scripts/pi-watch/pnpm-workspace.yaml 1 KB
Versions
The database has no other skills named pi-dev.
Database snapshot: 13.11.2026 · package version d74ea046ee44 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90Codex-opus-4-6-prompting
Comprehensive prompt engineering reference for Codex Opus 4.6. Use this skill whenever you are writing, reviewing, or optimizing prompts for Codex Opus 4.6 (or Sonnet 4.6 / Haiku 4.5). Covers foundational clarity principles, output formatting control, tool use, adaptive… - 90model-roles
Use for any coding task. Opus is the orchestrator: it plans, delegates, and supervises. Sonnet writes and reviews code, Haiku does lookups and mechanical edits, and no subagent runs on Opus. The model-policy mod enforces this, so read it before you spawn an agent, edit a code… - 90tasktide
Orchestrates development tasks with Claude Code subagents and routes work between Haiku, Sonnet and Opus. Use to plan architecture, implement features, refactor, debug, review and test code. - 90model-routing
Pick the right model per call, not per project — route Opus/Sonnet/Haiku, GPT-5/4o/mini, Gemini Pro/Flash by task, and cut cost without losing quality. Use when the user is choosing model tiers, building a router, or debating Opus-only vs mixed-tier deployments and mentions… - 95claude-opus-4-5-migration
Migrate prompts and code from Claude Sonnet 4.0, Sonnet 4.5, or Opus 4.1 to Opus 4.5. Use when the user wants to update their codebase, prompts, or API calls to use Opus 4.5. Handles model string updates and prompt adjustments for known Opus 4.5 behavioral differences. Does NOT migrate Haiku 4.5. - 100orchestration
Use when driving a large, multi-part task end to end with multiple models — planning at a high tier, decomposing into a task ledger, and delegating each piece to the right specialist at the right model (plan with Opus/Fable, implement with Sonnet, mechanical work with Haiku).…