muster-workspace 0.1.0

A terminal workspace for running CLI agents and dev processes side by side
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

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

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

From a source checkout:

```sh
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.

```yaml
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:

```sh
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

Single user, Unix only.