10. Automate#

In this chapter you drive a running mpmux from a script: open panes, type into them, read their screen, and show messages. Agents can use the same commands.

The control socket#

A running mpmux listens on a local socket, $XDG_RUNTIME_DIR/mpmux.sock by default. mpmux-cli talks to it. If you run several instances, pick one with --socket or the MPMUX_SOCKET_PATH variable.

The commands follow tmux where it makes sense.

Build a layout#

mpmux-cli new-tab
mpmux-cli split-pane --direction right
mpmux-cli split-pane --direction down
mpmux-cli list-panes

Type and read#

mpmux-cli send-text 'cargo test'
mpmux-cli send-keys Enter
mpmux-cli capture-pane            # print the visible text of the active pane

send-keys takes tmux-style key names, for example C-c, Escape, or Enter. Most commands take --pane-id to target a pane other than the active one.

▶ watch the clip

Talk to the user#

mpmux-cli display-message 'Build finished'
mpmux-cli display-dialog 'Deploy' 'Tests passed. Ready to deploy.'

A script can also open the command palette or a pie menu, and answer them.

Ask and wait#

--wait makes a dialog block until the person answers. dismissed_by says how it closed:

mpmux-cli --json display-dialog 'Deploy?' 'Tests passed.' \
  --primary-label Deploy --wait | jq -r .data.dismissed_by
# primary-button or enter: confirmed; escape or close-button: declined

React to events#

Instead of polling in a loop, register as a client, subscribe to events, and wait for the next one:

mpmux-cli --client-id bot attach --name "build bot"
mpmux-cli --client-id bot acquire-control
mpmux-cli --client-id bot subscribe dialog-state-changed ui-state-changed
mpmux-cli --client-id bot wait-for-events      # blocks until something happens

Once a client is attached, only the client holding control may change the window; pass --client-id with every command, and release-control and detach when done. Details: mpmux-cli reference.

Build your own tools#

Scripts and agents can add dialogs with fields and buttons, and sidebars with lists, inside mpmux. The todos sidebar from chapter 6 is built this way. A dialog can also show Markdown, links that report an action, and chips for a status or tags; the parts are listed under show-custom-dialog in the host-control reference. See extension architecture.

▶ watch the clip

The full list#

The mpmux-cli reference explains every command group with examples and recipes. mpmux-cli --help and mpmux-cli <command> --help show the options; all of them are also in command-line help.

Next#

Chapter 11 runs small interactive programs in the Viewer.