pi-agent-shell

A high-performance, general-purpose interactive shell extension for pi.

Gives AI agents a single turn() primitive to interact with any CLI program — no polling, no timing heuristics, no program-specific adapters. Uses OS-level read-block detection to know exactly when a program is waiting for input.

Install

pi install ~/Projects/pi-agent-shell

How it works

The agent interacts with shell programs through one atomic operation:

turn(sessionId, input?) → { newOutput, prompt, waitingForInput, exited }

Internally, turn() writes input to a PTY, drains output, and waits for an OS-level signal that the process is blocked on a read syscall. The agent never polls or guesses timing — every round-trip is a decision, not a timing check.

OS read-block detection

• macOS: process state probing via ps on the leaf foreground process
• Linux: /proc/{pid}/syscall — syscall number 0 (read) or select/epoll variants
• Fallback: quiet-window timeout when OS probing is unavailable (CI, containers)

Tool: agent_shell

Start a session

{ "command": "python3 game.py" }
→ { "sessionId": "abc-123" }

Take a turn

{ "sessionId": "abc-123", "input": "north" }
→ { "newOutput": "You enter a dark cave.\n> ", "prompt": "> ", "waitingForInput": true }

Peek (non-blocking)

{ "sessionId": "abc-123", "peek": true }
→ { "newOutput": "...", "waitingForInput": false }

Kill a session

{ "sessionId": "abc-123", "kill": true }

Parameters

Parameter	Type	Default	Description
command	string	—	Shell command to start a new session
sessionId	string	—	Session to interact with
input	string	—	Text to send (appends \n if missing)
peek	boolean	false	Non-blocking snapshot, no input
kill	boolean	false	Terminate the session
cwd	string	pi cwd	Working directory
env	object	—	Additional environment variables
timeoutMs	number	30000	Max wait time for turn()
quietMs	number	200	Quiet-window fallback threshold

User commands

Command	Description
/sessions	List all active sessions
/attach [id]	Reattach the session overlay to watch/interact

Session overlay

When a session is running, an overlay shows real-time output. Controls:

• Ctrl+B — background the session (overlay hides, session keeps running)
• Ctrl+C — kill the session
• ↑/↓ — scroll through output

Architecture

See ARCHITECTURE.md for design details.

Development

npm test        # run tests

Limitations

• Line-oriented programs only — full-screen TUI programs (vim, nano, htop) are not supported. The agent has better tools for file editing (read/edit/write), and most interactive CLI programs have non-interactive equivalents.
• Unix only — requires PTY support (macOS, Linux). No Windows/ConPTY support.
• Local processes only — no remote PTY or SSH session management.