Split panes

imux layouts follow workspace → pane → surface. Each workspace is one project or remote host; inside it you split panes horizontally or vertically and host terminals, browsers, or other panels. Ghostty renders terminal surfaces; Bonsplit manages the split tree.

Layout model

Targeting for automation (socket API, browser, Agent Chat) resolves window → workspace → pane → surface. Keep this chain in mind when scripting.

Workspace — one root folder or SSH host
Pane — split container (horizontal / vertical)
Surface — terminal UUID, browser tab, or embedded panel
Active surface — receives keyboard unless a focus command says otherwise

Split from the UI

Use the pane toolbar or workspace menu to split the current terminal. Drag dividers to resize. Close a pane when its surfaces are no longer needed.

Split from icc

The bundled icc CLI can split panes without stealing focus when you use non-focus socket commands.

# Examples (require running imux + icc on PATH)
icc pane split horizontal
icc pane split vertical
icc surface list

Focus policy

Automation must not yank focus unless you explicitly send a focus command. Status polls, snapshots, and inject keystrokes to a background surface stay non-activating.

Non-focus commands — telemetry, read surface text, queue input
Focus commands — activate app, select window/workspace/pane/surface
Agent Chat and supervisor respect the same rule

Troubleshooting

Split and focus issues usually come from session restore or automation commands that activate the app.

Split missing after restore — session snapshot may omit closed panes; recreate split
Wrong surface receives keys — check active surface id via icc surface list
Focus stolen during script — remove focus flags from socket commands