pi-interactive-shell 0.8.0 → 0.8.2

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to the `pi-interactive-shell` extension will be documented i
 
 ## [Unreleased]
 
+## [0.8.2] - 2026-02-10
+
+### Added
+- `examples/prompts/` with three Codex CLI prompt templates: `codex-review-plan`, `codex-implement-plan`, `codex-review-impl`. Demonstrates a plan → implement → review workflow using meta-prompt generation and interactive shell overlays.
+- `examples/skills/codex-cli/` skill that teaches pi Codex CLI flags, config, sandbox caveats, and interactive_shell usage patterns.
+- README section documenting the workflow pipeline, installation, usage examples, and customization.
+
+## [0.8.1] - 2026-02-08
+
+### Fixed
+- README: documented `handsFree.gracePeriod` tool parameter and startup grace period behavior in Auto-Exit on Quiet and Dispatch sections.
+- README: added missing `handoffPreviewLines` and `handoffPreviewMaxChars` to config settings table.
+
 ## [0.8.0] - 2026-02-08
 
 ### Added
@@ -15,6 +28,7 @@ All notable changes to the `pi-interactive-shell` extension will be documented i
 
 ### Fixed
 - Dispatch/hands-free `autoExitOnQuiet` no longer kills sessions during startup silence; quiet timer now re-arms during grace period and applies auto-kill only after grace expires.
+- README config table missing `handoffPreviewLines` and `handoffPreviewMaxChars` entries despite appearing in the JSON example.
 
 ## [0.7.1] - 2026-02-03
 

package/README.md

@@ -115,7 +115,7 @@ Attach to review full output: interactive_shell({ attach: "calm-reef" })
 
 The notification includes a brief tail (last 5 lines) and a reattach instruction. The PTY is preserved for 5 minutes so the agent can attach to review full scrollback.
 
-Dispatch defaults `autoExitOnQuiet: true` — the session gets a 30s startup grace period, then is killed after output goes silent (5s by default), which signals completion for task-oriented subagents. Opt out with `handsFree: { autoExitOnQuiet: false }` for long-running processes.
+Dispatch defaults `autoExitOnQuiet: true` — the session gets a 30s startup grace period, then is killed after output goes silent (5s by default), which signals completion for task-oriented subagents. Tune the grace period with `handsFree: { gracePeriod: 60000 }` or opt out entirely with `handsFree: { autoExitOnQuiet: false }`.
 
 The overlay still shows for the user, who can Ctrl+T to transfer output, Ctrl+B to background, take over by typing, or Ctrl+Q for more options.
 
