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.

Status: Beta

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.

Demo

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.
• First-class agent sessions can be launched from presets, named automatically, closed into history, resumed, and restored with their workspace. Terminals and commands can be added persistently without leaving the app.
• A failed process raises an alert visible from any pane.

Getting started

Requires a recent Rust toolchain.

cargo install muster-workspace
muster init                  # scaffolds a starter muster.yml here and registers it
muster                       # starts the TUI on a local or registered workspace
muster hooks setup           # enables native session discovery for agent CLIs

From a source checkout:

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

Without --config, muster uses $MUSTER_PROJECT when launched from one of its panes, then ./muster.yml when present, then the first project in the global registry. This means a registered workspace can be launched from any directory. Registry config paths are stored as absolute paths. Legacy relative entries are not supported during beta because resolving them from another directory is unsafe. Convert or remove them directly in the global projects.yml registry.

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 closes an agent session into history or removes the selected saved project
• u reopens the most recently closed agent session
• 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

Entries under agents are pinned workspace processes. They persist in muster.yml and use the normal start, stop, restart, and autostart controls.

Press a, choose agent, then select Claude, Codex, Gemini, Amp, OpenCode, Copilot, Kimi, or Custom to launch a first-class agent session. Enter launches a known preset immediately with a generated human name; e opens the advanced form for a custom name, command, and resume command. Sessions never modify muster.yml. Closing one with d or C-a d moves it into history, and u resumes the latest closed conversation. Open resumable sessions return when the workspace is opened again. If a provider ID was not captured, the session returns as a stopped row so d can close it without starting a new conversation.

Run muster hooks setup once to install the provider lifecycle integrations that capture native conversation IDs. Setup is explicit and idempotent, and OpenCode's plugin is installed under its XDG configuration root. Provider conversation switches update the durable resume target. OpenCode captures only the active top-level conversation, ignoring child and background session metadata. Caller-assigned IDs are not treated as resumable until the provider confirms them. Muster also exposes a versioned agent event protocol so new agents can integrate without screen scraping or a Rust dependency.

Agent activity detection follows the selected tool. Codex, Gemini, and Amp use terminal-title changes; the other presets use visible output. Terminal progress, bells, and notification sequences still provide explicit working or waiting signals for every preset.

The left dot always shows process lifecycle. A working agent also gets a cyan animated marker at the right edge, while any process that explicitly requests attention gets a yellow !. Ordinary command and terminal output adds no second marker.

• 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.

The CLI

Beyond the TUI, muster ships workspace commands:

muster init                  # scaffold a starter muster.yml and register the folder
muster check                 # validate the config; exits non-zero for CI and hooks
muster projects              # list registered projects; add/remove subcommands
muster completions zsh       # print the shell hook enabling tab completion
muster doctor                # diagnose config, projects, sessions, hooks,
                             # clipboard, and completions

On a terminal the commands render as styled reports in the TUI's visual language; piped or under NO_COLOR they emit plain line-per-fact output for scripts.

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.