Skip to content
sdlc

pi: harness notes for a dispatcher

State: open/active · Genre: research

Source: pi --help, and the installed package’s own docs (docs/rpc.md, docs/sessions.md, docs/tmux.md under @earendil-works/pi-coding-agent), pi 0.84.3, examined 2026-09-25. Package path: ~/.tools/proto/tools/node/24.13.0/lib/node_modules/@earendil-works/pi-coding-agent/.

Open with a known id and name

Section titled “Open with a known id and name”
  • Verified. pi --session-id <id> opens a session under an exact id, creating it if it does not exist. --name/-n <name> sets its display name at startup. The two compose: pi --session-id <id> --name "<name>".

Resume by id with a prompt

Section titled “Resume by id with a prompt”
  • Verified. pi --session <path|id> resumes a specific session, by full file path or partial UUID, and accepts trailing prompt arguments. pi -c/--continue resumes the most recent session for the working directory; pi -r/--resume opens an interactive picker. pi --fork <path|id> forks a session into a new one instead of continuing it in place.

Native send to a live session

Section titled “Native send to a live session”
  • Verified (from the package’s docs/rpc.md). pi --mode rpc runs pi as a JSON-over-stdio protocol: prompt/steer/follow_up commands sent as JSON lines on stdin are delivered into that one running process, which streams typed events back on stdout. steer queues a message for delivery once the current tool calls finish; follow_up queues one for after the whole run settles — both require RPC mode already running.
  • Inferred. This is a send channel into a process the dispatcher itself spawned and holds stdin for — the same shape as Claude’s --input-format stream-json (see claude.md). It is not a way to reach a pi TUI that is already running as an independent process in some terminal: RPC mode is chosen at launch (--mode rpc), not attached to afterward. pi --help has no attach-by-pid or attach-by-session-id command that would make that possible.

Headless mode

Section titled “Headless mode”
  • Verified. pi -p/--print processes one prompt and exits, text mode by default. --mode json gives one-shot JSON output; --mode rpc is the standing, multi-turn headless protocol described above.

Orca identity value

Section titled “Orca identity value”
  • Verified (read agent-session-resume.js and agent-session-provider-handle.js in the installed Orca build; see ../hosts/orca.md). pi is a RESUMABLE_TUI_AGENT and TuiAgent, but it is not one of the two providers (claude, codex) with a structured AgentSessionProviderHandle — pi resumes through a plain argv build instead. Orca’s canonical resume argv is ['pi', '--session', transcriptPath]: it needs the hook’s reported session file path, not just the bare session id. Resume returns null (treated as unresumable) if only an id is known and no transcript path was captured.

Notable

Section titled “Notable”

pi ships its own docs/tmux.md, but it covers only keyboard-modifier forwarding (extended-keys-format csi-u) for running pi’s TUI inside tmux. It says nothing about tmux as a session-discovery or send mechanism for pi — that stays our own tmux host’s job (see ../hosts/tmux.md), not pi’s.

← Back to Notes