Run Pi subagents in tmux or Zellij

Start Pi inside a named terminal session, choose a visible child pane, and use the supervisor to inspect, focus, attach, and continue interactive work.

By lmn451 · Updated

Start Pi inside a named terminal session

Interactive subagents run as separate Pi processes in multiplexer panes. Start the parent Pi session from the project directory where you want the child to work. These instructions cover published pi-subagentura4.2.1; package metadata was verified2026-11-07. Install it first, then use one of these examples.

tmux

cd /path/to/project
tmux new -s pi-lab

The tmux new -s command creates a named session and attaches your terminal to it. At the shell prompt inside tmux, start Pi:

pi

To return to that session later, run tmux attach -t pi-lab.

Zellij

cd /path/to/project
zellij --session-name pi-lab

At the shell prompt inside Zellij, start Pi:

pi

To attach later, use zellij attach pi-lab. These commands only start the terminal environment and Pi; they do not spawn a child by themselves. For a temporary one-session install, launch Pi withpi -e npm:pi-subagentura instead.

tmux session guide· Zellij command-line options· Zellij attach command

Open a visible interactive child

Once the parent Pi session is running inside tmux or Zellij, ask Pi to start an interactive specialist for a focused task. For example:

Start an interactive specialist to inspect the routing code.
Open it in a visible pane, summarize the files it plans to inspect,
and keep the session open for a follow-up.

When Pi calls subagent_interactive, set itsbackground option to false for a side-by-side pane. The option defaults to true, which opens a detached named window or tab; it does not appear beside the parent until you focus or attach to it. The tool selects the active tmux or Zellij environment automatically. You do not need to pass a multiplexer startup flag.

If you launch the parent outside a multiplexer, the child can start in a detached session and return an attach command. The command returned by the tool is the reliable way to connect to that child; it includes the target session or terminal identifier.

Inspect, focus, attach, and continue

Open /subagents in Pi, or press Ctrl+Alt+A, to see async work and interactive children. Select a child and expand its details before using the interactive controls:

  • v captures a bounded terminal snapshot.
  • f focuses the child pane in the current multiplexer.
  • a shows the terminal-scoped attach command.
  • X cancels the selected child and its descendant subtree.

You can also ask the parent Pi agent to send the child a follow-up. The follow-up continues that child Pi session with its existing conversation context. Terminal input is another option: focus or attach to the child and type directly into its Pi prompt.

See the package README’s interactive subagent sectionfor the tool behavior and supervisor controls.

Know which context continues

An interactive child has its own Pi session. If you want it to see the parent conversation branch at launch, Pi can pass that context explicitly with the tool’s includeContext option. Otherwise, give the child the task details it needs; do not assume it has the parent’s full transcript. A follow-up sent to the same child continues the child’s own conversation.

Interactive child panes and their artifacts can rehydrate across reload, resume, and quit continuity transitions when you return to the matching parent session. Starting a fresh /new or /forkcleans up the interactive work owned by that previous session. In-process jobs and background workflows have different, session-scoped lifecycles. The child uses the project working directory by default; pi-subagentura does not create a Git worktree for it automatically.

Continue with the install guideor parallel review tutorial. See also the product overview,session walkthrough, andPi subagents overview.