pi-persistent-term

Integrated terminal panel for the pi coding agent. Provides a persistent PTY shell inside pi — state (cwd, virtualenvs, environment variables) survives across calls, unlike pi's built-in bash tool which spawns a fresh subshell each time.

Features

• Persistent shell — cd, source .venv/bin/activate, export, etc. all carry over between calls
• Terminal overlay — /term or Ctrl+\`` opens a full-color interactive panel, Ctrl+Q` returns to pi
• LLM tools — run_in_terminal, write_terminal, read_terminal let the LLM drive the shell
• Context injection — recent terminal output is automatically prepended to every LLM prompt
• Colored display — uses @xterm/headless for proper terminal emulation in the overlay
• Scrollback — PgUp/PgDn to scroll, Shift+PgUp/Shift+PgDn for fine scroll

Installation

git clone https://github.com/kowsari/pi-persistent-term
cd pi-persistent-term
npm install
pi install .

Commands

Command	Description
/term	Open terminal overlay
/term-clear	Clear the terminal buffer
/term-restart	Restart the terminal shell process
/term-context	Toggle auto-injecting terminal output into LLM prompts
/monitor-stop	Stop the currently monitored background process
`Ctrl+``	Shortcut to open terminal overlay

Keybindings (inside overlay)

Key	Action
Ctrl+Q	Close overlay, return to pi
Ctrl+C	Interrupt running process
PgUp / PgDn	Scroll by page
Shift+PgUp / Shift+PgDn	Scroll by 5 lines

LLM Tools

monitor_process

Start, stop, or check a background process monitor. Output is captured from a child process (separate from the PTY shell) and can optionally be pushed into the conversation in real-time.

# Silent mode — output buffered, readable via read_terminal
monitor_process(action="start", command="npm run build -- --watch")

# React mode — each output chunk triggers a new LLM turn
monitor_process(action="start", command="pytest tests/ -v", react=True)

# Stop the monitor
monitor_process(action="stop")

# Check what's running
monitor_process(action="status")

Silent vs react mode:

Mode	Behavior	Best for
react=false (default)	Output buffered quietly, check with read_terminal	Dev servers, chatty watchers
react=true	Each output chunk → new LLM turn	Test runners, log monitors, error watching

Note: The monitor spawns an independent child process using the session's cwd and outer environment. It does not inherit PTY shell state (active virtualenvs, cds inside the shell). Prefix with source .venv/bin/activate && when needed. Only one monitor can run at a time.

run_in_terminal

Runs a command in the persistent PTY shell and waits for it to complete (sentinel-based). Returns the full output. Best for commands that finish — npm install, pytest, git status, etc.

run_in_terminal("npm install")
run_in_terminal("pytest tests/", wait_ms=60000)

write_terminal

Sends raw text or keypresses to the shell. Use for interactive prompts.

write_terminal("yes\n")
write_terminal("\x03")   # Ctrl+C

read_terminal

Reads recent output from the terminal buffer (includes monitor output when running).

read_terminal(lines=100)

Tool comparison

	bash tool	run_in_terminal	monitor_process
Shell state	Fresh subshell	Persistent PTY	Own child process
Blocking	Yes	Yes (sentinel)	No — background
Output delivery	On completion	On completion	Push (react) or buffer
Infinite processes	❌ timeout only	❌ timeout only	✅ natural fit
LLM reacts in real-time	❌	❌	✅ react mode
Best for	Stateless one-offs	Stateful commands	Watchers, log monitors

Requirements

• pi coding agent installed globally
• pi-interactive-shell installed globally (provides @xterm/headless)
• Node.js ≥ 18
• macOS or Linux (node-pty requires native compilation)

Architecture

• PtyManager — wraps node-pty, manages the shell process lifecycle
• MonitorManager — spawns an independent child_process for background monitoring; buffers output and flushes every 750ms (or at 4KB) into the pi conversation via pi.sendMessage({ triggerTurn: true }) in react mode
• XtermBuffer — wraps @xterm/headless for display only; renders colored lines for the overlay from raw PTY data
• SimpleBuffer — plain-text append buffer for read_terminal and sentinel-based command completion detection in run_in_terminal; also receives monitor output so read_terminal sees it

The two buffers serve different purposes: xterm is a screen emulator (viewport model) which handles display correctly but can't be used for line-based output capture. SimpleBuffer handles the text side reliably.