Add community skills, agents, system prompts from 22+ sources

Community Skills (32): - jat: jat-start, jat-verify, jat-complete - pi-mono: codex-cli, codex-5.3-prompting, interactive-shell - picoclaw: github, weather, tmux, summarize, skill-creator - dyad: 18 skills (swarm-to-plan, multi-pr-review, fix-issue, lint, etc.) - dexter: dcf valuation skill Agents (23): - pi-mono subagents: scout, planner, reviewer, worker - toad: 19 agent configs (Claude, Codex, Gemini, Copilot, OpenCode, etc.) System Prompts (91): - Anthropic: 15 Claude prompts (opus-4.6, code, cowork, etc.) - OpenAI: 49 GPT prompts (gpt-5 series, o3, o4-mini, tools) - Google: 13 Gemini prompts (2.5-pro, 3-pro, workspace, cli) - xAI: 5 Grok prompts - Other: 9 misc prompts (Notion, Raycast, Warp, Kagi, etc.) Hooks (9): - JAT hooks for session management, signal tracking, activity logging Prompts (6): - pi-mono templates for PR review, issue analysis, changelog audit Sources analyzed: jat, ralph-desktop, toad, pi-mono, cmux, pi-interactive-shell, craft-agents-oss, dexter, picoclaw, dyad, system_prompts_leaks, Prometheus, zed, clawdbot, OS-Copilot, and more
2026-02-13 10:58:17 +00:00
parent 5889d3428b
commit b60638f0a3
186 changed files with 38926 additions and 325 deletions
--- a/skills/community/pi-mono/codex-5.3-prompting/SKILL.md
+++ b/skills/community/pi-mono/codex-5.3-prompting/SKILL.md
@@ -0,0 +1,149 @@
+---
+name: codex-5.3-prompting
+description: How to write system prompts and instructions for GPT-5.3-Codex. Use when constructing or tuning prompts targeting Codex 5.3.
+---
+
+# GPT-5.3-Codex Prompting Guide
+
+GPT-5.3-Codex is fast, capable, and eager. It moves quickly and will skip reading, over-refactor, and drift scope if prompts aren't tight. Explicit constraints matter more than with GPT-5.2-Codex. Include the following blocks as needed when constructing system prompts.
+
+## Output shape
+
+Always include. Controls verbosity and response structure.
+
+```
+<output_verbosity_spec>
+- Default: 3-6 sentences or <=5 bullets for typical answers.
+- Simple yes/no questions: <=2 sentences.
+- Complex multi-step or multi-file tasks:
+  - 1 short overview paragraph
+  - then <=5 bullets tagged: What changed, Where, Risks, Next steps, Open questions.
+- Avoid long narrative paragraphs; prefer compact bullets and short sections.
+- Do not rephrase the user's request unless it changes semantics.
+</output_verbosity_spec>
+```
+
+## Scope constraints
+
+Always include. GPT-5.3-Codex will add features, refactor adjacent code, and invent UI elements if you don't fence it in.
+
+```
+<design_and_scope_constraints>
+- Explore any existing design systems and understand them deeply.
+- Implement EXACTLY and ONLY what the user requests.
+- No extra features, no added components, no UX embellishments.
+- Style aligned to the design system at hand.
+- Do NOT invent colors, shadows, tokens, animations, or new UI elements unless requested or necessary.
+- If any instruction is ambiguous, choose the simplest valid interpretation.
+</design_and_scope_constraints>
+```
+
+## Context loading
+
+Always include. GPT-5.3-Codex skips reading and starts writing if you don't force it.
+
+```
+<context_loading>
+- Read ALL files that will be modified -- in full, not just the sections mentioned in the task.
+- Also read key files they import from or that depend on them.
+- Absorb surrounding patterns, naming conventions, error handling style, and architecture before writing any code.
+- Do not ask clarifying questions about things that are answerable by reading the codebase.
+</context_loading>
+```
+
+## Plan-first mode
+
+Include for multi-file work, large refactors, or any task with ordering dependencies.
+
+```
+<plan_first>
+- Before writing any code, produce a brief implementation plan:
+  - Files to create vs. modify
+  - Implementation order and prerequisites
+  - Key design decisions and edge cases
+  - Acceptance criteria for "done"
+- Get the plan right first. Then implement step by step following the plan.
+- If the plan is provided externally, follow it faithfully -- the job is execution, not second-guessing the design.
+</plan_first>
+```
+
+## Long-context handling
+
+Include when inputs exceed ~10k tokens (multi-chapter docs, long threads, multiple PDFs).
+
+```
+<long_context_handling>
+- For inputs longer than ~10k tokens:
+  - First, produce a short internal outline of the key sections relevant to the task.
+  - Re-state the constraints explicitly before answering.
+  - Anchor claims to sections ("In the 'Data Retention' section...") rather than speaking generically.
+- If the answer depends on fine details (dates, thresholds, clauses), quote or paraphrase them.
+</long_context_handling>
+```
+
+## Uncertainty and ambiguity
+
+Include when the task involves underspecified requirements or hallucination-prone domains.
+
+```
+<uncertainty_and_ambiguity>
+- If the question is ambiguous or underspecified:
+  - Ask up to 1-3 precise clarifying questions, OR
+  - Present 2-3 plausible interpretations with clearly labeled assumptions.
+- Never fabricate exact figures, line numbers, or external references when uncertain.
+- When unsure, prefer "Based on the provided context..." over absolute claims.
+</uncertainty_and_ambiguity>
+```
+
+## User updates
+
+Include for agentic / long-running tasks.
+
+```
+<user_updates_spec>
+- Send brief updates (1-2 sentences) only when:
+  - You start a new major phase of work, or
+  - You discover something that changes the plan.
+- Avoid narrating routine tool calls ("reading file...", "running tests...").
+- Each update must include at least one concrete outcome ("Found X", "Confirmed Y", "Updated Z").
+- Do not expand the task beyond what was asked; if you notice new work, call it out as optional.
+</user_updates_spec>
+```
+
+## Tool usage
+
+Include when the prompt involves tool-calling agents.
+
+```
+<tool_usage_rules>
+- Prefer tools over internal knowledge whenever:
+  - You need fresh or user-specific data (tickets, orders, configs, logs).
+  - You reference specific IDs, URLs, or document titles.
+- Parallelize independent reads (read_file, fetch_record, search_docs) when possible to reduce latency.
+- After any write/update tool call, briefly restate:
+  - What changed
+  - Where (ID or path)
+  - Any follow-up validation performed
+</tool_usage_rules>
+```
+
+## Reasoning effort
+
+Set `model_reasoning_effort` via Codex CLI: `-c model_reasoning_effort="high"`
+
+| Task type | Effort |
+|---|---|
+| Simple code generation, formatting | `low` or `medium` |
+| Standard implementation from clear specs | `high` |
+| Complex refactors, plan review, architecture | `xhigh` |
+| Code review (thorough) | `high` or `xhigh` |
+
+## Quick reference
+
+- **Force reading first.** "Read all necessary files before you ask any dumb question."
+- **Use plan mode.** Draft the full task with acceptance criteria before implementing.
+- **Steer aggressively mid-task.** GPT-5.3-Codex handles redirects without losing context. Be direct: "Stop. Fix the actual cause." / "Simplest valid implementation only."
+- **Constrain scope hard.** GPT-5.3-Codex will refactor aggressively if you don't fence it in.
+- **Watch context burn.** Faster model = faster context consumption. Start fresh at ~40%.
+- **Use domain jargon.** "Golden-path," "no fallbacks," "domain split" get faster responses.
+- **Download libraries locally.** Tell it to read them for better context than relying on training data.
--- a/skills/community/pi-mono/codex-cli/SKILL.md
+++ b/skills/community/pi-mono/codex-cli/SKILL.md
@@ -0,0 +1,88 @@
+---
+name: codex-cli
+description: OpenAI Codex CLI reference. Use when running codex in interactive_shell overlay or when user asks about codex CLI options.
+---
+
+# Codex CLI (OpenAI)
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `codex` | Start interactive TUI |
+| `codex "prompt"` | TUI with initial prompt |
+| `codex exec "prompt"` | Non-interactive (headless), streams to stdout. Supports `--output-schema <file>` for structured JSON output |
+| `codex e "prompt"` | Shorthand for exec |
+| `codex login` | Authenticate (OAuth, device auth, or API key) |
+| `codex login status` | Show auth mode |
+| `codex logout` | Remove credentials |
+| `codex mcp` | Manage MCP servers |
+| `codex completion` | Generate shell completions |
+
+## Key Flags
+
+| Flag | Description |
+|------|-------------|
+| `-m, --model <model>` | Switch model (default: `gpt-5.3-codex`) |
+| `-c <key=value>` | Override config.toml values (dotted paths, parsed as TOML) |
+| `-p, --profile <name>` | Use config profile from config.toml |
+| `-s, --sandbox <mode>` | Sandbox policy: `read-only`, `workspace-write`, `danger-full-access` |
+| `-a, --ask-for-approval <policy>` | `untrusted`, `on-failure`, `on-request`, `never` |
+| `--full-auto` | Alias for `-a on-request --sandbox workspace-write` |
+| `--search` | Enable live web search tool |
+| `-i, --image <file>` | Attach image(s) to initial prompt |
+| `--add-dir <dir>` | Additional writable directories |
+| `-C, --cd <dir>` | Set working root directory |
+| `--no-alt-screen` | Inline mode (preserve terminal scrollback) |
+
+## Sandbox Modes
+
+- `read-only` - Can only read files
+- `workspace-write` - Can write to workspace
+- `danger-full-access` - Full system access (use with caution)
+
+## Features
+
+- **Image inputs** - Accepts screenshots and design specs
+- **Code review** - Reviews changes before commit
+- **Web search** - Can search for information
+- **MCP integration** - Third-party tool support
+
+## Config
+
+Config file: `~/.codex/config.toml`
+
+Key config values (set in file or override with `-c`):
+- `model` -- model name (e.g., `gpt-5.3-codex`)
+- `model_reasoning_effort` -- `low`, `medium`, `high`, `xhigh`
+- `model_reasoning_summary` -- `detailed`, `concise`, `none`
+- `model_verbosity` -- `low`, `medium`, `high`
+- `profile` -- default profile name
+- `tool_output_token_limit` -- max tokens per tool output
+
+Define profiles for different projects/modes with `[profiles.<name>]` sections. Override at runtime with `-p <name>` or `-c model_reasoning_effort="high"`.
+
+## In interactive_shell
+
+Do NOT pass `-s` / `--sandbox` flags. Codex's `read-only` and `workspace-write` sandbox modes apply OS-level filesystem restrictions that break basic shell operations inside the PTY -- zsh can't even create temp files for here-documents, so every write attempt fails with "operation not permitted." The interactive shell overlay already provides supervision (user watches in real-time, Ctrl+Q to kill, Ctrl+T to transfer output), making Codex's sandbox redundant.
+
+Use explicit flags to control model and behavior per-run.
+
+For delegated fire-and-forget runs, prefer `mode: "dispatch"` so the agent is notified automatically when Codex completes.
+
+```typescript
+// Delegated run with completion notification (recommended default)
+interactive_shell({
+  command: 'codex -m gpt-5.3-codex -a never "Review this codebase for security issues"',
+  mode: "dispatch"
+})
+
+// Override reasoning effort for a single delegated run
+interactive_shell({
+  command: 'codex -m gpt-5.3-codex -c model_reasoning_effort="xhigh" -a never "Complex refactor task"',
+  mode: "dispatch"
+})
+
+// Headless - use bash instead
+bash({ command: 'codex exec "summarize the repo"' })
+```
--- a/skills/community/pi-mono/interactive-shell/SKILL.md
+++ b/skills/community/pi-mono/interactive-shell/SKILL.md
@@ -0,0 +1,516 @@
+---
+name: interactive-shell
+description: Cheat sheet + workflow for launching interactive coding-agent CLIs (Claude Code, Gemini CLI, Codex CLI, Cursor CLI, and pi itself) via the interactive_shell overlay or headless dispatch. Use for TUI agents and long-running processes that need supervision, fire-and-forget delegation, or headless background execution. Regular bash commands should use the bash tool instead.
+---
+
+# Interactive Shell (Skill)
+
+Last verified: 2026-01-18
+
+## Foreground vs Background Subagents
+
+Pi has two ways to delegate work to other AI coding agents:
+
+| | Foreground Subagents | Dispatch Subagents | Background Subagents |
+|---|---|---|---|
+| **Tool** | `interactive_shell` | `interactive_shell` (dispatch) | `subagent` |
+| **Visibility** | User sees overlay | User sees overlay (or headless) | Hidden from user |
+| **Agent model** | Polls for status | Notified on completion | Full output captured |
+| **Default agent** | `pi` (others if user requests) | `pi` (others if user requests) | Pi only |
+| **User control** | Can take over anytime | Can take over anytime | No intervention |
+| **Best for** | Long tasks needing supervision | Fire-and-forget delegations | Parallel tasks, structured delegation |
+
+**Foreground subagents** run in an overlay where the user watches (and can intervene). Use `interactive_shell` with `mode: "hands-free"` to monitor while receiving periodic updates, or `mode: "dispatch"` to be notified on completion without polling.
+
+**Dispatch subagents** also use `interactive_shell` but with `mode: "dispatch"`. The agent fires the session and moves on. When the session completes, the agent is woken up via `triggerTurn` with the output in context. Add `background: true` for headless execution (no overlay).
+
+**Background subagents** run invisibly via the `subagent` tool. Pi-only, but captures full output and supports parallel execution.
+
+## When to Use Foreground Subagents
+
+Use `interactive_shell` (foreground) when:
+- The task is **long-running** and the user should see progress
+- The user might want to **intervene or guide** the agent
+- You want **hands-free monitoring** with periodic status updates
+- You need a **different agent's capabilities** (only if user specifies)
+
+Use `subagent` (background) when:
+- You need **parallel execution** of multiple tasks
+- You want **full output capture** for processing
+- The task is **quick and deterministic**
+- User doesn't need to see the work happening
+
+### Default Agent Choice
+
+**Default to `pi`** for foreground subagents unless the user explicitly requests a different agent:
+
+| User says | Agent to use |
+|-----------|--------------|
+| "Run this in hands-free" | `pi` |
+| "Delegate this task" | `pi` |
+| "Use Claude to review this" | `claude` |
+| "Have Gemini analyze this" | `gemini` |
+| "Run aider to fix this" | `aider` |
+
+Pi is the default because it's already available, has the same capabilities, and maintains consistency. Only use Claude, Gemini, Codex, or other agents when the user specifically asks for them.
+
+## Foreground Subagent Modes
+
+### Interactive (default)
+User has full control, types directly into the agent.
+```typescript
+interactive_shell({ command: 'pi' })
+```
+
+### Interactive with Initial Prompt
+Agent starts working immediately, user supervises.
+```typescript
+interactive_shell({ command: 'pi "Review this codebase for security issues"' })
+```
+
+### Dispatch (Fire-and-Forget) - NON-BLOCKING, NO POLLING
+Agent fires a session and moves on. Notified automatically on completion via `triggerTurn`.
+
+```typescript
+// Start session - returns immediately, no polling needed
+interactive_shell({
+  command: 'pi "Fix all TypeScript errors in src/"',
+  mode: "dispatch",
+  reason: "Fixing TS errors"
+})
+// Returns: { sessionId: "calm-reef", mode: "dispatch" }
+// → Do other work. When session completes, you receive notification with output.
+```
+
+Dispatch defaults `autoExitOnQuiet: true`. The agent can still query the sessionId if needed, but doesn't have to.
+
+For fire-and-forget delegated runs (including QA-style delegated checks), prefer dispatch as the default mode.
+
+#### Background Dispatch (Headless)
+No overlay opens. Multiple headless dispatches can run concurrently:
+
+```typescript
+interactive_shell({
+  command: 'pi "Fix lint errors"',
+  mode: "dispatch",
+  background: true
+})
+// → No overlay. User can /attach to watch. Agent notified on completion.
+```
+
+### Hands-Free (Foreground Subagent) - NON-BLOCKING
+Agent works autonomously, **returns immediately** with sessionId. You query for status/output and kill when done.
+
+```typescript
+// 1. Start session - returns immediately
+interactive_shell({
+  command: 'pi "Fix all TypeScript errors in src/"',
+  mode: "hands-free",
+  reason: "Fixing TS errors"
+})
+// Returns: { sessionId: "calm-reef", status: "running" }
+
+// 2. Check status and get new output
+interactive_shell({ sessionId: "calm-reef" })
+// Returns: { status: "running", output: "...", runtime: 30000 }
+
+// 3. When you see task is complete, kill session
+interactive_shell({ sessionId: "calm-reef", kill: true })
+// Returns: { status: "killed", output: "final output..." }
+```
+
+This is the primary pattern for **foreground subagents** - you delegate to pi (or another agent), query for progress, and decide when the task is done.
+
+## Hands-Free Workflow
+
+### Starting a Session
+```typescript
+const result = interactive_shell({
+  command: 'codex "Review this codebase"',
+  mode: "hands-free"
+})
+// result.details.sessionId = "calm-reef"
+// result.details.status = "running"
+```
+
+The user sees the overlay immediately. You get control back to continue working.
+
+### Querying Status
+```typescript
+interactive_shell({ sessionId: "calm-reef" })
+```
+
+Returns:
+- `status`: "running" | "user-takeover" | "exited" | "killed" | "backgrounded"
+- `output`: Last 20 lines of rendered terminal (clean, no TUI animation noise)
+- `runtime`: Time elapsed in ms
+
+**Rate limited:** Queries are limited to once every 60 seconds. If you query too soon, the tool will automatically wait until the limit expires before returning. The user is watching the overlay in real-time - you're just checking in periodically.
+
+### Ending a Session
+```typescript
+interactive_shell({ sessionId: "calm-reef", kill: true })
+```
+
+Kill when you see the task is complete in the output. Returns final status and output.
+
+### Fire-and-Forget Tasks
+
+For single-task delegations where you don't need multi-turn interaction, enable auto-exit so the session kills itself when the agent goes quiet:
+
+```typescript
+interactive_shell({
+  command: 'pi "Review this codebase for security issues. Save your findings to /tmp/security-review.md"',
+  mode: "hands-free",
+  reason: "Security review",
+  handsFree: { autoExitOnQuiet: true }
+})
+// Session auto-kills after ~5s of quiet
+// Read results from file:
+// read("/tmp/security-review.md")
+```
+
+**Instruct subagent to save results to a file** since the session closes automatically.
+
+### Multi-Turn Sessions (default)
+
+For back-and-forth interaction, leave auto-exit disabled (the default). Query status and kill manually when done:
+
+```typescript
+interactive_shell({
+  command: 'cursor-agent -f',
+  mode: "hands-free",
+  reason: "Interactive refactoring"
+})
+
+// Send follow-up prompts
+interactive_shell({ sessionId: "calm-reef", input: "Now fix the tests\n" })
+
+// Kill when done
+interactive_shell({ sessionId: "calm-reef", kill: true })
+```
+
+### Sending Input
+```typescript
+interactive_shell({ sessionId: "calm-reef", input: "/help\n" })
+interactive_shell({ sessionId: "calm-reef", inputKeys: ["ctrl+c"] })
+interactive_shell({ sessionId: "calm-reef", inputPaste: "multi\nline\ncode" })
+interactive_shell({ sessionId: "calm-reef", input: "y", inputKeys: ["enter"] })  // combine text + keys
+```
+
+### Query Output
+
+Status queries return **rendered terminal output** (what's actually on screen), not raw stream:
+- Default: 20 lines, 5KB max per query
+- No TUI animation noise (spinners, progress bars, etc.)
+- Configurable via `outputLines` (max: 200) and `outputMaxChars` (max: 50KB)
+
+```typescript
+// Get more output when reviewing a session
+interactive_shell({ sessionId: "calm-reef", outputLines: 50 })
+
+// Get even more for detailed review
+interactive_shell({ sessionId: "calm-reef", outputLines: 100, outputMaxChars: 30000 })
+```
+
+### Incremental Reading
+
+Use `incremental: true` to paginate through output without re-reading:
+
+```typescript
+// First call: get first 50 lines
+interactive_shell({ sessionId: "calm-reef", outputLines: 50, incremental: true })
+// → { output: "...", hasMore: true }
+
+// Next call: get next 50 lines (server tracks position)
+interactive_shell({ sessionId: "calm-reef", outputLines: 50, incremental: true })
+// → { output: "...", hasMore: true }
+
+// Keep calling until hasMore: false
+interactive_shell({ sessionId: "calm-reef", outputLines: 50, incremental: true })
+// → { output: "...", hasMore: false }
+```
+
+The server tracks your read position - just keep calling with `incremental: true` to get the next chunk.
+
+### Reviewing Output
+
+Query sessions to see progress. Increase limits when you need more context:
+
+```typescript
+// Default: last 20 lines
+interactive_shell({ sessionId: "calm-reef" })
+
+// Get more lines when you need more context
+interactive_shell({ sessionId: "calm-reef", outputLines: 50 })
+
+// Get even more for detailed review
+interactive_shell({ sessionId: "calm-reef", outputLines: 100, outputMaxChars: 30000 })
+```
+
+## Sending Input to Active Sessions
+
+Use the `sessionId` from updates to send input to a running hands-free session:
+
+### Basic Input
+```typescript
+// Send text
+interactive_shell({ sessionId: "shell-1", input: "/help\n" })
+
+// Send text with keys
+interactive_shell({ sessionId: "shell-1", input: "/model", inputKeys: ["enter"] })
+
+// Navigate menus
+interactive_shell({ sessionId: "shell-1", inputKeys: ["down", "down", "enter"] })
+
+// Interrupt
+interactive_shell({ sessionId: "shell-1", inputKeys: ["ctrl+c"] })
+```
+
+### Named Keys
+| Key | Description |
+|-----|-------------|
+| `up`, `down`, `left`, `right` | Arrow keys |
+| `enter`, `return` | Enter/Return |
+| `escape`, `esc` | Escape |
+| `tab`, `shift+tab` (or `btab`) | Tab / Back-tab |
+| `backspace`, `bspace` | Backspace |
+| `delete`, `del`, `dc` | Delete |
+| `insert`, `ic` | Insert |
+| `home`, `end` | Home/End |
+| `pageup`, `pgup`, `ppage` | Page Up |
+| `pagedown`, `pgdn`, `npage` | Page Down |
+| `f1`-`f12` | Function keys |
+| `kp0`-`kp9`, `kp/`, `kp*`, `kp-`, `kp+`, `kp.`, `kpenter` | Keypad keys |
+| `ctrl+c`, `ctrl+d`, `ctrl+z` | Control sequences |
+| `ctrl+a` through `ctrl+z` | All control keys |
+
+Note: `ic`/`dc`, `ppage`/`npage`, `bspace` are tmux-style aliases for compatibility.
+
+### Modifier Combinations
+Supports `ctrl+`, `alt+`, `shift+` prefixes (or shorthand `c-`, `m-`, `s-`):
+```typescript
+// Cancel
+inputKeys: ["ctrl+c"]
+
+// Alt+Tab
+inputKeys: ["alt+tab"]
+
+// Ctrl+Alt+Delete
+inputKeys: ["ctrl+alt+delete"]
+
+// Shorthand syntax
+inputKeys: ["c-c", "m-x", "s-tab"]
+```
+
+### Hex Bytes (Advanced)
+Send raw escape sequences:
+```typescript
+inputHex: ["0x1b", "0x5b", "0x41"]  // ESC[A (up arrow)
+```
+
+### Bracketed Paste
+Paste multiline text without triggering autocompletion/execution:
+```typescript
+inputPaste: "function foo() {\n  return 42;\n}"
+```
+
+### Model Selection Example
+```typescript
+// Step 1: Open model selector
+interactive_shell({ sessionId: "shell-1", input: "/model", inputKeys: ["enter"] })
+
+// Step 2: Filter and select (after ~500ms delay)
+interactive_shell({ sessionId: "shell-1", input: "sonnet", inputKeys: ["enter"] })
+
+// Or navigate with arrows:
+interactive_shell({ sessionId: "shell-1", inputKeys: ["down", "down", "down", "enter"] })
+```
+
+### Context Compaction
+```typescript
+interactive_shell({ sessionId: "shell-1", input: "/compact", inputKeys: ["enter"] })
+```
+
+### Changing Update Settings
+Adjust timing during a session:
+```typescript
+// Change max interval (fallback for on-quiet mode)
+interactive_shell({ sessionId: "calm-reef", settings: { updateInterval: 120000 } })
+
+// Change quiet threshold (how long to wait after output stops)
+interactive_shell({ sessionId: "calm-reef", settings: { quietThreshold: 3000 } })
+
+// Both at once
+interactive_shell({ sessionId: "calm-reef", settings: { updateInterval: 30000, quietThreshold: 2000 } })
+```
+
+## CLI Quick Reference
+
+| Agent | Interactive | With Prompt | Headless (bash) | Dispatch |
+|-------|-------------|-------------|-----------------|----------|
+| `claude` | `claude` | `claude "prompt"` | `claude -p "prompt"` | `mode: "dispatch"` |
+| `gemini` | `gemini` | `gemini -i "prompt"` | `gemini "prompt"` | `mode: "dispatch"` |
+| `codex` | `codex` | `codex "prompt"` | `codex exec "prompt"` | `mode: "dispatch"` |
+| `agent` | `agent` | `agent "prompt"` | `agent -p "prompt"` | `mode: "dispatch"` |
+| `pi` | `pi` | `pi "prompt"` | `pi -p "prompt"` | `mode: "dispatch"` |
+
+**Gemini model:** `gemini -m gemini-3-flash-preview -i "prompt"`
+
+## Prompt Packaging Rules
+
+The `reason` parameter is **UI-only** - it's shown in the overlay header but NOT passed to the subprocess.
+
+To give the agent an initial prompt, embed it in the `command`:
+```typescript
+// WRONG - agent starts idle, reason is just UI text
+interactive_shell({ command: 'claude', reason: 'Review the codebase' })
+
+// RIGHT - agent receives the prompt
+interactive_shell({ command: 'claude "Review the codebase"', reason: 'Code review' })
+```
+
+## Handoff Options
+
+### Transfer (Ctrl+T) - Recommended
+When the subagent finishes, the user presses **Ctrl+T** to transfer output directly to you:
+
+```
+[Subagent finishes work in overlay]
+        ↓
+[User presses Ctrl+T]
+        ↓
+[You receive: "Session output transferred (150 lines):
+  
+  Completing skill integration...
+  Modified files:
+  - skills.ts
+  - agents/types/..."]
+```
+
+This is the cleanest workflow - the subagent's response becomes your context automatically.
+
+**Configuration:** `transferLines` (default: 200), `transferMaxChars` (default: 20KB)
+
+### Tail Preview (default)
+Last 30 lines included in tool result. Good for seeing errors/final status.
+
+### Snapshot to File
+Write full transcript to `~/.pi/agent/cache/interactive-shell/snapshot-*.log`:
+```typescript
+interactive_shell({
+  command: 'claude "Fix bugs"',
+  handoffSnapshot: { enabled: true, lines: 200 }
+})
+```
+
+### Artifact Handoff (for complex tasks)
+Instruct the delegated agent to write a handoff file:
+```
+Write your findings to .pi/delegation/claude-handoff.md including:
+- What you did
+- Files changed
+- Any errors
+- Next steps for the main agent
+```
+
+## Safe TUI Capture
+
+**Never run TUI agents via bash** - they hang even with `--help`. Use `interactive_shell` with `timeout` instead:
+
+```typescript
+interactive_shell({
+  command: "pi --help",
+  mode: "hands-free",
+  timeout: 5000  // Auto-kill after 5 seconds
+})
+```
+
+The process is killed after timeout and captured output is returned in the handoff preview. This is useful for:
+- Getting CLI help from TUI applications
+- Capturing output from commands that don't exit cleanly
+- Any TUI command where you need quick output without user interaction
+
+For pi CLI documentation, you can also read directly: `/opt/homebrew/lib/node_modules/@mariozechner/pi-coding-agent/README.md`
+
+## Background Session Management
+
+```typescript
+// Background an active session (close overlay, keep running)
+interactive_shell({ sessionId: "calm-reef", background: true })
+
+// List all background sessions
+interactive_shell({ listBackground: true })
+
+// Reattach to a background session
+interactive_shell({ attach: "calm-reef" })                    // interactive (blocking)
+interactive_shell({ attach: "calm-reef", mode: "hands-free" })  // hands-free (poll)
+interactive_shell({ attach: "calm-reef", mode: "dispatch" })    // dispatch (notified)
+
+// Dismiss background sessions (kill running, remove exited)
+interactive_shell({ dismissBackground: true })               // all
+interactive_shell({ dismissBackground: "calm-reef" })        // specific
+```
+
+## Quick Reference
+
+**Dispatch subagent (fire-and-forget, default to pi):**
+```typescript
+interactive_shell({
+  command: 'pi "Implement the feature described in SPEC.md"',
+  mode: "dispatch",
+  reason: "Implementing feature"
+})
+// Returns immediately. You'll be notified when done.
+```
+
+**Background dispatch (headless, no overlay):**
+```typescript
+interactive_shell({
+  command: 'pi "Fix lint errors"',
+  mode: "dispatch",
+  background: true,
+  reason: "Fixing lint"
+})
+```
+
+**Start foreground subagent (hands-free, default to pi):**
+```typescript
+interactive_shell({
+  command: 'pi "Implement the feature described in SPEC.md"',
+  mode: "hands-free",
+  reason: "Implementing feature"
+})
+// Returns sessionId in updates, e.g., "shell-1"
+```
+
+**Send input to active session:**
+```typescript
+// Text with enter
+interactive_shell({ sessionId: "calm-reef", input: "/compact\n" })
+
+// Text + named keys
+interactive_shell({ sessionId: "calm-reef", input: "/model", inputKeys: ["enter"] })
+
+// Menu navigation
+interactive_shell({ sessionId: "calm-reef", inputKeys: ["down", "down", "enter"] })
+```
+
+**Change update frequency:**
+```typescript
+interactive_shell({ sessionId: "calm-reef", settings: { updateInterval: 60000 } })
+```
+
+**Foreground subagent (user requested different agent):**
+```typescript
+interactive_shell({
+  command: 'claude "Review this code for security issues"',
+  mode: "hands-free",
+  reason: "Security review with Claude"
+})
+```
+
+**Background subagent:**
+```typescript
+subagent({ agent: "scout", task: "Find all TODO comments" })
+```