Polygraph coordinates work across multiple repositories by spawning one child agent per repo. Running a session inside a terminal multiplexer opens each child agent in its own pane, tab, or window — so you can watch all of their live logs side by side, rather than attaching to each one separately.
Polygraph works much better in multiplexer mode, where you can see all child logs side by side.
Supported multiplexers
Section titled “Supported multiplexers”Polygraph supports the following choices for --multiplexer:
| Choice | Description |
|---|---|
auto | Default. Detects the best available option for your environment. |
tmux | tmux |
iterm2 | iTerm2 (macOS) |
kitty | kitty terminal |
ghostty | Ghostty terminal |
cmux | cmux |
zellij | Zellij |
none | Disable multiplexer support. |
Enable a multiplexer
Section titled “Enable a multiplexer”On a new session
Section titled “On a new session”Pass --multiplexer (alias -m) when starting a session:
polygraph session start --multiplexer <choice>The default is auto, which picks the best available option for your environment.
On an existing session
Section titled “On an existing session”To bring an existing session into a multiplexer, resume it with the flag:
polygraph session resume --multiplexer <choice>This is how you add multiplexer support to a session that was started without one.
As a default
Section titled “As a default”Set multiplexer in the Polygraph config so every session uses it without passing the flag each time:
polygraph config set multiplexer tmuxIf the selected multiplexer is not installed or configured correctly, Polygraph prints a warning and continues without one for that run.
View child agent logs without a multiplexer
Section titled “View child agent logs without a multiplexer”When no multiplexer is active, attach to a single child agent's live logs with:
polygraph agent attach -s <sessionId> -r <repo>When you start a session without a multiplexer, the session welcome card lists these agent attach commands under a View child agent logs section — one per repo in the session.
Switch to a multiplexer later
Section titled “Switch to a multiplexer later”You do not need to restart from scratch. Exit the current agent session and resume it with a multiplexer:
polygraph session resume --multiplexer autoPolygraph reconnects to the session and opens each child agent in its own pane, where you can see all logs side by side.