@@ -161,6 +161,18 @@ interactive_shell({
 })
 ```
 
+A 30s startup grace period prevents the session from being killed before the subprocess has time to produce output. Customize it per-call with `gracePeriod`:
+
+```typescript
+interactive_shell({
+  command: 'pi "Run the full test suite"',
+  mode: "hands-free",
+  handsFree: { autoExitOnQuiet: true, gracePeriod: 60000 }
+})
+```
+
+The default grace period is also configurable globally via `autoExitGracePeriod` in the config file.
+
 For multi-turn sessions where you need back-and-forth interaction, leave it disabled (default) and use `kill: true` when done.
 
 ### Send Input
@@ -300,6 +312,8 @@ Configuration files (project overrides global):
 | `handsFreeUpdateMaxChars` | 1500 | Max chars per update |
 | `handsFreeMaxTotalChars` | 100000 | Total char budget for updates |
 | `handoffPreviewEnabled` | true | Include tail in tool result |
+| `handoffPreviewLines` | 30 | Lines in tail preview (0-500) |
+| `handoffPreviewMaxChars` | 2000 | Max chars in tail preview (0-50KB) |
 | `handoffSnapshotEnabled` | false | Write transcript on detach/exit |
 | `ansiReemit` | true | Preserve ANSI colors in output |
 
@@ -315,6 +329,82 @@ interactive_shell → node-pty → subprocess
 
 Full PTY. The subprocess thinks it's in a real terminal.
 
+## Example Workflow: Plan, Implement, Review
+
+The `examples/prompts/` directory includes three prompt templates that chain together into a complete development workflow using Codex CLI. Each template instructs pi to gather context, generate a tailored meta prompt based on the [Codex prompting guide](https://developers.openai.com/cookbook/examples/gpt-5/gpt-5-2_prompting_guide.md), and launch Codex in an interactive overlay.
+
+### The Pipeline
+
+```
+Write a plan
+    ↓
+/codex-review-plan path/to/plan.md        ← Codex verifies every assumption against the codebase
+    ↓
+/codex-implement-plan path/to/plan.md     ← Codex implements the reviewed plan faithfully
+    ↓
+/codex-review-impl path/to/plan.md        ← Codex reviews the diff against the plan, fixes issues
+```
+
+### Installing the Templates
+
+Copy the prompt templates and Codex CLI skill to your pi config:
+
+```bash
+# Prompt templates (slash commands)
+cp ~/.pi/agent/extensions/interactive-shell/examples/prompts/*.md ~/.pi/agent/prompts/
+
+# Codex CLI skill (teaches pi how to use codex flags, sandbox caveats, etc.)
+cp -r ~/.pi/agent/extensions/interactive-shell/examples/skills/codex-cli ~/.pi/agent/skills/
+```
+
+### Usage
+
+Say you have a plan at `docs/auth-redesign-plan.md`:
+
+**Step 1: Review the plan** — Codex reads your plan, then verifies every file path, API shape, data flow, and integration point against the actual codebase. Fixes issues directly in the plan file.
+
+```
+/codex-review-plan docs/auth-redesign-plan.md
+/codex-review-plan docs/auth-redesign-plan.md pay attention to the migration steps
+```
+
+**Step 2: Implement the plan** — Codex reads all relevant code first, then implements bottom-up: shared utilities first, then dependent modules, then integration code. No stubs, no TODOs.
+
+```
+/codex-implement-plan docs/auth-redesign-plan.md
+/codex-implement-plan docs/auth-redesign-plan.md skip test files for now
+```
+
+**Step 3: Review the implementation** — Codex diffs the changes, reads every changed file in full (plus imports and dependents), traces code paths across file boundaries, and fixes every issue it finds. Pass the plan to verify completeness, or omit it to just review the diff.
+
+```
+/codex-review-impl docs/auth-redesign-plan.md              # review diff against plan
+/codex-review-impl docs/auth-redesign-plan.md check cleanup ordering
+/codex-review-impl                                          # just review the diff, no plan
+/codex-review-impl focus on error handling and race conditions
+```
+
+### How They Work
+
+These templates demonstrate a "meta-prompt generation" pattern:
+
+1. **Pi gathers context** — reads the plan, runs git diff, fetches the Codex prompting guide
+2. **Pi generates a calibrated prompt** — tailored to the specific plan/diff, following the guide's best practices
+3. **Pi launches Codex in the overlay** — with explicit flags (`-m gpt-5.3-codex -c model_reasoning_effort="high" -a never`) and hands off control
+
+The user watches Codex work in the overlay and can take over anytime (type to intervene, Ctrl+T to transfer output back to pi, Ctrl+Q for options).
+
+### Customizing
+
+These are starting points. Fork them and adjust:
+
+- **Model/flags** — swap `gpt-5.3-codex` for another model, change reasoning effort
+- **Review criteria** — add project-specific checks (security policies, style rules)
+- **Implementation rules** — change the 500-line file limit, add framework-specific patterns
+- **Other agents** — adapt the pattern for Claude (`claude "prompt"`), Gemini (`gemini -i "prompt"`), or any CLI
+
+See the [pi prompt templates docs](https://github.com/badlogic/pi-mono/) for the full `$1`, `$@` placeholder syntax.
+
 ## Advanced: Multi-Agent Workflows
 
 For orchestrating multi-agent chains (scout → planner → worker → reviewer) with file-based handoff and auto-continue support, see:

package/examples/prompts/codex-implement-plan.md

@@ -0,0 +1,23 @@
+---
+description: Launch Codex CLI in overlay to fully implement an existing plan/spec document
+---
+Read the Codex prompting guide at https://developers.openai.com/cookbook/examples/gpt-5/gpt-5-2_prompting_guide.md using fetch_content or web_search. Then read the plan at `$1`.
+
+Analyze the plan to understand: how many files are created vs modified, whether there's a prescribed implementation order or prerequisites, what existing code is referenced, and roughly how large the implementation is.
+
+Based on the prompting guide's best practices and the plan's content, generate a comprehensive meta prompt tailored for Codex CLI. The meta prompt should instruct Codex to:
+
+1. Read and internalize the full plan document. Identify every file to be created, every file to be modified, and any prerequisites or ordering constraints.
+2. Before writing any code, read all existing files that will be modified — in full, not just the sections mentioned in the plan. Also read key files they import from or that import them, to absorb the surrounding patterns, naming conventions, and architecture.
+3. If the plan specifies an implementation order or prerequisites (e.g., "extract module X before building Y"), follow that order exactly. Otherwise, implement bottom-up: shared utilities and types first, then the modules that depend on them, then integration/registration code last.
+4. Implement each piece completely. No stubs, no TODOs, no placeholder comments, no "implement this later" shortcuts. Every function body, every edge case handler, every error path described in the plan must be real code.
+5. Match existing code patterns exactly — same formatting, same import style, same error handling conventions, same naming. Read the surrounding codebase to absorb these patterns before writing. If the plan references patterns from specific files (e.g., "same pattern as X"), read those files and replicate the pattern faithfully.
+6. Keep files reasonably sized. If a file grows beyond ~500 lines, split it as the plan describes or refactor into logical sub-modules.
+7. After implementing all files, do a self-review pass: re-read the plan from top to bottom and verify every requirement, every edge case, every design decision is addressed in the code. Check for: missing imports, type mismatches, unreachable code paths, inconsistent field names between modules, and any plan requirement that was overlooked.
+8. Do NOT commit or push. Write a summary listing every file created or modified, what was implemented in each, and any plan ambiguities that required judgment calls.
+
+The meta prompt should follow the Codex guide's structure: clear system context, explicit scope and verbosity constraints, step-by-step instructions, and expected output format. Emphasize that the plan has already been thoroughly reviewed — the job is faithful execution, not second-guessing the design.
+
+Then launch Codex CLI in the interactive shell overlay with that meta prompt using these flags: `-m gpt-5.3-codex -c model_reasoning_effort="high" -a never`. Do NOT pass sandbox flags in interactive_shell. End your turn immediately after launching -- do not poll the session. The user will manage the overlay directly.
+
+$@

package/examples/prompts/codex-review-impl.md

@@ -0,0 +1,24 @@
+---
+description: Launch Codex CLI in overlay to review implemented code changes (optionally against a plan)
+---
+Read the Codex prompting guide at https://developers.openai.com/cookbook/examples/gpt-5/gpt-5-2_prompting_guide.md using fetch_content or web_search. Then determine the review scope:
+
+- If `$1` looks like a file path (contains `/` or ends in `.md`): read it as the plan/spec these changes were based on. The diff scope is uncommitted changes vs HEAD, or if clean, the current branch vs main.
+- Otherwise: no plan file. Diff scope is the same. Treat all of `$@` as additional review context or focus areas.
+
+Run the appropriate git diff to identify which files changed and how many lines are involved. This context helps you generate a better-calibrated meta prompt.
+
+Based on the prompting guide's best practices, the diff scope, and the optional plan, generate a comprehensive meta prompt tailored for Codex CLI. The meta prompt should instruct Codex to:
+
+1. Identify all changed files via git diff, then read every changed file in full — not just the diff hunks. For each changed file, also read the files it imports from and key files that depend on it, to understand integration points and downstream effects.
+2. If a plan/spec was provided, read it and verify the implementation is complete — every requirement addressed, no steps skipped, nothing invented beyond scope, no partial stubs left behind.
+3. Review each changed file for: bugs, logic errors, race conditions, resource leaks (timers, event listeners, file handles, unclosed connections), null/undefined hazards, off-by-one errors, error handling gaps, type mismatches, dead code, unused imports/variables/parameters, unnecessary complexity, and inconsistency with surrounding code patterns and naming conventions.
+4. Trace key code paths end-to-end across function and file boundaries — verify data flows, state transitions, error propagation, and cleanup ordering. Don't evaluate functions in isolation.
+5. Check for missing or inadequate tests, stale documentation, and missing changelog entries.
+6. Fix every issue found with direct code edits. After all fixes, write a clear summary listing what was found, what was fixed, and any remaining concerns that require human judgment.
+
+The meta prompt should follow the Codex guide's structure: clear system context, explicit scope and verbosity constraints, step-by-step instructions, and expected output format. Emphasize thoroughness — read the actual code deeply before making judgments, question every assumption, and never rubber-stamp.
+
+Then launch Codex CLI in the interactive shell overlay with that meta prompt using these flags: `-m gpt-5.3-codex -c model_reasoning_effort="high" -a never`. Do NOT pass sandbox flags in interactive_shell. End your turn immediately after launching -- do not poll the session. The user will manage the overlay directly.
+
+$@

package/examples/prompts/codex-review-plan.md

@@ -0,0 +1,19 @@
+---
+description: Launch Codex CLI in overlay to review an implementation plan against the codebase
+---
+Read the Codex prompting guide at https://developers.openai.com/cookbook/examples/gpt-5/gpt-5-2_prompting_guide.md using fetch_content or web_search. Then read the plan at `$1`.
+
+Based on the prompting guide's best practices and the plan's content, generate a comprehensive meta prompt tailored for Codex CLI. The meta prompt should instruct Codex to:
+
+1. Read and internalize the full plan
+2. Systematically review the plan against the reference docs/links/code
+3. Verify every assumption, file path, API shape, data flow, and integration point mentioned in the plan
+4. Check that the plan's approach is logically sound, complete, and accounts for edge cases
+5. Identify any gaps, contradictions, incorrect assumptions, or missing steps
+6. Make direct edits to the plan file to fix any issues found, adding inline notes where changes were made
+
+The meta prompt should be structured according to the Codex guide's recommendations (clear system context, explicit constraints, step-by-step instructions, expected output format).
+
+Then launch Codex CLI in the interactive shell overlay with that meta prompt using these flags: `-m gpt-5.3-codex -c model_reasoning_effort="xhigh" -a never`. Do NOT pass sandbox flags in interactive_shell. End your turn immediately after launching -- do not poll the session. The user will manage the overlay directly.
+
+$@

package/examples/skills/codex-cli/SKILL.md

@@ -0,0 +1,86 @@
+---
+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:
+
+```typescript
+// Interactive with prompt
+interactive_shell({
+  command: 'codex -m gpt-5.3-codex -a never "Review this codebase for security issues"',
+  mode: "hands-free"
+})
+
+// Override reasoning effort for a single run
+interactive_shell({
+  command: 'codex -m gpt-5.3-codex -c model_reasoning_effort="xhigh" -a never "Complex refactor task"',
+  mode: "hands-free"
+})
+
+// Headless - use bash instead
+bash({ command: 'codex exec "summarize the repo"' })
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-interactive-shell",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Run AI coding agents as foreground subagents in pi TUI overlays with hands-free monitoring",
   "type": "module",
   "bin": {
@@ -18,6 +18,7 @@
     "headless-monitor.ts",
     "types.ts",
     "scripts/",
+    "examples/",
     "banner.png",
     "README.md",
     "SKILL.md",