muster

A terminal workspace for running CLI agents and dev processes side by side.

muster runs your agents, dev servers, log tails, and build watchers as panes in a single terminal and manages their lifecycle: start, stop, restart, and auto-restart on failure.

It's been my daily driver for running local work for a while. This is the cleaned-up cut I opened up, done with help of the AI.

Features

Runs each process under its own PTY and renders it live. A process that exits keeps its last screen.
Full lifecycle control: start/stop, restart, force-kill, pause/resume (SIGSTOP/SIGCONT), command-level graceful shutdown, and auto-restart on failure.
A projects tree in the sidebar for switching between workspaces.
Live config reload: edits are reconciled into the running workspace, adding new processes and dropping removed ones while leaving running ones untouched.
Processes can be added and autostart toggled directly from the TUI.
A failed process raises an alert visible from any pane.

Getting started

Requires a recent Rust toolchain.

cargo install muster-workspace
muster                       # starts the TUI on ./muster.yml

From a source checkout:

cargo run                     # starts the TUI on ./muster.yml
cargo run -- --config my.yml  # use a different config

Press ? in the app for the full keymap:

j/k or arrows to move, Enter/l to open, h to go back
s start/stop, r restart, p pause, x force-kill, t toggle autostart
a add a process, n new project, o switch projects, d remove a project
C-a detaches from a focused pane; the same commands work as C-a chords while attached
q to quit

Configuration

A workspace is a YAML file with three sections: agents, terminals, and commands. The grouping controls how processes appear in the sidebar. Commands can additionally opt into graceful shutdown.

agents:
  - name: claude
    command: claude
    description: coding agent
    autostart: false

terminals:
  - name: shell
    command: null          # null runs your login shell
    description: your login shell

commands:
  - name: clock
    command: while true; do date +%T; sleep 1; done
    restart: on_failure
    stop:
      signal: terminate
      grace_period: 5s
    autostart: false

autostart: null uses the default (agents and terminals start with the workspace, commands wait for s), or set true/false explicitly. Toggle it live with t.
restart: never, on_failure, always, or null to never restart.
working_dir: launch directory; inherits the workspace directory when null.
stop: optional and valid only on commands. Commands default to terminate (SIGTERM) with a 5s grace period. Set both signal (terminate or interrupt) and a human-readable grace_period such as 5s or 1m to override that policy.

For commands, s and r send the effective graceful signal to the whole process group, wait for its grace period, then use SIGKILL if it is still alive. x always force-kills the selected process immediately. Agents, terminals, project switches, and quitting always use immediate kill.

muster run

muster run registers a command into a project and runs it in place, without opening the config:

muster run -- npm run dev
muster run --name api --kind terminal -- cargo watch -x run

The target is --project if given, otherwise $MUSTER_PROJECT (exported into every pane), otherwise --config. Shell quoting is preserved and --project has tab completion.

Status