Pi Interactive Shell

What it does

Pi Interactive Shell runs terminal programs through a pseudoterminal and exposes them in a Pi overlay or managed background session.

Its interactive, hands-free, dispatch, and monitor modes let a user watch or take over while the agent sends input, reads output, or waits for event-driven notifications.

When to reach for it

Invocation: Ask Pi to launch an interactive command-line program, use the interactive terminal tool, or use the spawn command for a configured coding agent.

A terminal program needs live input or user supervision

Open an interactive overlay and address the running process by session ID.

A delegated coding-agent task should return control immediately

Use dispatch mode and receive a completion turn instead of polling.

A long-running process should wake the agent only on selected output or state changes

Use monitor mode with bounded stream, poll-diff, or file-watch triggers.

What it adds

• A PTY-backed terminal session with xterm-compatible rendering and ordered input.
• Stable session IDs for status, input, backgrounding, reattachment, dismissal, and output retrieval.
• Completion and monitor-event notifications that can start a follow-up Pi turn.

How it fits

• Pi Subagents: Interactive Shell exposes external coding-agent terminals for observation and takeover; Pi Subagents provides structured Pi child execution under parent-controlled contracts.

Common questions

Does the extension sandbox launched commands?

• No. The subprocess runs through a local shell with the selected working directory and inherited environment. Use an isolated working directory or worktree when unattended work could change repository state.

How do modes differ?

• Interactive mode returns a session ID for direct driving, hands-free mode adds progress updates, dispatch mode notifies on completion, and monitor mode emits only configured trigger events.

It’s working if

• A launched process returns a session ID and accepts status, output, or input operations while it remains active.
• Dispatch completion or a configured monitor match produces a bounded notification without a polling loop.

Source and setup

Provenance

Project

Pi Interactive Shell

Origin

Nico Bailon

Current maintainer

Nico Bailon

Relationship

original

Installed source

npm:pi-interactive-shell

Source path

View source (index.ts)

Compatibility

• Pi package and TUI APIs
• Node.js 22.19 or newer
• zigpty-supported platform

License

MIT

License publication scope

Source link, independently written summary, attribution, and reviewed behavior claims; no package source text is republished.

Reviewed revision

c5dac7836f6886ed001697acddc15d56fbefe199

Catalog revision

e0c035a297462c519315abfa1af31a1ed3bd9eef

Setup notes

• Created and maintained by Nico Bailon; this record reviews npm version 0.14.1 and its registry-linked source commit.
• Requires Node runtime version 22.19 or newer plus a platform supported by the bundled PTY dependency.
• The immutable package manifest and npm metadata declare MIT; version 0.14.1 does not contain a standalone license file.
• Bundled core and example skills plus example prompt templates remain secondary, unfeatured surfaces in this catalog record.