An extension for Pi coding agent that lets Pi autonomously run interactive CLIs in an observable TUI overlay. Pi controls the subprocess while you watch - take over anytime.
pi-interactive-shell-extension.mp4
interactive_shell({ command: 'vim config.yaml' })Important: the interactive_shell({...}) snippets in this README are tool calls made by Pi (or extension/prompt authors). End users do not type these directly into chat. As a user, ask Pi to run something (for example: "run this in dispatch mode") or use /spawn, /attach, and /dismiss commands.
Some tasks need interactive CLIs - editors, REPLs, database shells, long-running processes. Pi can launch them in an overlay where:
- User watches - See exactly what's happening in real-time
- User takes over - Type anything to gain control
- Agent monitors - Query status, send input, decide when done
Works with any CLI: vim, htop, psql, ssh, docker logs -f, npm run dev, git rebase -i, etc.
pi install npm:pi-interactive-shellThe interactive-shell skill is automatically symlinked to ~/.pi/agent/skills/interactive-shell/.
Requires: Node.js. PTY support uses zigpty prebuilt binaries (no node-gyp toolchain required on supported platforms).
| Mode | Agent waits? | How output reaches agent | Best for |
|---|---|---|---|
| Interactive (default) | Yes — blocks until exit | Tool return value | Editors, REPLs, SSH — when you need the result now |
| Hands-free | No | Poll with sessionId |
Dev servers, builds — when you want to watch progress and send follow-up commands |
| Dispatch | No | Notification on completion via triggerTurn |
Delegating tasks to subagents — fire and forget |
| Monitor | No | Notification on structured monitor trigger events | Watchers, logs, tests, and state checks — wake only when something specific happens |
Interactive — The overlay opens, user controls the session, agent waits for it to close. Use for editors (vim), database shells (psql), or any task where the agent needs the final result immediately.
Hands-free — The overlay opens but returns immediately. The agent polls periodically with sessionId to check status and get new output. Good for long-running builds or dev servers where you want to react mid-flight (send input, check logs, kill when ready).
Dispatch — Returns immediately. No polling. The agent gets woken up via triggerTurn only when the session completes (natural exit, timeout, quiet detection, or user kill). The notification includes a tail of the output. This is the default for delegating work to subagents. Add background: true to skip the overlay entirely.
Monitor — Returns immediately. No polling, no completion notification. The agent gets woken up when a configured monitor trigger emits an event. Supports stream triggers, poll-diff checks, first-class file watching, optional cooldowns, persistence controls, detector commands, and event history queries. Runs headless; attach to inspect if needed.
The examples below show agent-side tool calls. They are not chat commands for end users.
For Pi, Codex, and Claude, the agent can use structured spawn params instead of building command strings by hand:
// User says: "Spawn pi so I can edit files interactively"
interactive_shell({ spawn: { agent: "pi" }, mode: "interactive" })
// User says: "Delegate this refactor to codex and notify me when it's done"
interactive_shell({ spawn: { agent: "codex" }, mode: "dispatch" })
// User says: "Ask claude to review the diffs in dispatch mode"
interactive_shell({ spawn: { agent: "claude", prompt: "Review the diffs" }, mode: "dispatch" })
// User says: "Start claude in a worktree for hands-free monitoring"
interactive_shell({ spawn: { agent: "claude", worktree: true }, mode: "hands-free" })
// User says: "Fork my current pi session" (Pi-only)
interactive_shell({ spawn: { mode: "fork" }, mode: "interactive" })Structured spawn uses the same resolver and config defaults as the user-facing /spawn command. Raw command is still supported for arbitrary CLIs and custom launch strings.
// User says: "Open package.json in vim"
interactive_shell({ command: 'vim package.json' })
// User says: "Connect to the postgres database"
interactive_shell({ command: 'psql -d mydb' })
// User says: "SSH into the server"
interactive_shell({ command: 'ssh user@server' })The agent's turn is blocked until the overlay closes. User controls the session directly.
// Start a long-running process
interactive_shell({
command: 'npm run dev',
mode: "hands-free",
reason: "Dev server"
})
// → { sessionId: "calm-reef", status: "running" }
// User says: "Check on the dev server status"
interactive_shell({ sessionId: "calm-reef" })
// → { status: "running", output: "Server ready on :3000", runtime: 45000 }
// Send input when needed
interactive_shell({ sessionId: "calm-reef", input: "/run review", submit: true })
interactive_shell({ sessionId: "calm-reef", inputKeys: ["ctrl+c"] })
// Kill when done
interactive_shell({ sessionId: "calm-reef", kill: true })
// → { status: "killed", output: "..." }The overlay opens for the user to watch. The agent checks in periodically. User can type anything to take over control. After taking over a monitored hands-free or dispatch session, press Ctrl+G to return control to the agent.
// User says: "Delegate refactoring the auth module to pi and notify me when done"
interactive_shell({
command: 'pi "Refactor the auth module"',
mode: "dispatch",
reason: "Auth refactor"
})
// → Returns immediately: { sessionId: "calm-reef" }
// → Agent ends turn or does other work.When the session completes, the agent receives a compact notification on a new turn:
Session calm-reef completed successfully (5m 23s). 847 lines of output.
Step 9 of 10
Step 10 of 10
All tasks completed.
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 15s startup grace period, then is killed after output goes silent (8s 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. Ctrl+G only becomes meaningful after the user has taken over a monitored hands-free or dispatch session.
// No overlay — runs completely invisibly
interactive_shell({
command: 'pi "Fix all lint errors"',
mode: "dispatch",
background: true
})
// → { sessionId: "calm-reef" }
// → User can /attach calm-reef to peek
// → Agent notified on completion, same as regular dispatchMultiple headless dispatches can run concurrently alongside a single interactive overlay. This is how you parallelize subagent work — fire off three background dispatches and process results as each completion notification arrives.
These examples are agent tool calls. End users should ask in natural language (for example: "watch my tests and alert me on failures"), and Pi should invoke interactive_shell with the monitor config.
Wake the agent when monitor triggers emit events — no polling and no waiting for process completion.
// User says: "Watch my tests and alert me on failures or errors"
interactive_shell({
command: 'npm test --watch',
mode: "monitor",
monitor: {
strategy: "stream",
triggers: [
{ id: "failed", literal: "FAIL" },
{ id: "error", regex: "/error|exception/i" }
],
throttle: { dedupeExactLine: true },
persistence: { stopAfterFirstEvent: false }
}
})
// User says: "Monitor the health endpoint and tell me when it changes"
interactive_shell({
command: 'curl -sf http://localhost:3000/health',
mode: "monitor",
monitor: {
strategy: "poll-diff",
triggers: [{ id: "changed", regex: "/./" }],
poll: { intervalMs: 5000 }
}
})
// User says: "Alert me when NVDA drops below $120"
interactive_shell({
command: 'curl -s https://api.example.com/quote/NVDA',
mode: "monitor",
monitor: {
strategy: "stream",
triggers: [
{
id: "nvda-below-120",
regex: "/NVDA:\\s*\\$?(\\d+(?:\\.\\d+)?)/",
threshold: { captureGroup: 1, op: "lt", value: 120 }
}
]
}
})
// User says: "Watch the uploads folder for new PDF files and notify me"
interactive_shell({
mode: "monitor",
monitor: {
strategy: "file-watch",
fileWatch: { path: "./uploads", recursive: true, events: ["rename", "change"] },
triggers: [{ id: "pdf", regex: "/\\.pdf$/i" }]
}
})Monitor mode emits structured payloads (sessionId, eventId, timestamp, strategy, triggerId, matchedText, lineOrDiff, stream) and now also emits lifecycle notifications when a monitor stops (stream ended, script failed, stopped, or timed out). monitorFilter was removed in favor of the structured monitor object.
interactive_shell({ monitorStatus: true, monitorSessionId: "calm-reef" })
interactive_shell({ monitorEvents: true, monitorSessionId: "calm-reef" })
interactive_shell({ monitorEvents: true, monitorSessionId: "calm-reef", monitorSinceEventId: 42 })
interactive_shell({ monitorEvents: true, monitorSessionId: "calm-reef", monitorTriggerId: "error" })
interactive_shell({ monitorEvents: true, monitorSessionId: "calm-reef", monitorEventLimit: 50, monitorEventOffset: 20 })Monitor sessions run headless and can be managed like other background sessions (listBackground, /attach, dismissBackground).
Capture output from TUI apps that don't exit cleanly:
interactive_shell({
command: "htop",
mode: "hands-free",
timeout: 3000 // Kill after 3s, return captured output
})For fire-and-forget single-task delegations, enable auto-exit to kill the session after 8s of output silence:
interactive_shell({
command: 'pi "Fix the bug in auth.ts"',
mode: "hands-free",
handsFree: { autoExitOnQuiet: true }
})A 15s startup grace period prevents the session from being killed before the subprocess has time to produce output. Customize it per-call with gracePeriod:
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.
// Text only (types text but does not submit)
interactive_shell({ sessionId: "calm-reef", input: "SELECT * FROM users;" })
// Type text and press Enter
interactive_shell({ sessionId: "calm-reef", input: "SELECT * FROM users;", submit: true })
// Named keys
interactive_shell({ sessionId: "calm-reef", inputKeys: ["ctrl+c"] })
interactive_shell({ sessionId: "calm-reef", inputKeys: ["down", "down", "enter"] })
// Bracketed paste (multiline without execution)
interactive_shell({ sessionId: "calm-reef", inputPaste: "line1\nline2\nline3" })
// Hex bytes (raw escape sequences)
interactive_shell({ sessionId: "calm-reef", inputHex: ["0x1b", "0x5b", "0x41"] })
// Combine text with keys
interactive_shell({ sessionId: "calm-reef", input: "y", inputKeys: ["enter"] })For editor-based TUIs like pi, raw input only types text. It does not submit the prompt. Prefer submit: true or inputKeys: ["enter"] instead of relying on \n.
// Default: 20 lines, 5KB
interactive_shell({ sessionId: "calm-reef" })
// More lines (max: 200)
interactive_shell({ sessionId: "calm-reef", outputLines: 100 })
// Incremental pagination (server tracks position)
interactive_shell({ sessionId: "calm-reef", outputLines: 50, incremental: true })
// Drain mode (raw stream since last query)
interactive_shell({ sessionId: "calm-reef", drain: true })When a subagent finishes work, press Ctrl+T to capture its output and send it directly to the main agent:
[Subagent finishes work]
↓
[Press Ctrl+T]
↓
[Overlay closes, main agent receives full output]
The main agent then has the subagent's response in context and can continue working with that information.
Configuration:
transferLines: Max lines to capture (default: 200)transferMaxChars: Max characters (default: 20KB)
Sessions can be backgrounded by the user (Ctrl+B, or Ctrl+Q → "Run in background") or by the agent:
// Agent backgrounds an active session
interactive_shell({ sessionId: "calm-reef", background: true })
// → Overlay closes, process keeps running
// List background sessions
interactive_shell({ listBackground: true })
// Reattach with a specific mode
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
interactive_shell({ dismissBackground: true }) // all sessions
interactive_shell({ dismissBackground: "calm-reef" }) // specific sessionMonitor sessions work the same way — they're headless background sessions that wake you on monitor events instead of completion.
User can also /spawn to launch the configured default spawn agent, /spawn codex, /spawn claude, /spawn pi, /spawn fork, or /spawn pi fork. Add --worktree to spawn in a separate git worktree, for example /spawn codex --worktree or /spawn pi fork --worktree. Plain /spawn claude stays a normal interactive overlay. fork is Pi-only. Worktrees are left in place and the overlay will tell you where they were created. /attach or /attach <id> reattaches, and /dismiss or /dismiss <id> cleans up from the chat. The keyboard spawn shortcut is separate from /spawn and uses spawn.shortcut.
Quoted prompt text plus --hands-free or --dispatch turns /spawn into a monitored delegated run instead of a plain interactive overlay. This shares the same resolver and defaults as structured interactive_shell({ spawn: ... }). Plain /spawn stays interactive. Ctrl+G only applies after you take over one of these monitored sessions.
/spawn claude "review the diffs" --dispatch
/spawn codex "fix the failing tests" --hands-free
/spawn pi fork "continue from here" --dispatch| Key | Action |
|---|---|
| Ctrl+T | Transfer & close - capture output and send to main agent |
| Ctrl+B | Background session (dismiss overlay, keep running) |
| Ctrl+Q | Session menu (transfer/background/kill/cancel) |
| Shift+Up/Down | Scroll history |
| Alt+Shift+F (default) | Toggle focus between overlay and main chat (focusShortcut) |
| Ctrl+G | Return to agent monitoring (only after taking over a monitored hands-free or dispatch session) |
| Alt+Shift+P (default) | Launch the configured default spawn agent (spawn.shortcut) |
| Any key (hands-free) | Take over control |
Configuration files (project overrides global):
- Global:
~/.pi/agent/interactive-shell.json - Project:
.pi/interactive-shell.json
Shortcut settings are pinned at startup. If you change focusShortcut or spawn.shortcut, reload or restart Pi to apply them.
{
"overlayWidthPercent": 95,
"overlayHeightPercent": 60,
"focusShortcut": "alt+shift+f",
"spawn": {
"defaultAgent": "pi",
"shortcut": "alt+shift+p",
"commands": {
"pi": "pi",
"codex": "codex",
"claude": "claude"
},
"defaultArgs": {
"pi": [],
"codex": [],
"claude": []
},
"worktree": false,
"worktreeBaseDir": "../repo-worktrees"
},
"scrollbackLines": 5000,
"exitAutoCloseDelay": 10,
"minQueryIntervalSeconds": 60,
"transferLines": 200,
"transferMaxChars": 20000,
"completionNotifyLines": 50,
"completionNotifyMaxChars": 5000,
"handsFreeUpdateMode": "on-quiet",
"handsFreeUpdateInterval": 60000,
"handsFreeQuietThreshold": 8000,
"autoExitGracePeriod": 15000,
"handsFreeUpdateMaxChars": 1500,
"handsFreeMaxTotalChars": 100000,
"handoffPreviewEnabled": true,
"handoffPreviewLines": 30,
"handoffPreviewMaxChars": 2000,
"handoffSnapshotEnabled": false,
"ansiReemit": true
}| Setting | Default | Description |
|---|---|---|
overlayWidthPercent |
95 | Overlay width (10-100%) |
overlayHeightPercent |
60 | Overlay height (20-90%) |
focusShortcut |
"alt+shift+f" | Toggle focus between overlay and main chat |
spawn.defaultAgent |
"pi" | Configured default spawn agent for /spawn, the spawn shortcut, and agent-side structured spawn |
spawn.shortcut |
"alt+shift+p" | Keyboard shortcut that launches the configured default spawn agent |
spawn.commands.<agent> |
pi / codex / claude |
Executable or path override per spawn agent |
spawn.defaultArgs.<agent> |
[] |
Extra default CLI args per spawn agent |
spawn.worktree |
false |
Launch spawns in a separate git worktree by default |
spawn.worktreeBaseDir |
unset | Optional base directory for generated worktrees |
scrollbackLines |
5000 | Terminal scrollback buffer |
exitAutoCloseDelay |
10 | Seconds before auto-close after exit |
minQueryIntervalSeconds |
60 | Rate limit between agent queries |
transferLines |
200 | Lines to capture on Ctrl+T transfer (10-1000) |
transferMaxChars |
20000 | Max chars for transfer (1KB-100KB) |
completionNotifyLines |
50 | Lines in dispatch completion notification (10-500) |
completionNotifyMaxChars |
5000 | Max chars in completion notification (1KB-50KB) |
handsFreeUpdateMode |
"on-quiet" | "on-quiet" or "interval" |
handsFreeQuietThreshold |
8000 | Silence duration before update (ms) |
autoExitGracePeriod |
15000 | Startup grace before autoExitOnQuiet kill (ms) |
handsFreeUpdateInterval |
60000 | Max interval between updates (ms) |
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 |
interactive_shell → zigpty → subprocess
↓
xterm-headless (terminal emulation)
↓
TUI overlay (pi rendering)
Full PTY. The subprocess thinks it's in a real terminal.
The examples/prompts/ directory includes three prompt templates that chain together into a complete development workflow using Codex CLI. Each template now loads the bundled gpt-5-4-prompting skill by default, falls back to codex-5-3-prompting when the user explicitly asks for Codex 5.3, and launches Codex in an interactive overlay.
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
Install the package first so pi can discover the bundled prompt and skill directories via the package metadata:
pi install npm:pi-interactive-shellIf you want your own slash commands and local skill copies, copy the examples into your agent config:
# Prompt templates (slash commands)
cp ~/.pi/agent/extensions/interactive-shell/examples/prompts/*.md ~/.pi/agent/prompts/
# Skills used by the templates
cp -r ~/.pi/agent/extensions/interactive-shell/examples/skills/codex-cli ~/.pi/agent/skills/
cp -r ~/.pi/agent/extensions/interactive-shell/examples/skills/gpt-5-4-prompting ~/.pi/agent/skills/
cp -r ~/.pi/agent/extensions/interactive-shell/examples/skills/codex-5-3-prompting ~/.pi/agent/skills/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
These templates demonstrate a "meta-prompt generation" pattern:
- Pi gathers context — reads the plan, runs git diff, and loads the local
gpt-5-4-promptingorcodex-5-3-promptingskill - Pi generates a calibrated prompt — tailored to the specific plan/diff, following the selected skill's best practices
- Pi launches Codex in the overlay — defaulting to
-m gpt-5.4 -a neverand switching to-m gpt-5.3-codex -a neveronly when the user explicitly asks for Codex 5.3
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).
These are starting points. Fork them and adjust:
- Model/flags — swap
gpt-5.3-codexfor 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 for the full $1, $@ placeholder syntax.
For orchestrating multi-agent chains (scout → planner → worker → reviewer) with file-based handoff and auto-continue support, see:
pi-foreground-chains - A separate skill that builds on interactive-shell for complex agent workflows.
- macOS tested, Linux experimental
- 60s rate limit between queries (configurable)
- Some TUI apps may have rendering quirks