pi-subagents

Interactive research mode for pi: fork the current session into a tmux pane running a fresh pi, steer the research directly, and send findings back to the parent session.

Commands

Command	Description
/rsh <task>	Fork the current session into an interactive tmux pane
/rsh-report	(in the child pane) send research findings back to the parent
/rsh-close [id]	Tear down a research session; omit id to list active sessions

/rsh

Forks the current session — parent transcript plus a boundary marker — into a fresh pi session spawned in a new tmux pane. The child is an interactive pi: you steer it directly, redirect it, iterate, then report back.

The child is launched from an executable script kept at ~/.pi/agent/research-scripts/<session-id>.sh, with stderr logged to <session-id>.log, so the exact invocation survives for debugging.

/rsh-report

Run inside the research pane. The child's last assistant message is written to a report file and delivered to the parent before the parent's next agent turn, appearing as a research_complete message.

/rsh-close

Cleans up a session by id: the tmux pane, the forked session file, the launch script and log, and the session state. Without an id it lists active research sessions.

Lifecycle

Research sessions clean up after themselves:

• When the child pi exits — gracefully or because the pane died — it removes its own pane, session file, launch script, and state.
• Every pi process sweeps research-sessions/ on startup and cleans sessions whose pane or child process is gone (covers crashes and SIGKILL).
• /rsh-close remains for manual cleanup.

Configuration

pi-subagents.json, read from ~/.pi/agent/ (global) and .pi/ (project; project overrides global):

Key	Type	Default	Description
focusOnStart	boolean	true	Jump into the research pane after /rsh

Requirements

• tmux — the research child runs in a tmux pane
• pi — the forked child runs pi interactively

Development

# Run unit tests from the workspace root
cd ../.. && pnpm run test

# Test with coverage
pnpm run test:coverage