Section 1
1.Overview
- Parallel agents — each one gets its own PTY, running
zerostack --parallelunder the hood - Live status tracking — see at a glance who’s working
[~], done[✓], dead[X], or waiting[ ], with per-agent timers - Drop into any agent — hit Enter to see its full terminal output, keystrokes pass straight through
- Status signals — listens for
start/stopover Unix sockets, so timers stay accurate across headless loop iterations - Git worktree per agent — branch-per-task workflow, spawned with a single keypress
- Projects — group agents by directory, jump between headers with PageUp/PageDown
- lazygit & shell — open
lazygitor$SHELLin the agent worktree without leaving the TUI - Desktop notifications — finished agents and git conflicts notify you even when you look away
Section 2
2.Other Projects
From the same author — the agent that multistack manages:
zerostack → Minimal AI coding agent for the terminal, written in RustSection 3
3.Live Status
Every agent reports its lifecycle over a Unix socket — the list stays accurate even while agents iterate headlessly:
| Indicator | State | Meaning |
|---|---|---|
[ ] | waiting | Spawned, no work observed yet |
[~] | working | Agent is running — the timer accrues |
[✓] | finished | Agent completed — desktop notification fired |
[X] | dead | Process exited |
[!] | git-conflict | Needs your attention — resolve the git conflict |
Timers freeze the moment an agent stops or conflicts, so the displayed time is time actually worked. Press Esc twice to quit while conflicts are pending.
Section 4
4.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 project — opens directory picker |
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 |
PgUp / PgDn | Jump to previous / next project header |
q / Esc | Quit (Esc twice if agents have git conflicts) |
TTY view (agent / lazygit / shell)
Esc — Return to agent list
all other keys — Forwarded to the underlying process
Prompt (new agent / rename / new project)
Enter — Confirm
Esc — Cancel
Backspace — Delete last character
printable chars — Append to input
Directory picker
Enter — Add selected directory as a project
Esc — Cancel, return to agent list
/ — Filter directories (type to narrow, Esc to clear)
all other keys — Navigate the file tree
Section 5
5.Documentation
- README.md — Installation, keybindings, and requirements
- ARCHITECTURE.md — Project architecture and design decisions
- STATUS_SIGNAL.md — Agent↔UI status socket protocol
Section 6
6.Quick Start
# Homebrew (recommended — zerostack installed automatically)
brew tap gi-dellav/tap
brew trust gi-dellav/tap # required for Homebrew 6.0.0+
brew install multistack
# Launch the TUI
multistack
# p — add your project, n — spawn an agent,
# Enter — drop into its TTY, Esc — back to the listYou need zerostack on your
PATH, plus a recent Rust toolchain.Section 7
7.Requirements
- Linux / BSD / macOS — uses Unix domain sockets and PTYs
- zerostack v1.5+ — built with the
status-signalsfeature (default from v1.5) - Rust 1.85+ — 2024 edition
Section 8