Skip to content
interactive-shell logo

Interactive Shell (Skill)

interactive-shell

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 b...

SKILL.md

Full skill instructions

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 SubagentsDispatch SubagentsBackground Subagents
Toolinteractive_shellinteractive_shell (dispatch)subagent
VisibilityUser sees overlayUser sees overlay (or headless)Hidden from user
Agent modelPolls for statusNotified on completionFull output captured
Default agentpi (others if user requests)pi (others if user requests)Pi only
User controlCan take over anytimeCan take over anytimeNo intervention
Best forLong tasks needing supervisionFire-and-forget delegationsParallel 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 saysAgent 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.

interactive_shell({ command: 'pi' })

Interactive with Initial Prompt

Agent starts working immediately, user supervises.

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.

// 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.

Background Dispatch (Headless)

No overlay opens. Multiple headless dispatches can run concurrently:

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.

// 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

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

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

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:

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:

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

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)
// 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:

// 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:

// 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

// 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

KeyDescription
up, down, left, rightArrow keys
enter, returnEnter/​Return
escape, escEscape
tab, shift+tab (or btab)Tab / Back-tab
backspace, bspaceBackspace
delete, del, dcDelete
insert, icInsert
home, endHome/​End
pageup, pgup, ppagePage Up
pagedown, pgdn, npagePage Down
f1-f12Function keys
kp0-kp9, kp/, kp*, kp-, kp+, kp., kpenterKeypad keys
ctrl+c, ctrl+d, ctrl+zControl sequences
ctrl+a through ctrl+zAll 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-):

// 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:

inputHex: ["0x1b", "0x5b", "0x41"]  // ESC[A (up arrow)

Bracketed Paste

Paste multiline text without triggering autocompletion/​execution:

inputPaste: "function foo() {\n  return 42;\n}"

Model Selection Example

// 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

interactive_shell({ sessionId: "shell-1", input: "/​compact", inputKeys: ["enter"] })

Changing Update Settings

Adjust timing during a session:

// 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

AgentInteractiveWith PromptHeadless (bash)Dispatch
claudeclaudeclaude "prompt"claude -p "prompt"mode: "dispatch"
geminigeminigemini -i "prompt"gemini "prompt"mode: "dispatch"
codexcodexcodex "prompt"codex exec "prompt"mode: "dispatch"
agentagentagent "prompt"agent -p "prompt"mode: "dispatch"
pipipi "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:

// 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:

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:

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

// 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):

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):

interactive_shell({
  command: 'pi "Fix lint errors"',
  mode: "dispatch",
  background: true,
  reason: "Fixing lint"
})

Start foreground subagent (hands-free, default to pi):

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:

// 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:

interactive_shell({ sessionId: "calm-reef", settings: { updateInterval: 60000 } })

Foreground subagent (user requested different agent):

interactive_shell({
  command: 'claude "Review this code for security issues"',
  mode: "hands-free",
  reason: "Security review with Claude"
})

Background subagent:

subagent({ agent: "scout", task: "Find all TODO comments" })

More skills from Dicklesworthstone

exa-policy-guardrails logo
Dicklesworthstone/pi_agent_rust

exa-policy-guardrails

Implement Exa lint rules, policy enforcement, and automated guardrails. Use when setting up code quality rules for Exa integrations, implementing pre-commit hooks, or configuring CI policy checks for Exa best practices. Trigger with phrases like "exa policy", "exa lint", "exa guardrails", "exa be...

1.8K 0
View
documenso-ci-integration logo
Dicklesworthstone/pi_agent_rust

documenso-ci-integration

Configure CI/CD pipelines for Documenso integrations. Use when setting up automated testing, deployment pipelines, or continuous integration for Documenso projects. Trigger with phrases like "documenso CI", "documenso GitHub Actions", "documenso pipeline", "documenso automated testing".

1.8K 0
View
openrouter-model-availability logo
Dicklesworthstone/pi_agent_rust

openrouter-model-availability

Build check model availability and implement fallback chains. Use when building resilient systems or handling model outages. Trigger with phrases like 'openrouter availability', 'openrouter fallback', 'openrouter model down', 'openrouter health check'.

