---
# Multistack
Run multiple [zerostack](https://gi-dellav.github.io/zerostack/) agents side by side in your terminal, allowing to spawn, watch, rename, kill all underlying processes.
Multistack is designed to be a native, lightweight and open-soruce competitor to [Conductor](https://www.conductor.build).
## What it does
- **Spawn parallel agents**: each one gets its own PTY, running `zerostack --parallel` under the hood
- **Local and remote projects**: run agents in a local directory or on an SSH server, with the same keybindings and status tracking
- **Live status tracking**: see at a glance who's working `[~]`, done `[✓]`, dead `[X]`, waiting `[ ]`, or waiting on you `[?]`, with per-agent timers
- **Drop into any agent**: hit Enter on a process to see its full terminal output, keystrokes pass straight through
- **Status signal support**: multistack listens for zerostack's `start` and `stop` signals over Unix sockets, so timers and indicators stay accurate even across headless loop iterations, and for the protocol v1.1 `blocked:` and `state:working` signals, so an agent parked on its permission prompt shows as `[?]`, raises a desktop notification, and stops its timer until you answer
## Agent status
| Glyph | Colour | Meaning |
|-------|---------|---------|
| `[ ]` | gray | waiting, the agent hasn't started yet |
| `[~]` | yellow | working, the timer is running |
| `[?]` | cyan | waiting on you, answer the prompt inside the agent |
| `[✓]` | green | finished, `stop` signal received |
| `[X]` | red | dead, the process exited |
| `[!]` | magenta | git conflict, resolve it before quitting |
See [STATUS_SIGNAL.md](STATUS_SIGNAL.md) for the wire protocol behind these.
## Install
### Homebrew (recommended)
```bash
brew tap gi-dellav/tap
brew trust gi-dellav/tap # required for Homebrew 6.0.0+
brew install multistack # zerostack installed automatically
```
### Script
```bash
curl -fsSL https://raw.githubusercontent.com/gi-dellav/multistack/main/install.sh | bash
```
### Cargo
```bash
cargo install multistack
```
You need [zerostack](https://gi-dellav.github.io/zerostack/) on your PATH, plus a recent Rust toolchain.
## Remote projects
A project can live on an SSH server. Multistack keeps owning the UI and local
PTYs; each remote agent is a local `ssh` process running `zerostack` in the
remote directory. Worktrees, lazygit, `$SHELL`, setup, status signals and
timers all work the same way as for local projects.
Add one from the TUI with `P`, or at startup:
```bash
multistack --remote=deploy@buildbox:/srv/app
multistack --remote=buildbox:2222/srv/app --remote=user@other:/srv/other
```
The accepted form is `[user@]host[:port]/path` (or the equivalent
`ssh://[user@]host[:port]/path`). Paths must be absolute on the remote host.
Host aliases and options from `~/.ssh/config` are honored because multistack
shells out to the system OpenSSH client.
Remote status signals use OpenSSH Unix-socket forwarding
(`ssh -R remote_sock:local_sock`), so the server needs Unix-socket forwarding
enabled (`AllowStreamLocalForwarding yes`, the default). If the server disables
it, remote agents still run but their status stays `[ ]`.
Requirements on the remote host: zerostack (v1.5+ for status signals),
`lazygit`/`speck` if you use those actions, and a POSIX shell. Authentication
and host-key prompts appear inside the agent's TTY; press Enter on the agent to
answer them. To avoid repeated auth prompts across agents and tools, enable
`ControlMaster` in `~/.ssh/config`.
Use `--ssh-suffix` to pass extra flags to every ssh invocation:
```bash
multistack --ssh-suffix="-o ConnectTimeout=5" --ssh-suffix="-i /home/me/.ssh/build_key"
```
## Keybindings
### Agent list (normal mode)
| Key | Action |
|---|---|
| `n` | Spawn new agent — prompts for a name, creates a git worktree |
| `N` | Spawn new agent in parallel mode — no prompt, jumps straight to TTY |
| `m` | Spawn bare agent — no worktree, no `--parallel`, jumps to TTY |
| `p` | Add local project — opens directory picker |
| `P` | Add remote project — prompts for `[user@]host[:port]/path` |
| `l` | Remove project and all its agents |
| `h` | Open `lazygit` in the project (or agent worktree) directory |
| `s` | Open `$SHELL` in the project (or agent worktree) directory |
| `r` | Rename selected agent |
| `d` | Delete (kill) selected agent |
| `Enter` | Drop into the selected agent's TTY |
| `↑` / `↓` | Move selection |
| `PageUp` / `PageDown` | Jump to previous / next project header |
| `?` / `F1` | Scrollable help overlay (keybindings, statuses, tips) |
| `q` | Quit — shows confirmation with agent counts (`Enter` quits, `Esc`/`n` stays) |
| `Esc` | Quit (confirmation; git conflicts get a warning) |
### TTY view (agent / lazygit / shell)
| Key | Action |
|---|---|
| `Esc` | Return to agent list |
| *All other keys* | Forwarded to the underlying process |
### Prompt (new agent / rename / new project)
| Key | Action |
|---|---|
| `Enter` | Confirm |
| `Esc` | Cancel |
| `Backspace` | Delete last character |
| *Printable chars* | Append to input |
### Directory picker
| Key | Action |
|---|---|
| `Enter` | Add selected directory as a project |
| `Esc` | Cancel, return to agent list |
| `/` | Start filtering directories (type to narrow, `Esc` to clear) |
| *All other keys* | Navigate the file tree |
## Requirements
- **Linux/BSD/macOS** (uses Unix domain sockets and PTYs)
- **zerostack v1.5+** built with the `status-signals` feature (default from v1.5). The `[?]` state needs a zerostack carrying status-signal protocol v1.1; older builds simply never send those lines and behave exactly as before. Minimum version: TBD, to be filled in at zerostack's next release
- Rust 1.85+ (2024 edition)
## License
GPL-3.0-only