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 |
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 $HOME/.polygraph/config.json:
{ "multiplexer": "tmux"}In general, you don't need to set it — Polygraph 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>