Polygraph coordinates work across multiple repositories by spawning one child agent per repo. Running a session inside a modern terminal or terminal multiplexer opens each child agent in its own pane, so you can watch all of their live logs side by side.
Polygraph detects and configures your terminal automatically, but you can pass the --multiplexer flag to override the behavior.
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 |
herdr | herdr |
windows-terminal | Windows Terminal |
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>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 the default multiplexer in the polygraph config editor: the Multiplexer setting lives in the General section, and Enter or Space cycles through the choices. You can also set the key in $HOME/.polygraph/config.json directly:
{ "multiplexer": "tmux"}When the setting is unset, Polygraph asks at session start. In general, you don't need to set it — auto detects your terminal automatically.
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>