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.