cmux Pane Orchestration

You have access to cmux tools for managing terminal panes. Use them to run parallel processes, monitor output, and interact with other terminals.

Available Tools

Tool	Purpose
cmux_list	List all surfaces (panes) and workspaces
cmux_split	Split pane right or down, optionally run a command
cmux_read	Read terminal output from another pane
cmux_send	Send text or keystrokes to another pane
cmux_close	Close a pane
cmux_notify	Send desktop notification
cmux_browser	Open/navigate/snapshot/click/fill/eval in built-in browser

Common Patterns

Dev server + coding workflow

1. cmux_split direction="down" command="npm run dev\n"
2. Note the surface ID from the result
3. Work on code in your main terminal (edit files, etc.)
4. cmux_read surface="surface:X" to check dev server output
5. cmux_close surface="surface:X" when done

Parallel test watching

1. cmux_split direction="right" command="npm test -- --watch\n"
2. Edit code in main pane
3. cmux_read surface="surface:X" to check test results
4. If tests fail, read the output and fix the code

Sub-agent spawning

1. cmux_split direction="right" command="pi \"Task description here\"\n"
2. Continue working on your own task
3. cmux_read surface="surface:X" to check sub-agent progress
4. cmux_close surface="surface:X" when sub-agent finishes

Web preview with browser

1. Start dev server: cmux_split direction="down" command="npm run dev\n"
2. Open browser: cmux_browser action="open" url="http://localhost:3000"
3. Get DOM: cmux_browser action="snapshot" surface="surface:X" compact=true
4. Interact: cmux_browser action="click" surface="surface:X" selector="button.submit"
5. Fill form: cmux_browser action="fill" surface="surface:X" selector="input[name=email]" value="test@example.com"

Stopping a process in another pane

1. cmux_send surface="surface:X" key="ctrl+c"
2. Wait a moment, then cmux_read to confirm it stopped

Guidelines

• Always cmux_list first if you don't know the surface IDs
• Append \n to commands in cmux_split and cmux_send to execute them
• Read before assuming — use cmux_read to check what happened in other panes
• Clean up — close panes you no longer need with cmux_close
• Don't close your own pane — only close panes you created
• Notify on completion — use cmux_notify for long-running tasks so the user knows
• Surface IDs are like surface:2 — use the exact format from cmux_list or cmux_split results