1.8K 0
View
langfuse-enterprise-rbac logo
Dicklesworthstone/pi_agent_rust

langfuse-enterprise-rbac

Configure Langfuse enterprise organization management and access control. Use when implementing team access controls, configuring organization settings, or setting up role-based permissions for Langfuse projects. Trigger with phrases like "langfuse RBAC", "langfuse teams", "langfuse organization"...

1.8K 0
View
cursor-compliance-audit logo
Dicklesworthstone/pi_agent_rust

cursor-compliance-audit

Execute compliance and security auditing for Cursor usage. Triggers on "cursor compliance", "cursor audit", "cursor security review", "cursor soc2", "cursor gdpr". Use when analyzing or auditing cursor compliance audit. Trigger with phrases like "cursor compliance audit", "cursor audit", "cursor".

1.8K 0
View
apollo-ci-integration logo
Dicklesworthstone/pi_agent_rust

apollo-ci-integration

Configure Apollo.io CI/CD integration. Use when setting up automated testing, continuous integration, or deployment pipelines for Apollo integrations. Trigger with phrases like "apollo ci", "apollo github actions", "apollo pipeline", "apollo ci/cd", "apollo automated tests".

1.8K 0
View
python-script logo
Dicklesworthstone/pi_agent_rust

python-script

Create robust Python automation with full logging and safety checks. Use when tasks need complex data processing, authenticated API work, conditional file operations, or error handling beyond simple shell commands.

1.8K 0
View
posthog-multi-env-setup logo
Dicklesworthstone/pi_agent_rust

posthog-multi-env-setup

Configure PostHog across development, staging, and production environments. Use when setting up multi-environment deployments, configuring per-environment secrets, or implementing environment-specific PostHog configurations. Trigger with phrases like "posthog environments", "posthog staging", "po...

1.8K 0
View
ai-agents-architect logo
Dicklesworthstone/pi_agent_rust

ai-agents-architect

Expert in designing and building autonomous AI agents. Masters tool use, memory systems, planning strategies, and multi-agent orchestration. Use when: build agent, AI agent, autonomous agent, tool use, function calling.

1.8K 0
View
insecure-deserialization-checker logo
Dicklesworthstone/pi_agent_rust

insecure-deserialization-checker

Validate insecure deserialization checker operations. Auto-activating skill for Security Fundamentals. Triggers on: insecure deserialization checker, insecure deserialization checker Part of the Security Fundamentals skill category. Use when working with insecure deserialization checker functiona...

1.8K 0
View
path-traversal-finder logo
Dicklesworthstone/pi_agent_rust

path-traversal-finder

Manage path traversal finder operations. Auto-activating skill for Security Fundamentals. Triggers on: path traversal finder, path traversal finder Part of the Security Fundamentals skill category. Use when working with path traversal finder functionality. Trigger with phrases like "path traversa...

1.8K 0
View
scientific-critical-thinking logo
Dicklesworthstone/pi_agent_rust

scientific-critical-thinking

Evaluate research rigor. Assess methodology, experimental design, statistical validity, biases, confounding, evidence quality (GRADE, Cochrane ROB), for critical analysis of scientific claims.

1.8K 0
View

Popular AI tools

Kaiber logo
Video

Kaiber

Generate, edit, and beat-sync AI video with leading models in one workspace.

Paid
View
Vimcal logo
Productivity

Vimcal

The world's fastest calendar for remote work

Free
View

Transform Your Design with AI Designer by ImgCreator.ai

Freemium
View
Akool AI logo
Content & writing

Akool AI

Revolutionizing Video Production with AI-Powered Creativity

Paid
View

Extend an image past the frame and let AI fill the new aspect ratio.

Freemium
View
StarByFace logo
Security

StarByFace

Discover your celebrity doppelgänger with StarByFace!

Free
View
C

ChainClarity explains 700+ crypto whitepapers in plain English, with layered summaries, comparisons, research tools, alerts, and a $4.99 Pro plan.

Freemium
View
Opus Clip logo
Coding & apps

Opus Clip

Opus.ai: Revolutionize Your Web Experience

Free
View