volee

See, launch and coordinate every coding agent on your machine, from your terminal.

Early development. volee is being built in the open. Pages marked planned describe behavior that is designed (see the decisions) but not released yet.

The problem

Coding agents made parallel work cheap. Running five of them is easy; keeping track of them is not:

• Which ones are still working, which one waits for a permission, which one finished an hour ago?
• Which worktree and branch does each one use, and was its work pushed?
• When two agents coordinate through a third one, what did they agree on?

Terminal tabs and multiplexer panes show where agents run, not what they do. volee shows what they do.

What volee gives you

• One screen for every agent on the machine, grouped the way the work is organized: a lead, its missions, their workers and subagents.
• Urgency first: questions and permission prompts float to the top.
• Delivery at a glance: commits since the agent started, pushed or not, pull request, checks.
• Conversations you can follow: typed, threaded messages between agents and with you, and a live graph where each message travels along its edge.
• Missions: give a goal across several repositories to a coordinator agent; volee supervises its workers and checks that the work was delivered.
• Every screen, exactly: each agent volee launches runs in a volee host that holds its terminal, so its preview is its live screen, and a wall shows the screens of every agent that runs, hosted by volee or not. The agent survives closed windows, the interface and the daemon, and comes back after a reboot.
• Your terminal, your tools: open an agent with a key, type into it inside volee and come back with Ctrl+Q; open its worktree in your editor, your diff viewer or your git interface. None of them is required, and no multiplexer either; a session you started in a tuios or tmux pane is shown and reached there.
• Claude Code and OpenCode: volee launches agents of both, and shows the ones started elsewhere. A Claude Code session you started yourself opens where it runs, in the background or in a tuios pane, with nothing stopped or restarted; the list is what runs now.
• Any other AI, from your terminal: volee run -- <command> runs any program under volee. Your terminal is on it at once, and it is listed, shown and opened like the others (Agents of other harnesses).
• Worktrees ready to work: your setup commands, such as bun install, run in each new worktree before its agent starts.

Where to go next

• Installation
• Getting started: your first agent and your first mission, in about ten minutes.
• Concepts: agents, sessions, roles, missions, messages.
• Architecture overview, for contributors and the curious.

Installation

Requirements

• macOS (Apple Silicon or Intel) or Linux (x86_64 or ARM64).
• Claude Code 2.1.319 or later, for the agent features (background sessions, claude agents --json, permission modes). claude update brings it up to date.
• git 2.40 or later.
• Optional: the GitHub CLI (gh), signed in with gh auth login. With it, volee shows the pull request opened from each agent’s branch and the state of its checks, and the mission supervisor can count an open or merged pull request as delivered work. Without it, everything else works and volee daemon status says why pull requests are not shown. volee uses your own sign-in and never sees a token.

With the installer

The latest release of volee is v0.17.0. Every release on GitHub comes with prebuilt binaries and an installer script. To install the latest release:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/volee-org/volee/releases/latest/download/volee-cli-installer.sh | sh

The script picks the archive for your machine, checks its SHA-256 checksum and installs the volee command into ~/.local/bin (or $XDG_BIN_HOME when it is set). If that directory is not on your PATH, the script adds it to your shell profile: open a new terminal afterwards.

To install a specific version, put its tag in the URL:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/volee-org/volee/releases/download/v0.1.0/volee-cli-installer.sh | sh

You can also download an archive from the release page yourself, check it against its .sha256 file and put volee anywhere on your PATH:

The Linux binaries need glibc 2.35 or later (Ubuntu 22.04, Debian 12, Fedora 36 or newer). On other Linux systems, such as Alpine, install from source.

Shell completions

volee completions <shell> prints a completion script for bash, elvish, fish, PowerShell or zsh. Put it where your shell looks for completions:

volee completions fish > ~/.config/fish/completions/volee.fish
volee completions zsh > "${fpath[1]}/_volee"      # or any directory on your fpath
volee completions bash > ~/.local/share/bash-completion/completions/volee

Run it again after an upgrade, so new commands complete too.

From source

Install with Cargo (Rust 1.90 or later and Zig 0.15.2):

cargo install --locked --git https://github.com/volee-org/volee --tag v0.17.0 volee-cli

Replace v0.17.0 with the release you want, or leave --tag out to build the latest commit of main. The volee command goes into ~/.cargo/bin. CONTRIBUTING.md says how to install Zig 0.15.2 (on macOS, Homebrew’s zig@0.15).

Check the installation

volee --version

Update

Run the installer again, or the cargo install command with the new tag.

Uninstall

Remove the volee command the way you installed it:

rm ~/.local/bin/volee          # installed with the installer
cargo uninstall volee-cli      # installed with Cargo

Then remove volee’s configuration and state:

rm -rf ~/.config/volee ~/.local/state/volee

The worktrees volee created stay in their repositories, under .claude/worktrees/. Before you uninstall, remove the ones whose work landed with volee tidy --all, and any other with git worktree remove <path> once you no longer need its changes. Their branches stay in your repositories either way.

Getting started

This walk-through takes about ten minutes. It assumes volee is installed (see Installation) and that you already use Claude Code.

1. Check that volee finds Claude Code

volee daemon start
volee daemon status

Other commands start the daemon on their own when they need it; here it is started by hand, because volee daemon status only reports. The status names the Claude Code version it found, and whether gh is there to read pull requests. If Claude Code is missing or too old, the line says why. Right after the start, the forge line may say gh not checked yet: volee checks gh in the background, so ask again a few seconds later.

2. See every agent on the machine

volee

The interface opens on every Claude Code session and every OpenCode agent running on this machine, whoever started it: in a terminal, in the background, or launched by another agent. The ones that need you come first. Press ? for the keys; q quits without stopping anything. volee ls prints the same list without the interface.

Nothing here depends on how you started the sessions: volee reads Claude Code’s own list of sessions, looks for OpenCode in the process table and asks tuios which of its panes run another AI, such as Codex CLI or Gemini CLI (at once when the interface opens, then every two to ten seconds while it is open, more often while sessions change, and every thirty seconds otherwise), and it hears the hooks of the agents it launches itself, which report at once. The list is what runs now: a session you close leaves it after a minute, a background session stays for as long as Claude Code keeps it, and a session started outside volee shows once it has lived ten seconds.

Press enter on any of them, or double click it: volee opens it where it runs, in a terminal inside the interface, and you type there (step 5).

3. Tell volee about your repositories

volee config init
$EDITOR "$(volee config path)"

Add one table per repository you want volee to launch agents in:

[repos.billing]
path = "~/code/billing"
base = "main"

Then run volee config check. Claude Code works only in folders you trust, and each repository counts on its own: if you have never run claude in a repository, do it once and accept the trust prompt before you launch an agent there.

4. Launch an agent

volee spawn billing feat/invoices "Add an invoice model with its migration and tests." --name invoices

volee creates the branch feat/invoices from main, checks it out in a new worktree at billing/.claude/worktrees/feat-invoices, and starts Claude Code there with your task, in a volee host: a small process that holds the agent’s terminal, so the agent keeps running when you close the interface, the terminal or the daemon. The agent appears at once as invoices, with its repository and branch (without --name, it would be called billing-feat-invoices). Your own checkout is never touched. Add --harness opencode to start OpenCode instead.

The agent runs in Claude Code’s manual permission mode unless you choose another in the configuration: when it needs a permission, it shows up as needing you, and you answer by taking it over.

5. Talk to it, or take it over

volee msg send invoices "Use cents, not floats, for amounts."
volee attach invoices       # Ctrl+Q comes back
volee diff invoices         # what it changed so far
volee stop invoices         # stop it; its conversation is kept

A message reaches the agent at the end of its turn, wakes it if it is idle, and resumes it in a new host if it stopped. volee attach hands your terminal to the agent, from any terminal; Ctrl+Q returns to where you were, and the agent keeps running. In the interface, enter opens the agent inside volee and sends it your keys until Ctrl+Q, z shows its screen full size, and 5 shows the screens of the agents that run, side by side. After volee stop, volee does not resume the agent on its own, even when other agents write to it: your next message to it does.

The sessions you started yourself open the same way, where they run, and stay what they are: enter (or volee attach) on a background session runs Claude Code’s own claude attach on it, and enter on a session in a tuios pane shows that pane. Nothing is stopped or restarted, and Ctrl+Q leaves the session running as it was. Messages are for the agents volee launched: to say something to another session, open it and type.

A Claude Code session you typed in a terminal of its own, in a tab of any terminal application, is held by that terminal: nothing else can show it. enter on it says which key to press there, the left arrow on its empty prompt, which has Claude Code move the conversation to the background, and volee opens it by itself once you pressed it, on the same row.

volee adopt <agent> (A in the interface, which asks first) is for a session you want volee to drive from now on: it stops the session and resumes its conversation in a volee host, with volee’s settings, where it receives messages and comes back after a reboot.

6. Run a mission

volee mission new "Invoicing" \
  "Add invoices to billing and expose them in the API, with tests." \
  --repo billing --repo api
volee mission show invoicing

A coordinator agent plans the work in the first repository, without editing it, and launches one worker per task, each in its own worktree of one of the mission’s repositories (eight at most, unless you raise [missions] max_workers). When a worker stops, volee checks its work itself: commits pushed and a pull request open for a change (commits alone in a repository without a remote), a report sent for an analysis. The coordinator hears every verdict and asks workers to finish what is missing.

Once every worker delivered, the coordinator merges nothing and closes nothing: it presents its report, and asks you. The question waits on top of your messages (I), and the mission shows as waiting for you:

coordinator-invoicing → you · question
Mission "Invoicing" is ready to merge.
Done: invoices in billing, exposed in the API.
Proof: billing#42 and api#17, tests green.
Left: nothing
  1 ok merge
  2 no

Press 1 then y (or run volee msg answer coordinator-invoicing 1): volee merges each worker’s work itself, its pull request on GitHub, or its branch into the base branch in a repository without a remote, and the mission closes. No agent merges. Closing tidies the mission in one gesture: the workers’ worktrees are removed, their branches kept, the coordinator stopped, and one message tells you what is merged, what was tidied and what was kept, with the reason. On no, or on an answer in your own words, nothing is merged and the mission stays open. If a merge cannot go through (a required review is missing, your main checkout has uncommitted changes), nothing is forced: volee tells you why, and the coordinator presents its report again once it is settled.

volee mission ls --all
volee mission abort invoicing --reason "wrong approach"   # nothing is deleted

7. Or talk to a lead

cd ~/code
volee lead

A lead is the agent you talk to: it launches the others. volee lead starts one in the current directory and opens it in your terminal; Ctrl+Q leaves it running, and enter on its row in the interface, or volee attach, comes back to it. Tell it what you want in your own words:

Add invoices to billing and expose them in the API, with tests.

It looks at what already runs, launches an agent for a task in one repository or a mission for several, tells you in one line what it launched, and gives the hand back. It never codes, and it does not watch its agents: volee wakes it when one reports, and it tells you in three lines what is done, the proof and what is left. Before a merge you are asked, as in the section above: the question waits in your messages (I), not in the lead’s conversation. A lead never answers for you, even when you tell it your answer: it tells you where to give it.

You can also write to a lead without opening it, with m on its row or volee msg send <lead> "...": it takes that as what you say.

volee lead "Add invoices to billing and to the API." starts it with the request at once.

After a reboot

A reboot ends every host, but not the conversations: the first time the daemon starts afterwards, it resumes each agent the reboot interrupted in a new host, in its worktree: one that was working is told that the machine restarted, one that waited at its prompt comes back waiting. Agents you stopped, agents of a finished mission and agents that were done stay as they were. To have the daemon start at login, so that agents come back without opening volee, run once:

volee daemon install

What volee never does

• It never deletes a branch, and never removes a worktree whose work is not delivered.
• It never edits your Claude Code settings: the agents it launches get their hooks and tools on their own command line.
• It never resumes an agent you stopped until you write to it, and never resumes the agents of a finished mission.
• It never stops, restarts or reconfigures a session it did not start: it opens it where it runs, and what you type there is yours. Only volee adopt, which asks, moves one into a volee host.
• It never installs anything that starts at login unless you run volee daemon install.
• It never forces anything on you: no multiplexer, editor or git client is required.

Next: Concepts explains the words used here, and The interface every view and key.

Concepts

volee uses a handful of words with precise meanings. Knowing them makes the interface and the documentation easier to read.

Agent

A unit of work done by an AI coding harness, such as a Claude Code session fixing a bug in one repository. An agent has:

• a role (below);
• a workspace: repository, worktree, branch and the base branch it started from;
• a state: working, needs you, idle, done, failed, or lost;
• a parent (the agent that launched it) and, optionally, a mission.

An agent is not a terminal pane and not a process. If you close every window, the agent is still there. If its session is resumed or forked, it is still the same agent, with its history.

Session

One run of a harness, such as a Claude Code session with its session id. An agent has one current session and keeps the lineage of the previous ones.

Roles

Mission

A goal that spans one or more repositories, run by a coordinator and delivered by workers. A change mission delivers branches and pull requests; an analysis mission delivers reports. volee’s supervisor checks delivery evidence before a mission is considered done.

Message

A typed note from one party (you, an agent, or volee itself) to others: question, answer, contract, report, alert or note. Messages are grouped in threads (one per mission, one per pair of agents, and your inbox) and can point at a file and line, a commit or a pull request.

Delivery evidence

What volee can prove about an agent’s work: commits since it started, branch pushed, pull request opened or merged, checks passed, report delivered. Cleanup commands rely on evidence, never on the absence of a window or a process.

volee keeps this evidence current by itself, for the sessions you started without volee too: it reads git in each agent’s directory, fetches the repositories of the agents it launched (git fetch --prune origin, at most every five minutes; the [git] fetch setting decides which repositories, or none) and, when the GitHub CLI is signed in, asks it about each agent’s branch at most once a minute. A fetch only updates your remote-tracking branches. See Git.

The interface

volee opens one screen that shows every agent on your machine and what it needs from you. To try it without any agent running, start the demo, a simulated team of agents that changes every few seconds:

volee demo

Starting volee

volee

volee with no command connects to the daemon, starting it in the background when it does not run yet, and shows every agent it knows: the agents volee launched itself, each in its volee host, and the Claude Code sessions and OpenCode agents it finds on the machine, wherever they were started. The daemon looks for sessions as soon as the interface opens, then while it stays open every two seconds after a look that found something new, slowing down to every ten seconds while nothing changes (every thirty seconds when no interface is open). A session started elsewhere therefore shows up within ten seconds at worst, and changes come in quick succession after that; agents volee launched show up at once, through their hooks. Nothing needs to be configured first.

Everything on the screen comes from the daemon, and so do the actions:

When the daemon cannot do something, because Claude Code or git is missing, because the agent runs in a terminal of its own, or because the daemon is older than the interface, volee says so in a sentence where the result would be, such as “No preview: dashboard runs in a terminal of its own: switch to that terminal to see or control it”, and goes on working. With no agent yet, the views say how agents get there; when the daemon cannot use Claude Code at all (missing, or too old), they say so instead, and volee daemon status says why. If the daemon stops while volee runs, the top bar shows offline and the screen stops changing; start volee again to reconnect.

The theme, the keys and reduced motion come from the [tui] table of the configuration, as for the demo.

Layout

 volee  1 Tree  2 Network  3 Repos  4 Timeline   ? 2 · ! 2 need you · ▸ 6 working · lead 1 · coordinators 2 · workers 5 · PR 1
╭ Agents ─────────────────╮╭ Tree · tower · cards ──────────────────────────────────────╮╭ For you · 3 ─────────────╮
│ LEADS                   ││                 ╭─ tower ──────────── opus ⠹ ─╮            ││ ? invoice-tools          │
│ t ▸ tower        24 min ││                 │  WORKING  24 min            │            ││   Should create_invoice …│
│ n ├ · invoicing  14 min ││                 ╰──────────────┬──────────────╯            ││ ! invoice-schema         │
│ s │ ├ ! invoice-…  2 min││      ┌─────────────────────────┴─────────────────┐         ││   Bash: bun run db:migra…│
│▌v │ ├ ! invoice-…  1 min││ ╭─ invoicing ────────╮               ╭─ latency-audit ────╮  │╰──────────────────────────╯
│ BY HAND                 ││ │ ◆ Invoicing · chan…│               │ ◆ Latency audit …  │  │╭ Journal ─────────────────╮
│ i · infra        25 min ││ ╰────────────────────╯               ╰────────────────────╯  ││  2 min invoice-schema ! …│
╰─────────────────────────╯│   (the workers' cards, side by side)                       ││  1 min invoice-tools ? y…│
╭ Detail ─────────────────╮│                                                            ││  40 s trace-gateway → e… │
│ invoice-tools · worker  ││                                                            ││                          │
│ ! needs you · for 1 min ││                                                            ││                          │
╰─────────────────────────╯╰────────────────────────────────────────────────────────────╯╰──────────────────────────╯
╭ Preview · invoice-tools ─ NEEDS YOU  1 min · Bash bun test … ──── enter  open   m  message   d  diff   z  full screen ─╮
│ ⏺ Before I go on, one question:                                                                                       │
│   Should create_invoice accept a draft flag?                                                                          │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
  VOLEE    I  messages    /  filter    ␣  more    :  commands    q  quit                                          ?  help

• Top bar. The views, numbered (press the number to switch; 5 opens the wall of screens over the whole terminal), and counters: questions waiting for your answer (?) and unread messages (✉) when there are any, how many agents need you and how many work, then the agents by role (leads, coordinators, workers, subagents, the sessions on their own) and the pull requests open. A narrow terminal keeps the first counters only.
• Agents. Every agent, one row each, its tree under its root, the roots grouped by kind: LEADS, MISSIONS (missions you started without a lead), BY HAND (sessions you started in a terminal tab or a tuios or tmux pane) and BACKGROUND (what runs with no window: Claude Code background sessions, and agents in a volee host), the most urgent first in each group. Each row shows the agent’s jump letter, its place in its tree, its state, its name in its color, and how long it has been in that state when the name leaves room for it. volee opens on the agent that needs you most.
• View. What the tab shows: the tree of who launched whom, the network of who talks to whom, the repositories with their worktrees and what agents delivered, or the timeline of what happened when. The selected agent is the same in every view and in the list.
• Detail. Under the list, facts about the selected agent: role, state and since when, its mission and the mission supervisor’s verdict on its work, repository and branch, worktree, where it runs (volee host, background, a pane such as tuios · work, or a terminal) and with which model, whether it is held (you stopped it, or its mission is over: volee will not resume it on its own), delivery evidence, last activity and session.
• For you. From 160 columns, at the right: what waits for you, the questions agents asked you that nobody answered, oldest first, then the agents that wait for you (a permission, a dialog), each with what it asks. A click selects the agent; I opens the messages to answer.
• Journal. Under it, what happened lately, newest at the bottom, with how long ago: who launched whom (→), who wrote to whom (✉, ? for a question), who needs you, who finished or failed, who left the list.
• Preview. Across the bottom, the selected agent: on the panel’s border, its state as a badge, for how long and what it does, and at the right the keys of what you can do with it (open it, write to it, its changes, its screen full size). Inside, its terminal screen, kept up to date. For an agent volee does not host, volee reads it again every two seconds while the agent works and every five seconds while it rests: a screen changes at rest too, when you type in its pane or when the last lines of a turn land late. An agent that ended keeps the screen it left. For an agent in a volee host, it is the exact screen the host holds, followed live, status line and prompt frame included, drawn at the agent’s own size: looking at an agent never resizes it. The preview, the full-screen view and the agent’s tile on the wall show the same cells of that screen, its cursor and its blank rows included. The bottom of the screen, where the latest output is, stays in view; scroll it with j and k when the panel has the keyboard. Lines wider than the panel are cut at its edge. z shows that screen full size, its whole conversation in view, from its newest lines: lines wider than the window go on over several lines, between words where they can, so that nothing is cut but the padding and frames the agent’s interface draws to its own edge. For an agent in a volee host, that view is live: volee watches the host and draws each change as it comes. j and k scroll it, enter types into the agent (edit mode), and z or esc comes back. For a session in a tuios or tmux pane, the screen is the pane’s, row for row, as its multiplexer captures it. A Claude Code background session that volee does not host (one that volee 0.7 launched, or a claude --bg you started by hand) is replayed from claude logs, which keeps only the session’s recent output: in a session that has run for hours, parts of the screen drawn long ago and never redrawn since, such as a list that has not changed, can show gaps. A recent session shows whole. A background session draws its conversation at the top of its terminal and its prompt at the bottom: so that the end of the conversation stays in view, the preview and the wall show a run of three blank rows or more as one dim row that says how many it stands for (⋯ 12 blank rows ⋯). z shows every row of the screen, and opening the session (enter) shows it live.
• Status line. One line at the bottom, in the manner of vim’s. At its left, the mode the keyboard is in: VOLEE while your keys drive volee, EDIT in the agent’s color while they go to an agent (with its name and the key that gives them back), and FILTER, MESSAGE, COMMAND, MESSAGES, WALL, VIEW or HELP while a field or a window has them. Then the few keys of the moment, drawn as keys, and ? help at the right. On the main screen it shows only the keys that are nowhere else on screen: the messages, the filter, the leader (␣ more), the commands and quitting; opening the selected agent and writing to it sit on its preview’s border, or on this line when the layout has no preview border. Every other key is a ? away. The keys come from the same table as the help, so they are always right.

Panel sizes depend only on the size of the terminal and on the view: moving around never makes anything jump. Under 160 columns, the For you column and the journal make room for the view. Below 100 columns or 28 rows, the view makes room too: on the tree tab, the agents panel, already a tree, sits next to the detail and the preview; the network, the repositories and the timeline take the right side of the screen, next to the agents and the detail. The smallest supported terminal is 80x24.

volee shows your terminal’s own background under its text; see Themes to have the theme’s instead.

States

Every state has a glyph and a word, so you can read it without colors. A spinner turns on the cards of working agents, as an extra, unless reduced_motion is set.

The tree

The tree shows who launched whom, for the selected agent: its lead at the top, then the coordinators of the lead’s missions, then their workers side by side, and the subagents hanging under their parent’s card as one-line satellites. Its title names the agent at the top. Select an agent of another tree, in the list or with its jump letter, and the view shows that tree. The sessions that nobody launched and that launched nobody, such as the Claude Code sessions you start yourself, show side by side, in rows, as Tree · on their own.

The links between cards are light and dotted, in a tint of the child’s color, with a dot where they meet. The selected card has heavy lines, a ▶ at its left, and its path up to its root is drawn in solid lines. The tree moves with the agents:

• dots flow down the link of each agent at work;
• each message travels from its sender’s card to its recipient’s, along the links up to their common ancestor and down again, as a small comet ●•· in the color of what it is (a question yellow, a report green, an alert red), and rests a moment on the card it reached; a message you write comes down the recipient’s own link, and its card’s border flashes;
• the border of a card that waits for you pulses, in heavy lines, and the border of one that failed pulses red for a minute.

With reduced_motion (configuration), nothing moves: a message lights its route for a moment, and borders keep their color.

                     ╭─ tower ───────────────── opus ⠹ ─╮
                     │ ⠹ Read missions/invoicing/plan.… │
                     │ 2 missions · 9 agents            │
                     │ platform › main                  │
                     │  WORKING  24 min                 │
                     ╰─────────────────┬────────────────╯
            •┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈•┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈•
╭─ invoicing ─┴────────────╮                    ╭─ latency-audit ┴─────────╮
│ ◆ Invoicing · change     │                    │ ◆ Latency audit · analy… │
│ Waiting for 3 workers    │                    │ Waiting for 2 workers    │
│ ■■■ 1/3 delivered        │                    │ □□ 0/2 delivered         │
│ ! 2 need you             │                    │ sonnet                   │
│  IDLE  14 min            │                    │  IDLE  12 min            │
╰─────────────┬────────────╯                    ╰─────────────┬────────────╯
  •┈┈┈┈┈┈┈┈┈┈┈•┈ ···                                •┈┈┈┈┈┈┈┈┈•┈ ···
┏━ invoice-schema ━━━━━┓                     ╭─ trace-gateway ── ⠹ ─╮
┃ billing › feat/invo… ┃                     │ gateway › audit/p95… │
┃ sonnet               ┃                     │ sonnet · ◆ 2         │
┃ ▂▂▂▃▄▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂ ┃                     │ ▂▃▅▄▂▆▃▂▄▅▃▂▄▃▅▆▄▃▂▄ │
┃ ctx ▰▰▰▰▰▰▰▰▱▱▱ 73%  ┃                     │ ctx ▰▰▰▱▱▱▱▱▱▱▱ 26%  │
┃ ! Bash: bun run db:… ┃                     │ ⠹ Read src/middlewa… │
┃ +214 −12   2 commits ┃                     │ no changes ✉ 1       │
┃  NEEDS YOU  2 min    ┃                     │  WORKING  11 min     │
┗━━━━━━━━━━━━━━━━━━━━━━┛                     ╰─┬────────────────────╯
                                               ├─ ▸ explore-handlers
                                               └─ ▸ explore-traces

Each worker and each session started on its own has a color of its own (its card’s border, its name and its activity), kept from one run to the next; leads and coordinators wear the color of their role. A card that calls for you takes the color of its state.

• A worker’s card, or a session’s, shows where it works (repo › branch), its model and its subagents at work (◆ 2), its activity as a skyline (one column per five seconds: a low bar while it worked, a step taller for each tool call, a yellow one while it waited for you, a red one when it failed, faded once it stopped), the share of its context window its conversation uses (ctx ▰▰▰▱▱▱ 42%, in the color of what waits past 80 %, ctx ? for a session volee did not launch: volee reads it from the status line of the agents it launches, which then shows yours, ADR 0035), what it does or waits for, the lines it changed (+214 −12), the messages waiting for it (✉ 1), how its work is delivered (2 commits, PR #42 ✓), and its state as a badge with how long it has lasted.
• A coordinator’s card shows its mission, what it waits for, its workers’ progress (one square each: delivered, waiting for you, or still at work), how many need you, and its state.
• A lead’s card shows its model on its border, what it does, the missions and agents it launched that still run, where it runs, and its state.

When a mission has more workers than the width allows, they are stacked in a column under their coordinator, so the tree stays readable instead of scrolling.

Zoom

The tree has four levels of detail: large cards, full cards, compact cards with only the state’s badge, and dots with a glyph and a name. A large card shows everything a card shows, and more of it: the whole place, the model and the harness, a skyline two rows high, a wider context bar, what the agent does and the two things it did before, the last message it sent or got (→ you: …, ← lead: …), what it changed and how it is delivered; a coordinator’s large card adds its mission’s goal, a lead’s what it did before and its last message. volee picks the most detailed level that fits the panel, so a small tree shows large cards; + and _ move to more or less detail and keep it, 0 lets volee choose again. When the tree is larger than the panel, it scrolls to keep the selection in view, arrows on the border tell where it goes on, and the mouse wheel scrolls it (with Shift, sideways).

s shows only the selected agent and its descendants, with more room for each card; Esc goes back to its whole tree.

The network

The network shows who talks to whom. Every agent is a node, whatever its harness (Claude Code, Codex CLI…) or its mission, and whether volee launched it or not; you and volee itself, the mission supervisor, join as soon as they take part in a conversation.

• A line joins two parties that exchanged messages, in either direction. It is thicker when they talked a lot lately: each message counts less as it ages.
• A faint dashed line joins an agent to the agent that launched it.
• A question that waits for its answer is drawn in the question color, with a ? next to the one who must answer. The title counts them.
• When a message is posted, a pulse ● travels along its line from the sender to each recipient, in about a second.
• The selected agent’s lines are highlighted and its neighbours’ names are in bold. The line under the graph tells which questions it waits for or owes, who it talks with, who launched it and whom it launched.

Lines follow the routes volee allows (ADR 0006): agents of a mission write to each other freely; otherwise an agent writes to its parent, its children, its mission’s coordinator or the lead who asked for the mission, and to you. So a conversation between two missions goes through their coordinators and the lead, or through you, and a session volee did not launch talks with you: the picture shows who relays what.

Agents that talk end up close together, whatever their mission: positions come from a force-directed layout (linked agents attract each other, all agents push each other away). It is computed only when an agent or a new pair of correspondents appears, never while you watch, and it starts from the previous positions, so a newcomer moves the others little. Agents that do not match the filter are dimmed.

Like the hierarchy, the network has three levels of detail: cards with the name and the state, compact labels with the state’s glyph and the name, and dots with the glyph and the agent’s jump letter, the one in the list, so ' and that letter selects it. In dots, the selected agent’s name is written next to its dot. volee picks the most detailed level whose nodes fit without overlapping; +, _ and 0 work as in the hierarchy. h, j, k and l move to the nearest agent in that direction, g and G to the top-left and the bottom-right ones.

With reduced_motion = true in the configuration, a new message lights up its whole line for a moment instead of travelling along it, and spinners stop.

The repositories

The repositories view shows where agents work and what they delivered. Repositories come first, sorted by name, then their worktrees (the main checkout first) with the branch checked out, the branch it started from and the worktree’s directory; a repository with a single worktree takes one line. Under each worktree come its agents, their subagents under them. Coordinators and agents outside any repository come last.

Every agent shows its delivery evidence: commits ahead of its base, lines added and removed, whether they are pushed, its pull request and the checks, a merge, a delivered report, uncommitted changes. For a worker of a mission, the supervisor’s last verdict sits at the right (✓ delivered, ! needs you, ✗ not delivered…); a coordinator shows its mission’s progress instead.

A worktree that volee tidy would remove is marked ✓ safe to tidy: its work landed (merged into its base, merged through a pull request, or reported), it has no uncommitted changes, its agent does not run, volee checked the work since the agent’s last change, and volee launched the agent in a worktree it created. It is the same rule, from ADR 0011. Otherwise the full level says why the worktree is kept, such as keep: busy, not landed or keep: not launched by volee. The view only tells; it removes nothing. The title counts the worktrees that are safe to tidy.

Three levels of detail: full (a line for the agent, a line for its evidence), compact (one line per agent, the evidence after the name) and names. volee shows the evidence in full when it fits, on one line otherwise; +, _ and 0 change the level and give it back to volee. j and k move through the agents in the view’s order, h and l jump to the previous or next repository.

The timeline

The timeline shows what happened when. Each agent has a lane, in the hierarchy’s order so lanes never jump around, over the last half hour by default. The present is at the right edge, and the picture slides left as time passes, one column at a time.

A lane draws the agent’s state as a bar: heavy while it works (━) or waits for you (━ in the color of that state), thin while it is idle or done (─), dotted once it stopped (┄). Marks tell what happened; when several fall in the same column, the one a person most needs to see wins:

A cursor scrubs through time. h and l move it one column back or forward, [ and ] jump to the selected agent’s previous or next event, and a click on a lane moves it there. The line under the lanes reads the cursor: when, the selected agent’s state then, and what it did at that moment (the question it asked, the answer it received, the pull request that merged…). Going back further than the lanes reach slides the window back with the cursor; Esc brings it to the present again. + and _ make the time scale finer or coarser, from a second to an hour per column; 0 comes back to the present and the default scale.

The wall of screens

5 (or Space w) opens the wall: the agents of the current list that run, each as a tile of its screen, over the whole terminal. The filter (/) applies, so filter first to watch one mission or one repository.

 Wall · 5 agents run
┏ ! invoice-tools · needs you ━━━━━━┓╭ ▸ invoicing · working · live ────╮
┃ ⏺ Before I go on, one question:   ┃│ ⏺ The tests pass: 356 of 356.    │
┃   Should create_invoice accept a  ┃│                                  │
┃   draft flag?                     ┃│ ❯ commit and push                │
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛╰──────────────────────────────────╯
 h/j/k/l move   z full screen   enter open   q back

Every agent that runs has its tile, wherever it runs:

• an agent in a volee host is followed live (its title says so);
• any other agent (a Claude Code background session, a session in a tuios or tmux pane) shows the screen volee reads for its preview, read again every five seconds while the agent works, every fifteen seconds while it rests, and at once when its state changes.

A tile shows the bottom of its agent’s screen, where the prompt and the questions are, cut on the right when the tile is narrower, under the agent’s name and state. The wall only looks: it never takes an agent’s input and never resizes its terminal.

A session in a terminal volee cannot read (Claude Code started by hand in a terminal window, outside tuios and tmux) has no screen to show. Its tile says so, then what volee knows of the agent: where it works, where it runs, what it did last. Opening it says how to make it reachable.

A page holds as many tiles as your terminal shows at a readable size (at least 40 columns by 14 rows each): two in an 80 by 24 terminal, nine in a large one, up to sixteen in a very large one. Moving past the last tile of a page shows the next page, and the first row says which page this is.

The wall’s selection is the list’s: the selected tile has a thick border, and leaving the wall leaves the list on that agent.

These are the defaults of the wall context: [tui.keys.wall] changes them, like any other key (Keys).

From a shell, volee host wall shows every running volee host of the machine as a wall of its own, whatever the hosts run and without the daemon (hosts).

Moving around

• j, k and the arrows move through the list; gg and G go to its first and last agent, Ctrl+d and Ctrl+u half a page down and up. In the hierarchy, h, j, k and l move through the tree as drawn: down to satellites and children, up to the parent, sideways to the nearest card. In the network they move to the nearest agent on screen; in the repositories and the timeline, j and k follow the view’s order.
• Every agent has a letter, shown in the list. Press ' then the letter to jump to it, from anywhere: two keys to reach any agent.
• - goes back to the agent selected before, and again to return.
• / filters by name, repository, branch or mission, as you type. The hierarchy and the network dim the agents that do not match; the list, the repositories and the timeline hide them. Enter keeps the filter, Esc clears it. With a filter kept, n and N go to the next and previous agent that matches, round the list.
• 1 to 4 show a view; H and L the previous and the next one.
• Tab moves the keyboard to the next panel. Clicking a row, a card, a node, a lane or a tab selects it; a second click on an agent, soon after, opens it.

Esc closes or leaves one thing at a time (a popup, the timeline’s cursor, the subtree, the filter, then the panel), and never quits volee.

Writing to an agent

m opens the composer on the selected agent. Write your message (Markdown is fine), choose its kind with Tab (note, question, answer, contract or alert) and send it with Enter. Alt+Enter or Ctrl+J starts a new line, and pasting several lines keeps them.

When the agent asked you a question that you have not answered, the composer opens as the answer to it and shows the question; volee then links the two, so the question stops waiting. A message reaches an agent volee launched at the end of its turn, and wakes it when it is idle. Sessions started outside volee cannot receive messages yet; the composer says so.

Esc closes the composer and keeps what you wrote: the hint line shows ✎ draft to <agent>, and m brings it back, addressed to the agent selected then. Quitting with a draft asks first.

Messages

I (or Space i) opens your messages. Questions agents asked you and that you have not answered come first, pinned until an answer refers to them; then every thread you take part in, the latest activity first: mission threads, threads with agents, and volee’s own alerts. A ● marks threads with unread messages; the top bar counts both.

The selected thread shows on the right. Enter reads it: the keyboard moves into the thread (j and k scroll it) and its messages are marked read; Esc comes back to the list, then closes the window.

r replies in the selected thread: to a pinned question, the composer opens as its answer, linked to it, so the question stops waiting; elsewhere it writes to the last agent that spoke there (or the mission’s coordinator). Sending or closing the composer comes back to the messages. volee’s alerts take no reply.

A question may offer the answers to choose from. They show under its text, numbered:

coordinator-invoicing → you · question · 2 min ago
Both pull requests are green and reviewed. Merge them?
  1 ok merge
  2 no
  press its number to answer, or reply in your own words

Press the number of an answer: the bottom line asks Answer "ok merge" to coordinator-invoicing?, and y sends it, n or Esc takes it back. The agent reads exactly the answer it offered. r still opens the composer, for an answer in your own words, which the agent must not take for one of its options.

s asks for a summary of the thread, written by a model. Summaries are off unless you turn them on (summaries = true under [messages] in the configuration); until then, the window says so.

Changes

d shows the selected agent’s changes against the branch it started from: first a summary (git diff --stat), then the full patch with f. j and k scroll, r loads them again, and Esc or d closes the window. A very long patch stops at a line that says so; the rest is in the agent’s worktree.

Your own tools

o opens the selected agent’s worktree in another program, from the agents or from the Changes window: e your editor, d your diff viewer, g your git interface, w an editor with a window of its own. None is required: volee offers what it finds ($VISUAL or $EDITOR, Neovim with diffview.nvim, lazygit, VS Code) and what [tui.tools] names in the configuration, and says how to add the others. Terminal programs take over the terminal and the interface comes back when they exit; VS Code opens its own window and volee stays.

Launching agents and missions

Space n launches an agent in a new worktree: choose the repository (from [repos] in the configuration, or type the path of a checkout when there is none), name the new branch, write the task (its first prompt) and, optionally, the model and the harness (claude-code, the default, or opencode). Space N creates a mission: a title, its kind (change delivers branches and pull requests, analysis reports), its repositories and its goal; volee launches its coordinator.

Tab moves between fields, ← and → choose, space picks a repository, and Enter starts a new line in the task or the goal (it moves to the next field from the others). Ctrl+S launches, from any field: Enter never does, so a task you are still writing cannot start an agent. If your terminal or multiplexer keeps Ctrl+S for itself (Zellij’s scroll mode does), move launch to another key under [tui.keys]. When volee refuses (a repository Claude Code does not trust yet, a branch that already exists…), the dialog stays open and says why, so you can fix it and launch again. The new agent is selected as soon as it appears.

Edit mode: typing into an agent

enter opens the selected agent and types into it without leaving volee (i, a and a double click do the same). The full-screen view opens on the agent’s live screen, its frame takes the input colour, and its title and the bottom line say EDIT and whose keys these are now:

╭  EDIT  Screen · invoicing ─────────────────────────────────────────────╮
│ ⏺ The tests pass: 356 of 356.                                          │
│                                                                        │
│ ❯ commit and push                                                      │
╰────────────────────────────────────────────────────────────────────────╯
  EDIT   your keys go to invoicing   ctrl-q back to volee

Every key goes to the agent, Esc, q and Ctrl+C included, and so does what you paste, in one piece (as a bracketed paste when the agent turned it on). Ctrl+Q gives the keys back to volee: the screen stays, live, i types again, and z or esc comes back to the list. Ctrl+Q never reaches the agent; to use another key, set leave in [tui.keys.attached] (Keys).

The mouse goes to the agent too, when its program asked for it (Claude Code does): clicks, drags and the wheel land on the agent’s own cells. For a program that did not ask, the wheel scrolls back through what it wrote, as it does in the full-screen view outside edit mode. A click on the frame around the screen does nothing.

In edit mode the agent’s terminal takes the size of the panel, so that its screen is drawn cell for cell, cursor included, and follows when your terminal changes size; it keeps that size when you leave. Only edit mode and volee attach set an agent’s size: the preview, the full-screen view and the wall never resize it. For an agent in a volee host, the three show the same live screen as edit mode: the preview follows the selected agent as it writes, and its title says live. volee encodes your keys the way the agent asked (the kitty keyboard protocol Claude Code turns on, or the usual encoding), and Ctrl+Z, which suspends Claude Code, is followed by its resumption: in a volee host there is no shell to bring it back.

volee attach <agent>, from a shell, takes an agent over in the whole terminal instead; Ctrl+Q comes back there too. Taking an agent over in one place ends edit mode in another: volee says so and watches the agent again.

Opening a session volee did not start

A session started outside volee opens the same way, where it runs, through the door it already has (ADR 0027):

Nothing is stopped, restarted or adopted for it: it is the same session, in the same process, with its own tools and settings. Ctrl+Q closes the terminal volee opened and comes back to the list, and the bottom line says that the agent keeps running. While it is open, the session takes the size of volee’s panel; a tuios pane goes back to its own size when you leave.

A finished background session is still in the list, as in Claude Code’s own agents view: opening it starts it again, under the same session, as claude attach does. Leaving the terminal the way Claude Code offers (Ctrl+Z) closes it too, and the left arrow on the session’s empty prompt shows Claude Code’s own agents view there, as in any terminal.

A Claude Code session typed in a terminal of its own, in a tab of your terminal application with no multiplexer around it, is held by that terminal: nothing else can show it or type in it. enter on it does not fail. A window says what to do, and volee waits:

╭ Open dashboard ────────────────────────────────────────────────╮
│ It runs in a terminal of its own: only that terminal can show  │
│ it. Claude Code hands it over at one key, and nothing stops:   │
│                                                                │
│  1  Go to the terminal where it runs:                          │
│     claude, in /home/you/code/dashboard                        │
│  2  Press the left arrow key there, with nothing typed in its  │
│     input box. Claude Code shows ← for agents under it.        │
│  3  Come back here: volee opens it by itself.                  │
│                                                                │
│ The conversation moves to Claude Code's background, where its  │
│ work goes on. Its terminal still shows it: Escape twice there. │
│                                                                │
│ volee is waiting for that key.                      esc cancel │
╰────────────────────────────────────────────────────────────────╯

A terminal too small for the window has the same on its bottom line, in one sentence. Press the left arrow there, while the session rests or while it works: Claude Code moves the conversation to the background, where a turn under way goes on, and volee opens it by itself, on the same row. esc gives the wait up, and it ends with the session if you quit it there. From then on it is a background session like any other: enter opens it at once. In its own terminal, Claude Code now shows its list of agents; Escape twice shows the conversation there again.

The row keeps its place in the list and takes the name Claude Code gives the conversation in the background: the one you gave with --name, or a title made from the conversation when Claude Code had named the session. It works the same in every terminal application: volee asks none of them for anything (ADR 0034).

Agents volee launched before 0.10 run in older hosts, which outlive an upgrade: edit mode sends them the bytes a terminal sends, so typing works, but a key only a keyboard protocol tells apart, such as Shift+Enter, arrives as its plain form, and Ctrl+Z is not sent at all, since nothing in such a host would resume Claude Code. Such an agent gets a new host the next time it is stopped and resumed.

Adopting an agent

Opening a session needs no adoption. Adopt one when you want volee to drive it from now on, like the agents it launches: messages reach it, volee stop stops it, a message resumes it, and it comes back after a reboot.

A moves the selected agent’s conversation into a volee host, as volee adopt does. It asks first, on the bottom line, because it changes the session: volee stops it (claude stop), so that two programs never write the same conversation, then resumes the conversation in a new host, in the same directory, with volee’s settings in place of the session’s own (its hooks, its MCP servers, its permission mode). y adopts and opens the agent as soon as its host runs; n or Esc leaves it alone. It works on Claude Code background sessions, on agents whose session ended, and on OpenCode agents started with --session. An agent that runs in a terminal of its own must be quit there first: volee refuses it until then and says so on the bottom line. The agent keeps its name and its history.

The conversation resumes in the agent’s worktree. In a repository Claude Code does not trust yet, it asks first, in the host: open the agent (enter) to answer, once for the repository. When the resumed program fails, the agent is stopped and its detail quotes the program’s last line (Claude Code’s trust message, for example). The conversation is not lost: fix the cause and send the agent a message, or resume it in the background yourself, and volee shows it there again, ready to adopt.

Agents in tuios panes

A Claude Code session you started by hand in a tuios pane is found in that pane when tuios is installed and its server runs: the daemon asks tuios each time it looks for sessions, and the Detail panel says where it runs (tuios · work: tuios, and the session that holds the pane). Its preview is the pane’s screen, and enter opens the pane inside volee: the daemon runs tuios pane-view on it, and what you type goes to the pane. While no tuios window shows the pane’s session, the pane takes the size of volee’s panel, and goes back to its own when you leave with Ctrl+Q. No pane is opened, closed or moved, and the session in it is none the wiser.

The session shows in volee ten seconds after it starts, like any session started outside volee. /clear in the pane starts a new session in the same process: its row stays the same row.

An agent of another AI in a tuios pane is shown and opened the same way. OpenCode is found in the process table, then in its pane. For a harness volee has no list of its own for (Codex CLI, Gemini CLI, Aider), tuios itself tells volee: it recognizes the program in the foreground of the pane, and volee lists that pane as an agent (Agents of other harnesses).

volee uses the default tuios server, or the one TUIOS_SERVER names when you run volee daemon run yourself. The commands that bring a pane forward name that server, so they reach the pane even when volee runs in a pane of another tuios server; the command volee shows then names it too, such as tuios --server lab attach work.

tuios’s own Claude Code hooks (tuios integration install claude-code) tell volee which session runs in which pane; without them, volee follows the session’s process to its pane. Nothing is required: without tuios, these sessions are listed as before, and volee daemon status says whether volee found tuios (ADR 0015).

Agents in tmux panes

A Claude Code session you started by hand in a tmux pane is found the same way, when tmux is installed and its server runs: volee follows the session’s process to the pane that runs it. The Detail panel says tmux · work, the preview is the pane’s screen, and enter makes the pane current in its window and session, then switches your tmux client to it when volee runs in a client of that same tmux server. From anywhere else (outside tmux, or in a client of another server), volee switches no client, not even one open in another terminal: it says how to see the pane instead, tmux attach -t =<session> (the = asks for that exact session).

The daemon uses the default tmux server, or the one TMUX names when you run volee daemon run yourself inside tmux, and every command it runs or shows names that server. Zellij is not supported yet.

Forgetting an agent

F forgets the selected agent, after asking on the bottom line: volee stops listing it and ignores its sessions from then on, as volee forget does. Nothing is stopped or deleted: its sessions, worktree and branch stay as they are. volee refuses an agent it launched that still runs (stop it first with volee stop) and an agent of an open mission, and the bottom line says which.

Keys

The keys follow the habits of vim and of terminal tools such as lazygit: h, j, k, l and the arrows move, gg and G go to the ends, Ctrl+d and Ctrl+u move half a page, / filters and n / N go through the matches, ? shows the keys, : runs a command by name, Esc goes back and q quits. q quits at once, unless a message you started would be lost: then volee asks first.

The keys of this screen. ? opens a small popup at the bottom right with the keys of the panel you are in and of everywhere, in columns, with nothing to scroll. Press one of them and the popup closes and does it; ? again lists every key of every context; Esc closes it.

The leader. Less frequent actions sit behind the space bar, as in LazyVim: press Space and a popup at the bottom right shows what can follow, such as n for a new agent, N for a new mission, t for the theme, w for the wall or k for every key. Esc, or a key that continues nothing, drops the sequence. gg works the same way: after g, the popup shows what can follow.

The command palette. : opens a prompt on the bottom line and lists the commands of the current screen, the ones matching what you type first: each action by its name and what it does, and theme <name> for every theme. Enter runs the selected one, the arrows, Tab or Ctrl+n / Ctrl+p move, Esc closes.

The theme. Space t (or :theme) opens the theme picker at the bottom right: moving shows each theme at once, Enter keeps it in the configuration, Esc goes back to the theme you had. See Themes.

Changing keys. Every key in the tables below can be changed in the [tui.keys] table of the configuration: give an action other keys in every context, or in one with a [tui.keys.<context>] table (the context’s name is in each title below), and an empty list unbinds it. Keys are written like q, ctrl-c, shift-tab, enter or f5, and sequences of up to three keys like g g or space n:

[tui.keys]
take-over = "ctrl-a"           # opening an agent, everywhere it has a key
new-agent = ["c", "space n"]   # several keys
adopt = []                     # no key

[tui.keys.agents]
first = "home"                 # in the agents list only

[tui.keys.attached]
leave = "ctrl-g"               # leave edit mode with Ctrl+G

volee refuses, with the line of the configuration, two actions on the same key where both apply, and a key that both acts and starts a longer sequence (g alone would hide gg). The leave key (leave) must be Control and a letter other than h, i, j or m: it is the only kind of key every terminal sends the same way while an agent owns the keyboard. Typing keys (letters, Backspace, the arrows in a text) are not shortcuts and stay as they are. The tables are generated from the keymap, like the popups and the hints.

Everywhere (global)

Agents list (agents)

Hierarchy (hierarchy)

Network (network)

Repositories (repos)

Timeline (timeline)

Detail and preview (detail)

Full screen (screen)

Filter prompt (filter)

Message composer (composer)

Changes (diff)

Questions (confirm)

Messages (inbox)

Open with (tools)

Launch dialogs (dialog)

Choices in dialogs (choice)

Text fields (editing)

Keys popup (keys)

All keys (help)

Command palette (commands)

Theme picker (themes)

Wall of screens (wall)

Edit mode (attached)

Themes

volee draws with semantic roles, such as state.needs_input or diff.added, never with fixed colors. A theme maps those roles to colors.

Pick a theme

volee ships with five themes:

From the interface

Press Space t, or type :theme, to open the theme picker at the bottom right of the screen. It lists the built-in themes, then your own from ~/.config/volee/themes. Moving in the list applies each theme at once, so you see it on your own agents before you decide.

• Enter keeps the theme and saves it as [tui] theme in your configuration. The rest of the file, comments included, is left as it was.
• Esc closes the picker and brings back the theme you had.

From the command line

volee --theme <name> opens the interface with that theme for this run. It does not change the configuration, and it wins over [tui] theme. An unknown name is refused with the list of the themes that exist.

volee --theme catppuccin-latte
volee demo --theme catppuccin-latte

In the configuration

[tui]
theme = "catppuccin-latte"

volee looks for a theme in ~/.config/volee/themes/<name>.toml first, then among the built-in themes.

When nothing is set

With no --theme and no [tui] theme, volee looks at your terminal: it asks for the background color and uses catppuccin-mocha on a dark background and catppuccin-latte on a light one. When the terminal does not answer (some multiplexers and remote sessions), it reads the COLORFGBG variable, and when that is missing too it keeps catppuccin-mocha. The guess is only made when the output is a terminal, and never waits more than a moment. Set a theme to turn it off.

The order is: --theme, then [tui] theme, then the guess, then catppuccin-mocha.

volee uses 24-bit colors when the terminal announces them in COLORTERM (truecolor or 24bit), and otherwise replaces each color by the nearest one of the 256-color palette. The terminal theme uses only the 16 colors your terminal lets you configure.

The background

volee shows your terminal’s own background under its text, whatever the theme: its color, and its transparency or blur when your terminal has some. The theme colors the text, the borders and what fills a cell on purpose, such as the selected row, a state badge or a notice.

To have the theme’s own background color instead (the background role of the theme):

[tui]
background = "theme"

The theme picker shows each theme over the background you chose. A theme made for a light background reads badly on a dark terminal, and the other way round: when nothing is set, volee picks the flavor that matches your terminal (above).

Write a theme

A theme is a TOML file with an optional parent, a palette of named colors, and the roles:

# ~/.config/volee/themes/dusk.toml
inherits = "catppuccin-mocha"

[palette]
ember = "#ff9e64"

[roles]
"state.needs_input" = { fg = "ember", modifiers = ["bold"] }
"role.worker" = "sky"
edge = "#3b4261"

• inherits starts from another theme (yours or a built-in one). A theme may inherit from the built-in theme of the same name to change only a few roles of it.
• [palette] names colors. A palette entry of the child replaces the parent’s, and every role that uses it follows: that is how the Catppuccin flavors share one set of roles.
• [roles] gives each role a color (a plain string sets the foreground) or a style: { fg = "...", bg = "...", modifiers = [...] }. Modifiers are bold, dim, italic, underlined, reversed and crossed-out.
• A color is a palette name, an ANSI name (red, light-blue, dark-gray…), reset for the terminal’s default, #rrggbb, or a 256-color index.
• A role a theme does not set falls back to its parent role (state.working falls back to state), then to the terminal’s default style. Unknown roles are ignored, so a theme keeps working with older and newer versions of volee.

Roles

Command line

Everything in volee goes through one daemon per user. The commands below start it when they need it, so most of the time you never think about it.

The daemon

The daemon logs to ~/.local/state/volee/logs/daemon.log. Set VOLEE_LOG to change the level, for example VOLEE_LOG=debug volee daemon run.

The interface writes no log unless you ask: it owns your terminal, so it has nowhere to print. With VOLEE_LOG set, for example VOLEE_LOG=volee_tui=debug volee, it writes to ~/.local/state/volee/logs/interface.log, a file only you can read. In edit mode that log says what became of each key (sent to the agent, kept until the host answers, kept back, dropped), never the key itself.

A command that starts the daemon may run inside an agent’s session or a multiplexer pane. The daemon starts in its state directory and drops the variables that identify that session or pane (such as CLAUDE_CODE_SESSION_ID or TMUX_PANE), so the agents it launches never inherit them. Your settings, such as ANTHROPIC_API_KEY or CLAUDE_CODE_USE_BEDROCK, are kept.

Starting at login

volee daemon install           # start the daemon at login
volee daemon install --print   # show the file, install nothing
volee daemon uninstall         # undo it

Without it, the daemon starts the first time you use volee after a reboot, and that is when it resumes the agents the reboot interrupted (after a reboot). volee daemon install makes that happen at login instead: on macOS it writes a launchd agent, ~/Library/LaunchAgents/org.volee.daemon.plist, and on Linux a systemd user unit, ~/.config/systemd/user/volee.service; both run volee daemon run, and the command loads them at once. The file records the PATH of the shell you run it from, so that the daemon finds claude, git and gh, and the VOLEE_* variables you set: run it again after you change them. volee never installs it on its own.

What the daemon does in the background

While it runs, the daemon keeps what volee shows current by itself. None of it waits for you, and none of it changes your work:

Pull request look-ups use your GitHub account’s API allowance, a few requests a minute with several agents running. Without gh, or signed out, volee skips them and volee daemon status says why. Without a tuios or tmux server, the search for panes changes nothing, and volee daemon status says so on its panes lines.

Agents

volee ls          # every agent, the ones that need you first
volee ls --json   # the same, as JSON for scripts

The list includes every agent volee launched, each in its volee host, and every live Claude Code session and OpenCode agent on the machine, in a terminal or in the background, whoever started it. Claude Code agents volee launched report through their hooks the moment something happens. The daemon finds the other sessions by listing them (and OpenCode in the process table), and each listing costs a little CPU, so it lists as often as things change. While the interface is open, it lists every two seconds after a listing that found something new, and waits twice as long after each listing that found nothing, up to ten seconds. With no interface open, it lists every thirty seconds, so an idle daemon costs next to nothing. Opening the interface lists them at once, and so does volee ls, which waits for that listing (three seconds at most) before it prints. Finished sessions you never saw through volee are left out; volee daemon status tells you whether Claude Code was found.

Each line shows a symbol and a word for the state, so the list reads without color:

Each agent also has a short id such as ag_x7k2pq. Wherever a command asks for an agent, you can type its name, that short id, or its full id.

Acting on an agent

volee logs <agent>          # its screen as it looks now
volee diff <agent>          # its changes against the branch it started from, by file
volee diff <agent> --full   # the same changes, as a full patch
volee attach <agent>        # open it in this terminal, where it runs
volee adopt <agent>         # move a session volee did not start into a volee host
volee stop <agent>          # stop it; volee does not resume it until you message it
volee forget <agent>        # stop listing an agent that no longer runs

volee logs prints the agent’s screen as it looks now, as plain text. For an agent in a volee host, that is the exact screen the host holds; for a session in a tuios or tmux pane, the pane’s screen, row for row. For a Claude Code background session, volee replays what claude logs recorded and prints the screen that leaves, every row of it, blank rows included; in a session that has run for hours it can miss what was drawn long ago and never redrawn. volee diff compares the agent’s worktree, committed or not, with the merge base of its base branch, and lists the files it created; a very long diff is cut, and the rest is in the worktree.

volee attach hands this terminal to the agent, where it runs. For an agent in a volee host, Ctrl+Q comes back; the agent keeps running after you leave. Ctrl+Q never reaches the agent, whatever keyboard protocol the agent turned on. While you type, your terminal’s size is the agent’s size, and it stays when you leave; nothing else resizes an agent. Taking the same agent over from a second terminal moves the input there, and the first terminal returns to its shell.

For a Claude Code background session volee did not start, volee attach runs Claude Code’s own claude attach on it: it is the same session, with nothing stopped or restarted, and Ctrl+Z comes back to your shell, as Claude Code says. In the interface, enter opens it the same way inside volee (opening a session).

Where an agent runs decides what these commands can do:

The list is what runs now (ADR 0027). A session volee did not start is one row for as long as its harness lists it: a finished background session stays, like in Claude Code’s own agents view, and a session that is gone leaves the list a minute later. A session started outside volee, in a terminal, shows once it has lived ten seconds, so that a program’s one-off call never becomes a row.

volee never stops or restarts a session it did not start: you stop it where it was started. volee adopt is for a session you want volee to drive from now on: volee stops a background session first (claude stop), so that two programs never write the same conversation, then resumes its conversation in a new host, in the same directory, with volee’s settings in place of the session’s own, where it waits at its prompt. It also adopts an agent whose session ended. An agent that runs in a terminal of its own must be quit there first: volee refuses it until then. An OpenCode agent can be adopted when it was started with --session, once you quit it. The agent keeps its name and history in volee. Once adopted, it is handled like the agents volee launches: messages reach it (they wake it when it waits at its prompt), volee stop stops it, and a message resumes it in a new host. The conversation resumes in the agent’s worktree; in a repository Claude Code does not trust yet, it asks there first (volee attach to answer). When the resumed program fails, the agent’s detail quotes its last line.

A stopped agent keeps its conversation, and volee does not resume it on its own, even when other agents write to it, until you send it a message yourself. volee stop on an agent that is not running only records that.

volee forget removes an agent from volee’s lists, for example one whose launch failed or a session you no longer care about; volee then ignores its sessions. Nothing else changes: its worktree and branch stay, so remove them with git when you no longer need them. volee refuses to forget an agent it launched that still runs (stop it first) and an agent of an open mission.

Launching agents

volee spawn billing feat/invoices "Add invoices to the billing module."
volee spawn . fix/flaky-test "Make the payment test stable." --base develop --model sonnet
volee spawn billing feat/export "Export invoices as CSV." --harness opencode

volee spawn <repository> <branch> <task> creates the branch from the base (--base, else the repository’s base in the configuration, else its default branch), checks it out in a new worktree at .claude/worktrees/<name> inside the repository (the branch with / and other unusual characters replaced by -), and starts Claude Code there, in a volee host, with the task as its first prompt. --name sets its display name, <repository>-<name> otherwise. The agent gets volee’s hooks and MCP tools, so it appears at once in volee ls and can send you messages.

--harness opencode starts OpenCode instead, in the same kind of worktree and host (opencode --session <id> --prompt <task>, with --auto when permission_mode = "auto"). --model does not apply to it. OpenCode takes no hooks, so volee reads its state from its screen, and messages wait until it stops, then resume it; see Agents of other harnesses.

When the repository has setup commands in the configuration, such as bun install, they run in the new worktree before the session starts, and volee spawn says so before it waits; the agent is listed as launching, with the command that runs. A failing command fails the launch and keeps the worktree, like the cases below (setup commands).

Claude Code works only in repositories you trust: run claude once in each repository and accept its trust prompt before volee launches agents there. When a launch fails before its session started, the worktree and the branch it had already made stay, untouched: once the cause is fixed, run the same volee spawn again, and volee reuses them, as long as nothing was done in them (ADR 0016). That includes a launch the daemon could not finish because it stopped, and one whose session Claude Code never listed within two minutes: volee marks those failed at its next look for sessions.

A launch on a branch where an agent already works is refused, and names that agent: what there is to add goes to it, with volee msg send.

A lead

volee lead                                   # here, and talk to it
volee lead "Add invoices to billing and to the API."
volee lead --name tower --model sonnet

A lead is the agent you talk to. It launches agents and missions for you, hears their reports, and never codes (ADR 0033). volee lead starts one in the current directory, in a volee host, and opens it in your terminal at once; Ctrl+Q gives the terminal back and the lead keeps running. Without a terminal, it says how to open it. enter on its row in the interface, or volee attach <name>, opens it again. It is named lead-<directory> unless --name says otherwise, and uses the configured model unless --model does.

A lead has no worktree and Claude Code’s editing tools are turned off for it. It gets two more MCP tools than the other agents: spawn_agent, for one task in one repository, and start_mission, for work across several. What it launches reports to it; it tells you in a line what it launched, and in three lines what came back. You can also write to it without opening it: volee msg send <lead> "..." from a shell, or m on its row in the interface. It takes that as what you say, the same as what you type in its terminal. volee lead typed again where that lead runs is refused, and says how to open it; give another lead a name of its own with --name.

volee lead, volee spawn and volee mission new refuse to run in the shell of an agent volee launched, like the commands that speak for you: an agent launches with its own tools, so that what it starts reports to it.

Running any program as an agent

volee run -- codex                      # any command line, after --
volee run --name invoices -- gemini     # with a name of your choice

volee run [--name <name>] -- <command> starts the command in a volee host, in the current directory and with this terminal’s environment, makes it an agent of the list, and puts this terminal on it: you use the program as if you had typed the command alone. ctrl-q (the leave key) gives the terminal back, and the program keeps running under volee: volee ls and the interface list it, volee attach <name> and enter open it, volee logs <name> prints its screen and volee stop <name> ends it. The agent is named after the directory unless --name says otherwise. Without a terminal on standard input and output, the command starts the program and prints how to open it. A command that cannot start (a program that is not found) is no agent, and the reason is printed.

Such an agent is a program volee holds the terminal of, and nothing more: its state is read on its screen (working while the screen changes, idle after a few seconds without a change), nothing hands it a message, and nothing resumes it once it ended, whether by itself, by volee stop or with a reboot. Its row then shows the end for a minute and leaves the list. See Agents of other harnesses for when to use it, and ADR 0029 for the decision.

After a reboot

A reboot, a logout or a crash of a host ends the agent’s program, but its conversation and its worktree stay. The first time the daemon starts afterwards, it looks for agents whose host is gone without recording an end, and resumes each one in a new host, in the same directory and worktree. An agent that was working gets a first prompt that says the machine restarted, so that it checks where it was; an agent that waited at its prompt comes back waiting, without one. A resumed agent has lost what it was doing in the middle of a turn, such as a command that was running: the harness resumes from the last saved message.

Some agents are not resumed: the ones you stopped, the ones of a mission that is over, the ones that were done or had failed, and an agent whose host came from such a resume and is gone again less than ten minutes after it started, which volee takes for a crash rather than a reboot, so that it never restarts an agent in a loop: it marks it failed, with the reason. Set resume_after_reboot = false to resume none of them: they show as stopped, and your next message resumes one.

The daemon starts when you first use volee, or at login once you ran volee daemon install.

Tidying worktrees

volee tidy <agent>             # remove its worktree if its work landed
volee tidy --all               # the same for every agent volee launched
volee tidy --all --dry-run     # say what would be removed, touch nothing

volee tidy removes the worktree of an agent only when the evidence says its work landed: its branch is merged into its base branch, its pull request is merged, or, for analysis work, its report was delivered. It also removes the worktree of a launch that failed before any session started, when nothing was ever done in it: no change, no untracked file, no commit of its own. The worktree must also be clean, the agent must not be running, and volee must have checked the agent’s work since its last change. It only touches agents volee launched, in the worktrees it created under .claude/worktrees/. Files git ignores (a copied .env, local data) are not work git can see, so they go with the worktree: copy out anything you want to keep first. It never deletes a branch and has no way to force a removal: when something is missing, it says what, for example:

Kept billing-feat-invoices: its work has not landed: not merged into its base branch, no merged pull request, no report.

Once the worktree is gone, the agent leaves volee ls; its history stays in volee’s event log, and its branch stays in the repository.

Messages

volee msg send billing "Also update the changelog."
volee msg send ag_x7k2pq "Use TTC." --kind answer

A message reaches a working Claude Code agent at the end of its turn, and wakes an idle one at once. When an agent volee launched has stopped (its program ended, or Claude Code stopped an idle background session after about an hour), volee resumes it in a new volee host, in its worktree, with the message as its prompt: Claude Code with --resume, OpenCode with --session. If that fails, it tells you once. An OpenCode agent has no hooks to hand it a message while it runs: the message waits until it stops. Two cases are never resumed on their own:

• an agent you stopped with volee stop: messages from agents and from volee wait, and your next message to it resumes it with all of them;
• an agent whose mission is over (closed or aborted): its messages wait until it runs again, which only you can decide, with claude --resume in its worktree.

Claude Code sessions you did not launch through volee cannot receive messages yet. Agents of other harnesses that joined through volee’s MCP server read their messages themselves, when they call read_messages; a message sent while one is stopped waits for its next start. volee msg send says, after sending, which of these cases applies.

Questions

An agent that needs a decision asks you. Its question waits, on top of your messages in the interface, until you answer it:

volee msg questions

msg_x7k2pq  coordinator-invoicing asks, 2 min ago:
  Both pull requests are green and reviewed. Merge them?
  Answers: 1 ok merge · 2 no
  Answer with `volee msg answer msg_x7k2pq <number>`.
msg_8fq0zd  billing asks, 12 min ago:
  Are amounts stored with or without tax?
  Answer with `volee msg answer msg_8fq0zd "<your answer>"`.

volee msg answer msg_x7k2pq 1              # the first answer it offers
volee msg answer msg_x7k2pq "ok merge"     # the same, by its words
volee msg answer billing "Without tax."    # the agent's name, when it asked one question

A question may offer the answers to choose from. Name one by its number or by its words, whatever their case: the agent then reads exactly the answer it offered. Anything else is sent as your own words, and volee says that it is not one of the offered answers: an agent that asked for a yes or a no must not take a sentence for a yes. The answer is linked to the question, which stops waiting.

Summaries

volee summary invoicing      # a mission's thread
volee summary billing        # your thread with an agent

A model reads the thread and answers in a few bullet points: what was decided, what was delivered (with its links), the questions still waiting and who must answer them, what is blocked. Summaries are off until you set summaries = true under [messages] in the configuration, because each one runs Claude Code with your account.

Missions

A mission is one goal carried out across one or more repositories by a coordinator agent and its workers (see Concepts).

volee mission new "Invoicing" "Add invoices to billing and expose them in the API" \
  --repo billing --repo api           # or --repo billing,api
volee mission new "Slow queries" "Find the ten slowest queries" --repo . --kind analysis
volee mission ls                      # open missions; --all adds closed ones, --json for scripts
volee mission show invoicing          # agents, verdicts on workers, the mission's thread
volee mission abort invoicing --reason "wrong approach"
volee mission close invoicing         # yourself, once every worker delivered

A repository is a name from the configuration or a directory. A mission is named by its title, its short id (ms_x7k2pq) or its id. While a mission is open, another one under the same title is refused, whatever its case: what there is to add goes to its coordinator.

Creating a mission starts its coordinator: a Claude Code session in the main checkout of the mission’s first repository, with Claude Code’s editing tools turned off. It plans the work and launches one worker per task with the MCP tool spawn_worker, each in its own worktree. Without Claude Code (missing, or too old), volee mission new refuses before recording anything, and volee daemon status says why.

volee checks each worker when it stops. A change worker has delivered when its commits are pushed with an open pull request, or merged; in a repository without a remote, when its work is committed on a clean worktree. An analysis worker has delivered when it sent its report. The coordinator hears about every verdict.

Once every worker delivered, the coordinator presents its report (what is done, the proof, what is left) as a question to you, with the answers ok merge and no (ok close and no for an analysis mission). Nothing is merged or closed before you answer, and volee mission ls shows the mission as waiting for you:

volee msg questions
volee msg answer coordinator-invoicing 1     # ok merge

Only that answer merges the work, and volee makes the merges itself, one worker after the other: no agent merges (ADR 0032).

• With a remote, it merges the worker’s pull request on GitHub with your gh: a draft is marked ready first, and the method is the repository’s merge setting, or the first one the repository allows among a merge commit, a squash and a rebase. GitHub’s rules still apply: volee does not bypass a required review or a failing check, and does not wait for them.
• Without a remote, it merges the worker’s branch into its base branch in the main checkout, as a merge commit. The main checkout must have the base branch checked out, and no uncommitted change to a tracked file: volee does not switch branches or stash for you.

It then closes the mission. When a merge cannot go through, nothing is forced and a conflict is abandoned: what was already merged stays merged, the mission is open again, and a message tells you, the coordinator and the lead which work was not merged and why. Once that is settled, the coordinator presents its report again and you answer again. On any answer other than ok merge the mission stays open, and the coordinator is told what you said.

A closed mission is tidied in one gesture: volee removes the worktree of every worker whose work landed, keeps its branch, forgets the agent, stops the coordinator, and tells you in your messages what is merged, what it tidied and what it kept, with the reason (uncommitted changes, work that did not land). It never forces and never deletes a branch.

volee mission close is you closing a mission yourself, without the coordinator and without a merge: it refuses a mission whose workers have not all delivered and says which; --force closes it anyway. It tidies the same way, so a worker whose work you did not merge is kept. Aborting tells every agent of the mission to stop and deletes nothing: branches, worktrees and pull requests stay where they are.

The commands that speak for you, volee msg send, volee msg answer and volee mission close, refuse to run in the shell of an agent volee launched: an agent asks you, it does not answer for you.

The interface

volee                             # the interface, on every agent of this machine
volee demo                        # the interface, on a simulated team of agents
volee demo --theme terminal       # with another theme than the configured one

volee with no command starts the daemon when it does not run, then shows the agents it knows until you quit. volee demo needs no daemon and touches nothing: it shows a fictional lead, two missions and their workers, and two sessions volee did not launch, whose states change and who write to each other and to you every few seconds, along the routes the daemon allows. Both take their theme, keys and reduced_motion setting from the [tui] table of the configuration. The interface guide describes the screen, what needs the daemon, and every key.

Hosts

Every agent volee launches runs in a volee host, a small process of its own that holds the agent’s terminal and its exact screen (how a host works). The volee host commands work on hosts directly, without the daemon, and run any command line in one:

volee host spawn -- htop                     # start a program in a new host; prints its id
volee host spawn --cwd ~/code/api --name api-tests -- cargo test
volee host ls                                # hosts, running or ended; --json for scripts
volee host peek <id>                         # its screen, as plain text
volee host attach <id>                       # take it over; Ctrl+Q comes back
volee host stop <id>                         # end its program
volee host wall                              # every running host as a wall of live screens

volee host spawn starts the host detached from your terminal, waits until it answers, and prints its id; closing the terminal does not end it. --cwd sets the program’s directory (this one otherwise), --cols and --rows its size until someone takes it over (this terminal’s otherwise), --name the name its clients show, and --linger how many seconds the last screen stays after the program ends (600). A host started this way has no harness profile: volee does not resume it after a reboot, and it is not an agent in volee ls; to have a program in the list, volee run starts it in a host and makes it an agent. volee host ls shows each host as running, exited with its code, killed with its signal, or interrupted when its host is gone without recording an end.

Every command takes --dir to use another directory of hosts than <state>/hosts (~/.local/state/volee/hosts by default). Hosts keep there a socket, a record and a log each, readable only by you. volee host wall --ids <id>,<id> shows only these hosts. The interface has a wall of its own, on every agent of its list that runs, in a volee host or not (the wall).

Isolated runs

Every path can be moved with an environment variable, which is handy for trying volee without touching your real state:

Put a custom VOLEE_SOCKET in a directory only you can enter, as the defaults are: the daemon restricts the socket to you right after creating it, and a directory that others can enter would let them connect in between (the daemon logs a warning then). The daemon replaces a stale socket left by a crash, but never another kind of file.

Configuration

volee reads ~/.config/volee/config.toml (or $XDG_CONFIG_HOME/volee, or $VOLEE_CONFIG_DIR). Every setting is optional and a missing file means the defaults.

volee config init    # write a commented example
volee config check   # validate the file and show what it sets
volee config path    # print where the file is

Unknown keys are errors, reported with their line, so a typo never turns into a setting that silently does nothing.

Example

[agents]
model = "opus"
permission_mode = "auto"
wake_timeout = 3600

[repos.billing]
path = "~/code/billing"
base = "develop"
model = "sonnet"
setup = ["bun install"]

[tui]
theme = "catppuccin-mocha"

[tui.keys]
take-over = "ctrl-a"

[tui.tools]
git = "gitui"

[agents]

Worktrees

volee creates each agent’s worktree inside its repository, at .claude/worktrees/<name>, where Claude Code keeps its own. <name> is the branch with every character other than a letter, a digit, ., _ or - replaced by -: feat/invoices becomes feat-invoices. volee adds that folder to the repository’s local exclude file so git status stays clean. The location is not configurable: Claude Code only trusts a session started from a repository you trust, and never a worktree elsewhere (see ADR 0013). Run claude once in each repository you list below and accept its trust prompt.

[repos.<name>]

One table per repository volee may launch agents in. <name> is what you type on the command line and what agents see; it uses letters, digits, -, _ and ..

Setup commands

A new worktree holds the tracked files only: no dependencies, and none of the files git ignores. setup prepares it before the agent starts (ADR 0017):

[repos.shop]
path = "~/code/shop"
setup = [
  "cp \"$VOLEE_REPO_ROOT/.env.local\" .",
  "bun install",
]

The daemon runs the commands in order, each with /bin/sh -c, in the new worktree. Besides the daemon’s environment, they get VOLEE_REPO (the repository’s name), VOLEE_REPO_ROOT (its main checkout), VOLEE_WORKTREE, VOLEE_BRANCH and VOLEE_BASE. Each may run for 15 minutes, after which it is killed with everything it started. Meanwhile the agent is listed as launching, with the command that runs; what the commands print goes to setup.log in the agent’s folder of volee’s state directory as they print it, so tail -f follows it, and volee spawn says where it is. Until the agent’s session starts, its preview in the interface and volee logs show the end of that log.

If a command fails, the launch fails: no session starts, the worktree and branch stay, and the agent is listed as failed with the command and the last line it printed. Fix the cause and run the same volee spawn again: volee reuses the worktree while git sees it clean, and runs the setup again, so keep the commands safe to run twice. Commands that write only files git ignores, such as dependencies or a .env.local listed in .gitignore, keep the worktree clean; if the setup left other files, remove the worktree and its branch before launching again. If the agent’s mission ends during the setup, the launch stops and no session starts. A mission’s coordinator works in the main checkout and runs no setup.

Some setups, each checked with volee config check:

# Bun, and a .env.local that git ignores, from the main checkout.
setup = ['cp "$VOLEE_REPO_ROOT/.env.local" .', "bun install"]

# npm, exactly as the lockfile says.
setup = ["npm ci"]

# Python with uv.
setup = ["uv sync"]

# A monorepo with a .env.local in several apps and packages.
setup = [
  '''cd "$VOLEE_REPO_ROOT" && find apps packages -maxdepth 2 -name .env.local | while read -r file; do mkdir -p "$VOLEE_WORKTREE/${file%/*}" && cp "$file" "$VOLEE_WORKTREE/$file"; done''',
  "bun install",
]

Package managers also run scripts: the project’s own and its dependencies’ (postinstall, prepare). They run in the new worktree, which shares the repository’s git configuration with your main checkout, so a script that runs git config (to set core.hooksPath, for example) changes it for every checkout of the repository. If that matters, skip the scripts (bun install --ignore-scripts, npm ci --ignore-scripts) and run the ones you need as setup commands of their own.

[messages]

A summary runs claude -p with no tools, no MCP server, none of your hooks and no saved session, in a directory of volee’s own: the model reads the thread and nothing else.

[missions]

A coordinator launches workers with its spawn_worker tool, without asking you, so this limit is what keeps a coordinator gone wrong from starting sessions without end. Launches that run at the same time all count. A coordinator that reaches the limit gets a refusal that tells it to ask you. Workers also stay in the repositories the mission names: volee compares their main checkouts, never their directory names.

[git]

To tell whether an agent’s commits are pushed, and whether its branch was merged, volee compares the branch with origin. The daemon therefore runs git fetch --prune origin in an agent’s repository at most every five minutes, in batch mode: a fetch that needs a password fails instead of waiting, and only your remote-tracking branches change (--prune forgets the ones deleted on the remote; FETCH_HEAD is left alone).

By default it fetches only the repositories of agents volee launched: their remote is part of the work volee started. A session you started yourself is yours, and so is its remote: volee reads its repository but leaves fetching to you, and compares with what your last fetch brought. Set "all" to have those repositories fetched too, or "never" to fetch only by hand (for example on a metered connection, or with remotes that need a hardware key). With fetches off, push states and merges are as current as your last fetch, and new agents start from origin/<base> as that fetch left it.

[tui]

[tui.keys]

Every key of the interface, the wall and a take over can be changed. Name the action (the interface guide lists them by context) and give it one key, a list of keys, or an empty list to unbind it. At the top of [tui.keys], the keys replace the action’s keys in every context where it has some; in a [tui.keys.<context>] table, only there:

[tui.keys]
take-over = ["enter", "ctrl-a"]   # opening an agent
new-agent = ["c", "space n"]
adopt = []

[tui.keys.agents]
first = "home"

[tui.keys.wall]
take-over = "enter"

[tui.keys.attached]
leave = "ctrl-g"

A key is written like q, G, ctrl-c, alt-x, shift-tab, enter, esc, space, home, pgdn or f5; a sequence of up to three keys with spaces between them, like g g or space n (gg works too). volee refuses, naming the action, an unknown action or context, two actions on the same key where both apply, and a key that both acts and starts a longer sequence. The leave key must be Control and a letter other than h, i, j or m.

[tui.tools]

The interface can open an agent’s worktree in your own tools. None is required and none is forced: volee offers the ones it finds, and each key below replaces what it would find.

Each value is a command line, split like a shell would (quotes, no variables or pipes) and run in the agent’s worktree. {dir} stands for the worktree and {base} for the branch the agent started from, each passed as one argument. Keep them out of sh -c '...': the base may come from a coordinator agent (volee only accepts a plain branch name, but a shell is still the wrong place for text an agent chose). An empty string turns a tool off, even when it is installed:

[tui.tools]
editor = "hx"                   # instead of $EDITOR
diff = "git difftool -d {base}"
git = ""                        # never offer lazygit
ide = "zed {dir}"

Tools that run in the terminal take it over, as taking over an agent does, and the interface comes back when they exit.

Agents of other harnesses

volee finds Claude Code sessions by itself, and launches, finds and resumes OpenCode agents too. For any other AI, there are three ways in, and they add up:

• In a tuios pane, nothing to do: tuios recognizes Codex CLI, Gemini CLI, Aider and the other programs of its list, and volee shows each as an agent in its pane, opened by enter.
• volee run starts it under volee from your terminal: it is in the list, you see its screen and you open it from the interface, like any agent. This works for any program, today.
• Joining gives it volee’s MCP tools: it can write to you, read your answers and, inside a mission, talk with the mission’s other agents, whatever AI runs them (ADR 0014).

In a tuios pane

Start the AI in a pane of tuios, as you always do:

cd ~/code/billing
codex

tuios recognizes the program in the foreground of each pane, by its name, for the harnesses of its own list (Codex CLI, Gemini CLI, Aider, OpenCode and others). volee asks it at each round, and lists each of those panes as an agent, named after the pane’s directory, with the harness tuios names (ADR 0030). From there it is an agent in a pane like any other (panes): its preview and its tile on the wall are the pane’s screen, row for row, and enter opens the pane inside volee, where you type into it; ctrl-q comes back and it goes on as before. Nothing is stopped, restarted or configured for it.

• State. It shows as idle while it runs: volee reads no state for it. When you quit the program, the agent stops, then leaves the list a minute later.
• Messages. Nothing hands it a message; join it to give it volee’s tools. The agent that joined is then a second row, the one its messages go through.
• Only in tuios. tmux does not tell what its panes run, and a plain terminal has no door: there, use volee run.
• What it was checked with. Stand-in programs carrying the names codex and gemini: what tuios and volee do with a program of that name is measured, what the real programs draw in a pane is not.

Any program: volee run

cd ~/code/billing
volee run -- codex                      # any command line, after --
volee run --name invoices -- gemini     # with a name of your choice

volee run starts the program in a volee host, in the directory you are in and with your terminal’s environment, exactly as if you had typed the command alone. Your terminal is on it at once: you use the program as usual. ctrl-q gives the terminal back and the program keeps running; it is now an agent of the list, named after its directory unless you named it (ADR 0029).

From there it is an agent in a host, like the ones volee launches: its preview, its tile on the wall and the full-screen view show its exact screen, enter opens it inside volee where you type into it, volee attach <name> opens it in a terminal, and volee stop <name> ends it. Run from a script, with no terminal, the command starts the program and prints how to open it.

What volee knows of such a program is its screen, and nothing else:

• State. A screen that changes is working, one unchanged for a few seconds is idle, a program that ended is stopped. volee cannot tell when it waits for you, and it shows as working while you type into it.
• Messages. Nothing hands it a message: you talk to it by typing into it. The composer and volee msg send say so. To give it volee’s tools, join it as well.
• No resume. When the program ends, by itself, by volee stop or with a reboot, nothing starts it again. Its row shows the end for a minute, then leaves the list; run the command again to have it back.
• One row. A program that volee also finds by itself (Claude Code in its own list, OpenCode in the process table) is listed once, as the program you ran, even when the command went through a wrapper such as npx or a shell.

For Claude Code, prefer what volee finds by itself when you can: a session in a tuios or tmux pane, or a background session, is listed with its exact state and its own name, and opens where it runs. volee run -- claude is for a plain terminal, which has no door otherwise: you get the door, with the screen-read state above.

OpenCode

volee has a profile for OpenCode (ADR 0022), measured on OpenCode 2.2.5:

volee spawn billing feat/export "Export invoices as CSV." --harness opencode

The launch dialog (n) has the same choice in its harness field. volee creates the branch and the worktree as for any agent, runs the repository’s setup commands, then starts opencode --session <id> --prompt <task> in a volee host, in the worktree, with a session id it chooses (and --auto when [agents] permission_mode = "auto"). Take it over with a or volee attach, watch it in the preview, full screen or on the wall, and stop it with volee stop, like any agent in a host.

• State. OpenCode takes no hooks on its command line, so volee reads the agent’s state from its screen: a screen that changes is working, one unchanged for a few seconds is idle, a program that ended is stopped. volee cannot tell when it waits for you.
• Messages. Nothing hands it a message while it runs. A message waits until the agent stops, then volee resumes it in a new host with opencode --session <id> --prompt <messages>.
• After a reboot. volee resumes it like a Claude Code agent, with opencode --session <id> and a prompt that says the machine restarted.
• Started elsewhere. An OpenCode agent you started yourself is found in the process table (not the background service, opencode serve --service), with its directory, and so its repository and branch. It is shown until its process ends, then leaves the list a minute later.
  • In a tuios or tmux pane, it is an agent in a pane like any other (panes): the list says which pane, its preview and its tile on the wall are the pane’s screen, and in a tuios pane enter opens it inside volee, where you type into it; ctrl-q comes back and it goes on as before. Nothing is stopped or restarted for it.
  • In a plain terminal, volee has no door on it and says so: switch to that terminal. To drive it from volee, quit it, then adopt it (A, or volee adopt): volee resumes it in a host, which only works when it was started with --session, since volee needs the session id. Or start it with volee run -- opencode next time: it then runs in a host from the start.

Join

Add volee’s MCP server to the harness’s configuration, with the name the agent should have:

volee mcp --join infra --harness codex

• --join names the agent. Starting the harness again in the same directory, with the same name and harness, finds the same agent again, with its messages.
• --harness says which AI it is (codex, gemini-cli…), so the interface can tell agents apart; other when you leave it out.
• --mission (optional) makes the agent a member of an open mission, by its title, short id or id. Members of a mission write to each other, so this is how an agent of one AI talks with agents of another. Without it, the agent writes to you, and you to it.

The directory the server runs in is the agent’s workspace: volee reads its repository and branch there. Harnesses usually start their MCP servers in your project; if yours does not, set the server’s working directory in its configuration.

Codex CLI

Codex CLI reads its MCP servers from ~/.codex/config.toml (or a project’s .codex/config.toml, for projects you trust):

[mcp_servers.volee]
command = "volee"
args = ["mcp", "--join", "infra", "--harness", "codex"]

Or with its own command:

codex mcp add volee -- volee mcp --join infra --harness codex

Check Codex CLI’s documentation on MCP for the options of your version, such as cwd or startup_timeout_sec.

Gemini CLI

Gemini CLI reads its MCP servers from ~/.gemini/settings.json, or from a project’s .gemini/settings.json:

{
  "mcpServers": {
    "volee": {
      "command": "volee",
      "args": ["mcp", "--join", "docs", "--harness", "gemini-cli"]
    }
  }
}

Gemini CLI asks before each tool call of a server it does not trust; set "trust": true on the server if you want volee’s tools to run without asking. It also has a gemini mcp add command. Check Gemini CLI’s documentation on MCP servers for that command and for the other options of your version, such as cwd or timeout.

What to expect

• State. The agent is idle while its harness runs, and stopped once the harness exits (its MCP server closes). volee cannot see when it works: the interface shows its last tool call as its activity, such as “wrote to human”.
• Messages. Nothing hands it messages on its own: there are no hooks in other harnesses to do it. They wait until the agent calls read_messages, and the server’s instructions ask the model to call it when it starts a task, after it asks a question, and before it finishes. You can also ask it to “check your volee messages”. volee msg send says so when you write to it, and a message sent while it is stopped waits for its next start.
• Missions. A member that joined is never judged by the mission’s supervisor, which judges workers only, and the coordinator hears that it joined. Joining again with another mission, or without one, changes its membership.
• Not resumed. volee never starts or resumes it: you start its harness.
• Its screen. An agent that only joined has no screen in volee: its harness runs in a terminal of yours. Start the harness with volee run to have its screen and a door on it too; the program you ran and the agent that joined are then two rows, one for the screen and one for the messages.

Daemon protocol

The daemon listens on a Unix socket (see Command line for its path) readable only by the current user. Clients speak JSON-RPC 2.0, one JSON object per line, in both directions. The Rust types live in the volee-proto crate.

Try it by hand:

echo '{"jsonrpc":"2.0","id":1,"method":"daemon.status","params":{"protocol":1}}' \
  | nc -U ~/.local/state/volee/volee.sock

Methods

Running a program

agents.run makes the program of a volee host an agent (ADR 0029). The client starts the host itself (volee host run, detached, under the daemon’s hosts directory), so that the program gets the client’s environment and directory, then gives the daemon the host’s id. The daemon reads the host’s record and registers an agent in that host, launched by the human, with the role independent, the name asked for (else the host’s own name, else the name of the program’s directory) and, as its harness, the name of the program. It refuses an id that names no file of its hosts directory (-32602), a host it does not find (-32001), and a program that already ended or a host that already is an agent (-32002); the client then ends the program it started.

The agent has no session, so nothing that needs one applies to it: its states come from its screen, no message is handed to it and nothing resumes it. agents.preview, agents.open, agents.attach and agents.stop act on its host, as for any agent in a host; once its program ended, agents.open and agents.attach are refused with words that say nothing resumes it, and the agent leaves the registry a minute later. A session or a process that a harness lists inside the host, the program itself or a process below it, is not registered a second time.

Tidying

agents.tidy follows ADR 0011: it removes nothing without delivery evidence and never deletes a branch. delivery::tidy_check decides from the registry: the agent was launched by volee, works in a worktree under <repository>/.claude/worktrees/, is not running, and its delivery evidence, checked since its last change, shows a clean tree and landed work (merged, merged pull request, or report). Otherwise the result is kept with every reason, each with a reason tag (busy, uncommitted-changes, not-delivered, not-launched-by-volee, not-a-volee-worktree, evidence-not-checked, evidence-stale, kept-by-harness, refused-by-git) and a sentence for people when displayed.

When the evidence allows it, the daemon asks the harness to delete the session (with the evidence), checks the verdict again, unlocks the worktree if the harness left it locked, and lets git remove it; git still refuses changes and commits that no branch keeps, and never forces. It then records the workspace without its worktree and forgets the agent; its events stay in the log. With dry_run, the answer is would-remove or kept, and nothing is touched.

Launching

agents.spawn creates the branch and its worktree with git, writes the agent’s hook settings and MCP configuration (readable only by you), records the agent, then starts the session in a new volee host (ADR 0019), from the repository’s main checkout with --worktree (ADR 0013). With harness: "opencode", it starts opencode --session <id> --prompt <task> in the worktree instead, for a lead or a worker; any other role there, and any other harness, is refused (-32602). A failed start marks the agent failed and keeps the worktree; the same request sent again reuses that worktree while nothing was done in it, and forgets the failed agent (ADR 0016). It refuses coordinators (missions launch them) and, for a mission, repositories the mission does not list. missions.create refuses (-32003) when the daemon has no usable Claude Code (missing or too old, as daemon.status reports), before it records anything. Otherwise it records the mission and launches the coordinator; when that launch fails, it tells the human in the mission’s thread and coordinator is null.

Joining

agents.join brings an agent of another harness into volee (ADR 0014); volee mcp --join sends it. The daemon finds the agent that joined with the same name, harness and cwd (an absolute path) and was not forgotten, or registers one (launched_by: outside, harness other with that name, role independent), records it idle, and answers whether it knew it (rejoined). With mission, which must be open, the agent is a member of that mission, and its coordinator is told; joining again with another mission, or without one, records a membership-changed event. The agent stays alive while the connection that joined stays open: when the last such connection closes, or when the daemon starts, it is stopped. Invalid names or harnesses answer -32602, a mission that is over -32002, and claude-code is refused (-32002): those sessions are found without joining.

agents.activity records a joined agent’s last action in one line (its MCP server sends one per tool call). It refuses agents that did not join.

Acting on agents

For an agent in a volee host (ADR 0019), agents.preview returns a snapshot of the host’s screen (exact, with the size of the host’s terminal: a snapshot redraws its screen in a terminal of that size only), agents.attach returns the volee host attach command for the client to run (Ctrl+Q comes back), and agents.stop asks the host to end the program. For a Claude Code background session that volee does not host, agents.attach returns the harness’s own command (claude attach <id>): nothing is stopped or resumed (ADR 0027). agents.adopt is another thing: it first stops the session, then resumes its conversation in a new host. It refuses an agent that already runs in a host and one that runs in a terminal of its own, which must be quit there first (ADR 0023).

agents.open is for a client that draws the agent inside its own screen, as the interface does. It answers with the socket of a volee host, which the client connects to with the host protocol: the host the agent runs in (view false), or a view (view true), a host the daemon starts on the session’s own door, at cols by rows: claude attach for a Claude Code background session, running or finished, and the multiplexer’s own command for a pane it can show alone (tuios pane-view). A view ends its program once no client has held its input for 15 seconds, and ends with the daemon; the session it shows is not touched. Without a socket, the agent runs in a pane only its multiplexer can show: agents.attach says how to bring it forward. It refuses (-32002) an agent in a terminal the daemon cannot reach, and says what makes it reachable.

For other agents, agents.preview, agents.attach and agents.stop act on the agent’s current harness session, as the last listing showed it; an agent volee just launched is reachable before any listing shows it. They refuse (-32002) an agent whose session runs in a terminal of its own, which only that terminal can show or control, and answer -32001 when the harness no longer knows the session. agents.stop also refuses agents volee did not launch (ADR 0011). What agents.preview returns for them is the replay of the session’s output, or the end of the setup log of an agent that never had a session: exact is false, and a client may repair it as a replay (ADR 0028).

agents.attach returns a command for the client to run in its own terminal, with the environment variables in env_remove removed; the harness keeps the agent running when the person comes back.

An agent whose session runs in a multiplexer pane the daemon found (ADR 0015) is not refused: agents.preview returns what the pane shows, each row placed with a cursor move (exact, without a size: it draws the same cells in any terminal large enough), and agents.attach returns an empty program and a focus object (multiplexer, session, steps, attach). The client runs each step, a program and its arguments, in order, in its own environment and without giving up its terminal, so that the multiplexer acts on the person’s own client. The first step focuses the pane in its session; when a later one fails, attach is the command that shows that session in a terminal (such as tuios attach work), for the client to suggest. daemon.status lists the multiplexers the daemon uses in multiplexers, with whether each answers now.

agents.diff compares the agent’s worktree (committed and uncommitted changes, and the files it created) with the merge base of the branch it started from. The text is at most 512 KiB, cut at a line break when longer, with truncated set.

Missions

missions.create opens the mission’s thread and records the mission in the planning status. From then on the daemon runs the supervisor after every batch of events that concerns the mission, and once when it starts. Its decisions are ordinary events (worker-assessed, mission-updated) and messages from volee in the mission’s thread, so every client sees them.

agents.spawn refuses (-32002) a branch of a repository where an agent already works, and missions.create a title under which a mission is already open: each refusal names the agent to write to instead (ADR 0033). When requested_by names an agent, it must be a lead, and the mission’s coordinator is registered with that lead as its parent. agents.lead refuses a lead under the name of one that runs in the same directory.

missions.request_approval is refused (-32002) unless by is the mission’s coordinator and the mission is reporting: every worker delivered, and no report waits for an answer. It posts the report as a question to the human and moves the mission to awaiting-approval. The human’s answer is an ordinary message in reply to that question (messages.send); the supervisor reads it and moves the mission to approved, or back to reporting.

No request merges: the daemon does, when a mission becomes approved (ADR 0032). It reads the workers’ evidence from git and the forge, merges the work that has not landed (a pull request on the forge, a branch into its base branch in the main checkout of a repository without a remote), reads the evidence again, and closes the mission once every merge shows in it. Otherwise it moves the mission back to reporting and posts an alert in the mission’s thread, to the human, the coordinator and the lead, that names each worker whose work was not merged, with the reason. A mission that is approved when the daemon starts is carried out then.

missions.close is the human closing a mission themselves, without a merge. It refuses (-32002) while a worker has not delivered, unless force is set, and it refuses a request made in an agent’s name (by): no agent closes a mission. Without report, the report the coordinator presented is kept, else its latest report in the mission’s thread. After a close, by the human or by the daemon, the daemon tidies the workers whose work landed, stops the coordinator, and posts one message in the mission’s thread that says what is merged, what it tidied and what it kept.

Events and replicas

Clients do not ask the daemon for “the list of agents”. They read events (events.since) and apply them to their own Registry from volee-core, exactly as the daemon does. A subscription (events.subscribe) answers with the backlog and then pushes every new event as a notification:

{"jsonrpc":"2.0","method":"events.appended","params":{"seq":42,"event":{"type":"state-changed","at":1793993747000,"agent":"ag_01jc5…","state":{"state":"working"},"detail":null}}}

Notifications arrive in log order without gaps. A subscriber that falls more than 4,096 events behind receives events.lagged (with the number of events it skipped) and is dropped; it can resubscribe with after set to the last sequence number it applied.

A client a person watches, such as the interface, subscribes with interactive set to true. While at least one interactive subscription is open, the daemon lists the harness’s sessions every two to ten seconds (two after a listing that changed something, longer while nothing changes) instead of every thirty, and a new one triggers a listing at once, so the client opens on fresh data (discovery). The subscription stops counting when it ends or its connection closes. Programs, such as an agent’s MCP server, leave it false: agents volee launched report through their hooks in real time anyway.

A one-off command that wants the sessions as they are now, such as volee ls, sends discovery.refresh before events.since. The daemon lists at once and answers when a listing that started after the request is applied, or when timeout_ms runs out; the listing then still completes in the background. Requests made while a listing runs share the next one. listed is false without a harness, after a failed listing, or after the timeout: the events then show the last listing, as before.

Rust clients get all of this from volee_proto::replica: subscribe returns the backlog and a feed of the events that follow, which drops repeats and picks up again after a lag on request (subscribe_interactive does the same for a client a person watches), and Replica keeps a Registry up to date from a feed. The MCP server reads a Replica; the interface follows an interactive feed, because it also needs the events themselves.

Errors

Standard JSON-RPC codes, plus volee’s own:

Versioning

The protocol version is 1. Adding a method or an optional field does not change it; changing or removing one does, and daemon.status tells a client which version the daemon speaks.

MCP tools for agents

Agents talk to volee, and to each other, through an MCP server that volee runs for each of them (ADR 0005). Agents launched by volee get it automatically. Any MCP-capable harness can use it too:

{
  "mcpServers": {
    "volee": { "type": "stdio", "command": "volee", "args": ["mcp", "--agent", "ag_01jc5…"] }
  }
}

The server speaks for one agent, given by --agent. It starts the volee daemon if needed.

An agent of another harness, which volee did not launch, joins instead (ADR 0014):

volee mcp --join <name> [--harness <kind>] [--mission <title, short id or id>]

The directory the server runs in is the agent’s workspace. The agent is idle while the server runs and stopped once it exits; each tool call shows as its activity. No hooks hand it messages, so the server’s instructions ask the model to call read_messages at the start of a task, after a question, and before it finishes. The guide has configurations for Codex CLI and Gemini CLI.

Agents volee launches may call every tool below without a permission prompt: their settings allow mcp__volee, so that a background agent never stalls on asking to send a message. Only a mission’s coordinator may call spawn_worker and request_approval; only a lead may call spawn_agent and start_mission. No tool merges or closes a mission: volee does both, once the human approved.

Tools

whoami

The caller’s identity: id, name, role, state, repository, branch, worktree, base branch, mission and parent. For a lead, also repos: the repositories of the person’s configuration, which it can name when it launches.

list_agents

Every agent volee knows, those that need attention first. Each entry has an id, a name, a role, a state, the repository and branch, the mission, the parent, the harness, and can_message: whether the caller may write to it. The caller’s own entry is in the list too, with you: true in place of can_message: a lead that reads the list before it launches does not take itself for a duplicate.

send_message

Routing follows ADR 0006: inside a mission every member writes to every member; otherwise an agent writes to its parent, its children, its mission’s coordinator, the agent that requested its mission, and the human. A refusal comes back as a tool error that explains why, so the model can correct itself.

A message to an agent whose session ended resumes it, unless the human stopped that agent or its mission is over: then the message waits. When the human stops a worker of a running mission, volee tells the coordinator in the mission’s thread, so that it plans without that worker.

read_messages

Messages addressed to the caller, oldest first, with sender, kind, id and references. Returned messages are marked as read.

Messages also reach the agents volee launched without this tool: at the end of a turn through the Stop hook, or by waking an idle agent. An agent that joined with --join has no hooks: this tool is the only way its messages reach it.

ask_human

Asks the human a question that only they can decide, with the answers they choose from. The question stays on top of the human’s messages, in the interface and in volee msg questions, until they answer it.

The answer reaches the agent as an answer message in reply to the question, like any other message. Its text is one of the options, in the option’s own spelling, when the human picked one; anything else is the human’s own words and is never a yes. The tool returns at once: the agent ends its turn and volee wakes it with the answer.

send_message with the kind question still asks a question without options. Options on anything but a question to the human are refused (ADR 0031).

report

Tells the agent’s parent, its mission’s coordinator and the human that the task is done, blocked or failed. A done report is a report message; blocked and failed are alert messages.

spawn_worker

For a mission’s coordinator: launches a worker on a new branch, in its own worktree of one of the mission’s repositories. volee tells the coordinator when the worker stops, with the evidence it checked. A mission launches at most [missions] max_workers agents (8 by default); past it, the tool returns an error that tells the coordinator to ask the human.

spawn_agent

For a lead (ADR 0033): launches an agent on one task in one repository, on a new branch in its own worktree. The agent’s parent is the lead: it reports to it. The arguments are those of spawn_worker; repo is a name whoami lists, or an absolute path. volee refuses, with the name of the agent to write to instead, when an agent already works on that branch of that repository.

start_mission

For a lead: starts a mission in its name. Its coordinator answers to the lead: its reports go to it, and each may write to the other.

volee refuses, with the name of the coordinator to write to instead, while a mission is open under the same title.

request_approval

For a mission’s coordinator, once volee told it that every worker delivered: presents its report to the human and asks for their approval (ADR 0032).

volee posts the report as a question from the coordinator to the human, in the mission’s thread, with the answers ok merge and no (ok close and no for an analysis mission); the lead that asked for the mission reads it too. The mission waits: nothing is merged or closed before the human answers. The tool returns at once, and the coordinator ends its turn. volee then tells it what the answer was. On the approving answer, volee merges each worker’s work itself, closes the mission, tidies its workers and stops the coordinator, which has nothing more to do; if a merge does not go through, volee tells it why, and it presents its report again once what blocks is settled. On any other answer, nothing is merged and the mission stays open.

Refused, with the reason, when the caller is not the coordinator, while a worker has not delivered (a report presented for approval says the work is ready), while the human has not answered the report already presented, and once they approved.

Architecture overview

This page explains how volee is built and why. Each significant choice has an architecture decision record (ADR) in Decisions.

What volee is for

Developers now run many coding agents at once: several Claude Code sessions, each in its own git worktree, sometimes coordinated by another agent. volee answers four questions at a glance, from a terminal:

1. Who is running? Every agent on the machine, with its state, its repo, its branch and its worktree.
2. Who needs me? Permission prompts, questions and finished work, sorted by urgency.
3. What did they do? Commits, diffs, pushed or not, pull request and checks.
4. Who talks to whom? Messages between agents and with you, as threads and as a living graph.

It also runs missions: a goal that spans one or more repositories, split by a coordinator agent and delivered by worker agents.

Principles

• An agent is not a pane. An agent is a unit of work done by one or more harness sessions. Panes, tabs and terminals are only places where an agent can be shown. See ADR 0001.
• A host holds each agent’s terminal. Every agent volee launches runs in a volee host: one small process per agent that holds its pseudo-terminal and its exact screen, and survives the interface, the daemon and the terminal that started it. Any number of watchers read the screen without changing it, and one person at a time takes the agent over. See Hosts and ADR 0019, which supersedes ADR 0002.
• Every agent on the machine, opened where it runs. Agents started elsewhere are found through their harness and the process table, and shown: one row per session the harness lists, gone when the session is. Opening one puts a terminal on its own door (claude attach, tuios pane-view) in a view, a host the daemon runs for as long as someone uses it; volee never stops, forks or restarts a session it did not start. Adopting one, which moves its conversation into a host, is a choice. See ADR 0023 and ADR 0027.
• One source of truth. A small daemon (volee daemon) keeps the registry, the event log, the messages and the missions in SQLite. Every client (the TUI, the CLI, the MCP server used by agents) reads and writes through it. See ADR 0003.
• Evidence before action. volee never removes a worktree, stops a session or closes a mission on a guess. Cleanup needs delivery evidence (a merged branch, a merged pull request, a delivered report). See ADR 0011.
• Your tools, not ours. Multiplexers, editors and git clients are optional integrations. volee works in any terminal and never asks you to install lazygit, a specific editor or a specific multiplexer.

Components

flowchart LR
  subgraph Hosts [in volee hosts]
    A1[Claude Code<br/>worker]
    A2[Claude Code<br/>coordinator]
    A4[OpenCode<br/>worker]
  end
  subgraph Elsewhere [started elsewhere]
    A3[Claude Code session<br/>started by hand]
    A5[OpenCode<br/>started by hand]
  end
  subgraph volee
    D[(volee daemon<br/>registry, events,<br/>messages, missions)]
    T[volee TUI]
    C[volee CLI]
    M[volee mcp<br/>stdio server]
    H[volee hook]
  end
  A1 -->|hooks| H --> D
  A2 -->|hooks| H
  A1 -->|MCP tools| M --> D
  A2 -->|MCP tools| M
  D -->|"screen snapshots"| A4
  D -->|"claude agents --json"| A3
  D -->|"ps, lsof"| A5
  D -->|"git, gh"| R[(repositories<br/>and worktrees)]
  T <-->|JSON-RPC over a Unix socket| D
  C <--> D
  T -->|"take over, watch"| A1

Everything ships as one binary, volee, with subcommands:

Sources of truth

The daemon merges these sources into one model. Each source is authoritative for one kind of fact:

Hook events are written to an append-only event log first, then folded into the current state. When the daemon is not running, volee hook appends to a spool file that the daemon ingests at start, so no event is lost.

Talking to agents

volee hands messages to Claude Code agents through three documented mechanisms, never by typing into their terminal, even when it hosts them. All three were verified on Claude Code 2.1.319 (see ADR 0006):

OpenCode has no hooks: a message waits until the agent stops, then volee resumes it in a new host with opencode --session <id> --prompt <messages>.

Agents send messages through the volee MCP server (send_message, read_messages, list_agents…), which works for any harness that speaks MCP. That is how an agent of one AI can talk to an agent of another.

After a reboot

A reboot ends every host, but the harness has saved the conversation and the worktree is on disk. When the daemon starts, it looks for agents whose host is gone without recording an end, and resumes each one in a new host with its harness’s resume command: a working agent with a first prompt that says the machine restarted, an idle one at its prompt. Agents you stopped, agents of a mission that is over, agents that were done or failed, and agents whose host died again soon after such a resume (a crash, not a reboot) stay down. The daemon starts the first time volee is used, or at login after volee daemon install. See ADR 0024.

Missions

A mission has a coordinator and workers. The coordinator is split in two on purpose (see ADR 0007):

• a supervisor program inside the daemon waits, retries and checks delivery evidence. It costs no tokens while it waits.
• a coordinator agent (an LLM) splits the goal, spawns workers through MCP, answers their questions and presents its report to the person. It never merges: once the person approved, the daemon merges the work itself and closes the mission (ADR 0032). It is woken by messages; it never polls.

Missions are of two kinds: change missions deliver branches and pull requests; analysis missions deliver reports.

Crates

The dependency graph points inward: volee-core knows nothing about Claude Code, SQLite, git or terminals. That keeps the domain testable without IO and leaves room for more harnesses.

Files on disk

volee follows the XDG base directory layout on every platform:

Performance budget

• Daemon idle: under 1 % CPU and under 30 MB of memory. Measured on the 0.1 release build: 9.4 MB, and 0.03 s of CPU in two minutes.
• Session discovery: each claude agents --json --all costs about 0.17 s of CPU and starts a Node process of about 150 MB. Listing every two seconds would cost about 8.5 % of a core for as long as the interface is open, so the daemon lists every two seconds only after a listing that changed something, backs off to every ten seconds (about 1.7 % of a core) while nothing changes, and lists every thirty seconds (about 0.6 %) when no interface is open.
• TUI frame: under 5 ms at 200x60. Animation ticks only run while something moves.
• Git is never polled more than once a minute per worktree, unless an event (an edit, a commit, a push) asks for it.

Domain model

The domain lives in the volee-core crate. It performs no IO and never reads the clock, so every rule below is unit-tested.

Event sourcing in one page

volee’s state is a registry built by applying events in order. The daemon validates an event, appends it to the log, applies it to the in-memory registry and notifies subscribers, in that order. Restarting the daemon replays the log.

flowchart LR
  H[hook payloads] --> D{daemon}
  L[harness listing] --> R[reconcile] --> D
  C[commands: spawn, send, forget...] --> D
  D -- append --> E[(event log)]
  D -- apply --> G[registry]
  G -- snapshot + changes --> T[TUI, CLI, MCP]

Entities

Identifiers are ULIDs, so they sort by creation time.

Agent states

Lists sort by urgency: needs-input, failed, working, launching, done, idle, stopped, lost, and the most recent change first within a group.

Events

Reconciliation

reconcile compares a harness listing with the registry and returns events:

• a listed session of a known agent updates its state only when the coarse category differs, so a richer state from hooks (for example “permission for Bash”) is never overwritten by a coarser one;
• a live session nobody owns becomes an independent agent; finished sessions nobody owns are history and are skipped;
• when a complete listing no longer contains an agent’s current session, the agent becomes stopped (it ran in a terminal) or lost (it ran in the background). It never becomes done because it disappeared.

Two rules run before it, each on the listing and the one before. A session that changes its id inside the same process keeps its agent (continued). And a session in a terminal that stops being listed while its process still runs did not end: its conversation went on in the background, under another session id, and the agent takes the background session that continues it (moved_to_background). The daemon reads the process table for it, and a background session that just started beside a session in a terminal waits five seconds before it becomes an agent of its own (ADR 0034).

The daemon runs it (module discovery of volee-daemon) against claude agents --json --all, which costs about 0.17 s of CPU and starts a Node process each time, so the cadence follows who watches and what changes:

• when the daemon starts, it lists at once;
• while an interactive client (the interface) is subscribed, it waits two seconds after a listing that changed something (a session linked to its agent, or reconciled events), and twice as long after each listing that changed nothing, up to ten seconds (discovery_interval and max_discovery_interval of its configuration);
• with no interactive client, it waits thirty seconds (idle_discovery_interval);
• a new interactive subscription lists at once, so the interface opens on fresh data, and so does a discovery.refresh request, which answers once a listing that started after it is applied (volee ls sends one, and so does the interface every two seconds while it waits for a session to leave its terminal; requests made meanwhile share the listing). Both bring the two-second wait back.

Hook events never shorten the wait: agents volee launched report through their hooks in real time whatever discovery does, and resetting on them would keep the shortest wait exactly while agents work. Only sessions started elsewhere, and sessions that end without a word, show up later while nothing changes or nobody watches. Each wait starts when the previous listing ends, so a slow listing on a loaded machine never runs back to back. The listing runs outside the state lock, so a slow claude never blocks requests; a failing listing changes nothing (so the wait keeps growing) and is logged once, then again when it works. When Claude Code is missing or too old, volee daemon status says why and discovery stays off.

The mission supervisor

supervisor::supervise is the program half of a mission (ADR 0007). The daemon calls it after events that concern a mission and applies its decision: events to commit and notices to send from volee in the mission thread. It is idempotent: once its own events are applied, calling it again returns nothing.

Delivery evidence depends on the mission kind:

• change: commits, all pushed, an open or merged pull request, and a clean tree; a merged branch or pull request always counts. In a repository without a remote (PushState::NoRemote) there is nowhere to push and no pull request to open: commits and a clean tree are enough;
• analysis: a report message from the worker.

A pull request counts only when its head commit is the branch’s tip (Delivery::pull_request_at_tip): an old pull request of a reused branch name, or one read before the branch moved on, proves nothing about the work as it is.

A change worker is judged only on evidence read since it stopped (checked_at at or after its state_since): evidence read before may miss its last commits, push or pull request, and evidence never read is empty, so the verdict waits for the daemon’s next check, which the stop itself triggers (and the daemon’s start, for a mission’s worker never read). The coordinator therefore never hears “not delivered” just before “delivered”. Judging evidence never read once told a coordinator that a worker which committed, reported and stopped within a few seconds had “no commits”: its branch had not been read yet. A daemon without a git source reads no evidence: it judges what its clients send, with the time it was read.

Every new or changed verdict is recorded as worker-assessed and told to the coordinator. When every worker delivered, the mission moves to reporting and the coordinator is asked, once, to present its report to the human. A delivered worker that works again (to answer its coordinator, say) keeps its delivery until a new verdict says otherwise; a new verdict that is not delivered moves the mission back to running.

The end of a mission is the human’s decision (ADR 0032):

supervise reads the human’s answer with Registry::answer_to and Message::chosen: only the approving option, chosen exactly, approves; anything else moves the mission back to reporting and tells the coordinator. Only the answer to the report presented last counts, and only while the mission is awaiting-approval. If a worker’s verdict stops being delivered while a report waits or after it was approved, the mission goes back to running and the human and the coordinator are told that the report no longer stands.

In the daemon (volee-daemon, module missions), supervision follows every commit: the daemon finds the missions the new events concern (an agent of the mission changed state or delivery, posted a message, or registered, or the human answered the report its coordinator presented), first records a newly registered coordinator on its mission, then runs supervise and commits the decision in one batch. The supervisor’s own events never trigger another round. It also runs over every open mission when the daemon starts, which catches up after a crash between a commit and its follow-ups, or after an upgrade that changed the rules. A failure there is logged and never fails the request that caused it: the events that triggered it are already committed.

Rules

• Routing (Registry::check_route): people and volee write to anyone; agents write to people; between agents, members of the same mission write to each other, and otherwise an agent writes to its parent, its children, its mission’s coordinator and the agent that requested its mission.
• Cleanup (delivery::tidy_verdict): a worktree may be removed only when the agent is not busy, the tree is clean, and the work is delivered (merged, merged through a pull request, or reported). Every missing condition is reported at once. delivery::tidy_check adds what makes a worktree volee’s to remove: the agent was launched by volee, the worktree lies under <repository>/.claude/worktrees/, and the delivery evidence was checked since the agent’s last change (stale or missing evidence proves nothing). An agent whose launch failed before any session started, with a clean tree and no commit of its own, needs no delivery: nothing was ever done in its worktree (ADR 0016). The branch is never part of the decision: it is always kept.
• Delivery evidence (delivery::Delivery) describes the agent’s branch: commits counts its commits that the base branch does not have, and tip is the commit it was computed from. A merge leaves no commit of the branch outside the base branch, which looks exactly like a branch that never had any, so the evidence carries a memory: unmerged_tip, the last tip seen with commits of its own. merged_into_base is true only once that commit is part of the base branch. The daemon passes the previous unmerged_tip back to git on each check; delivery-updated events keep it across restarts. checked_at is when the daemon began the check that produced the evidence, which tells the supervisor whether it is fresh (above). The pull request carries its head commit, so the supervisor and cleanup count it only at that tip. How git computes each fact, how a pull request is matched to the branch, and when the daemon checks, is described in Git.

Hosts

Every agent volee launches or adopts runs in a volee host: one small process per agent that holds the agent’s pseudo-terminal and its exact screen, and serves both on a private Unix socket. The decision is ADR 0019; the code is the volee-host crate, with the screen kept by volee-term over libghostty-vt (ADR 0020). This page explains how a host works.

The process

The daemon starts a host with volee host spawn, which starts volee host run from the same volee binary, with nothing on its standard streams, and waits until the host answers on its socket (five seconds at most). The daemon names each host after its agent, with a suffix of its own, so that a resumed agent gets a new host. The host then:

• leaves the session and the terminal that started it, so that closing that terminal, quitting the interface or stopping the daemon does not end it;
• binds its socket first, readable and writable by you only, so that a socket that cannot be bound never leaves a program running;
• starts the agent’s command line in a new pseudo-terminal, in the agent’s directory, with TERM=xterm-256color, COLORTERM=truecolor and VOLEE_HOST set to its id;
• feeds everything the program writes into a terminal emulator, so that it always knows the exact screen, with 1,000 lines of history.

One terminal thread owns the screen and every decision; the threads that read the program’s output, write its input, wait for its end and serve clients only talk to it. Output, snapshots and input are therefore handled in one order.

A host’s size, before anyone takes the agent over, is 160 columns by 45 rows for the agents the daemon launches, and the starting terminal’s size for volee host spawn (or --cols and --rows).

Files

Hosts live in <state>/hosts/ (~/.local/state/volee/hosts/ by default), a directory volee creates with mode 0700. Each host has three files, named by its id:

A record with no exit and no host answering on the socket is what a reboot leaves: the daemon resumes such an agent in a new host (ADR 0024), and volee host ls shows the host as interrupted.

The protocol

A frame is a 4-byte big-endian length, a 1-byte kind and a payload of that length, at most 64 MiB. Control payloads are JSON; screen bytes and keys are raw.

A client says hello within five seconds, or the host drops it. Each side names its protocol version first: a host can outlive an upgrade of volee, so a newer volee must keep speaking the versions of the hosts still running. The protocol is at version 1.

Watchers and the input owner

A client says in its hello what it wants:

• A watcher receives a snapshot of the screen, then the program’s output as it comes. It never writes and never changes the size. The preview, the full-screen view, the wall of screens, volee host peek and the daemon are watchers; any number of them can read an agent at once.
• The input owner also sends keys and its terminal size. There is one at a time. Its size becomes the program’s size (at most 1000 columns or rows), and stays when it leaves. A new input owner takes the input from the previous one, which receives input_taken, is disconnected and returns to its caller.

volee attach, a in the interface and volee host attach connect as the input owner (ADR 0021). The client puts the person’s terminal in raw mode, switches it to the alternate screen, clears it and writes the snapshot. It then forwards the person’s keys without Ctrl+Q, which it recognizes in every encoding: the plain byte 0x11, the kitty keyboard protocol (CSI 113 ; 5 u, with any event type) and xterm’s modifyOtherKeys (CSI 27 ; 5 ; 113 ~). Ctrl+Q ends the take over and never reaches the agent. On the way out, the client turns off what the agent may have left on (mouse reporting, focus events, bracketed paste, synchronized output, application cursor keys and keypad, the scrolling region, the cursor style, modifyOtherKeys, kitty keyboard flags, an open hyperlink, color scheme reports, a hidden cursor) and restores the person’s screen.

Snapshots

When a client connects, the host renders its screen as VT sequences (text, colors, cursor, modes, keyboard protocol, scrolling region, tab stops) and sends that snapshot before any further output. A watcher builds its own copy of the screen from it, then follows the stream. The host reads the program’s output in chunks cut between complete sequences and characters, so a snapshot never falls in the middle of one.

Synchronized output. Agents’ interfaces wrap their redraws in DEC mode 2026 so that a terminal shows each frame whole. While the program is in such an update, snapshots wait for its end, one second at most, so that no client starts from half a frame.

Resizes. When the input owner changes the size, every watcher receives resized and a fresh snapshot at the new size.

Terminal queries

Programs ask their terminal questions: device attributes, cursor position, colors, version, keyboard protocol, size. While an input owner is connected and up to date, its own terminal sees the questions in the output and answers them. While none is, the host answers them from its emulator, so an agent nobody watches never waits for an answer. A snapshot holds state, not the stream, so replaying one never asks a question again.

Slow watchers

Each client has a queue of 256 frames. A watcher that falls behind stops receiving output, and gets a fresh snapshot once it has drained its queue: the program is never slowed down by a watcher. A client that stops reading for 30 seconds while it waits for a snapshot is dropped.

The end of a program

volee stop, volee host stop and a Stop frame end the program like a closed terminal would: SIGHUP to its process group, then SIGKILL five seconds later if it is still there. When the program ends, by itself or not, the host waits half a second for its last output, records its exit code or signal, sends exited to every client, and keeps the last screen for ten minutes (--linger, in seconds, for volee host spawn), so that the daemon and the interface can still show it. Then it removes its socket and exits; the record stays.

How the daemon uses hosts

The daemon knows each agent’s host from its launch: the agent’s location is volee host, with the host’s id. It takes a snapshot to answer a preview, gives the client the volee host attach command for a take over, and asks the host to stop the program for volee stop. For the hosted agents whose harness has no hooks (OpenCode), it takes a snapshot of each after every look for sessions: a screen that changed is working, one unchanged for about six seconds is idle, a program that ended is stopped. When the daemon starts, it resumes the agents whose host is gone without recording an end (ADR 0024).

Views

A session volee did not start has no host: it runs in Claude Code’s background, or in a pane of a multiplexer. To show it inside the interface and type into it, the daemon runs the session’s own door in a host, a view (ADR 0027): claude attach <id> for a Claude Code background session, tuios pane-view for a tuios pane. agents.open answers with the view’s socket, and the interface connects to it as to any host, in edit mode.

A view differs from an agent’s host on three points. It runs in a thread of the daemon, under <state>/views, and ends with it. It ends its program once nobody has held its input for 15 seconds (idle_exit, also volee host spawn --idle-exit <seconds>): the program is a door, so ending it ends nothing else. And it leaves no file: its socket and its record go when it ends, and a daemon that starts clears what a killed one left.

Limits

• An agent survives the interface and the daemon, but not its host: a host that crashes ends its agent, which the daemon resumes the next time it starts, as after a reboot.
• Each host costs a process and the memory of its emulator.
• Claude Code’s own supervisor (reaping idle background sessions, claude attach) does not apply to the agents in hosts.
• The protocol is a compatibility surface between versions of volee.

Claude Code adapter

The volee-harness crate is how volee talks to Claude Code. It relies only on documented commands and hooks, never on Claude Code’s internal files (ADR 0004). Everything on this page was measured on Claude Code 2.1.319 or taken from its documentation, as marked; volee needs 2.1.319 or newer, the version it was measured on, and says so at startup when the installed version is older.

The daemon uses the adapter through the Harness trait; the same crate holds the OpenCode profile (ADR 0022, Agents of other harnesses). Every command runs through a CommandRunner with a timeout, which lets the tests replay recorded output instead of running claude.

Commands

Every agent volee launches or adopts runs claude interactive inside a volee host (ADR 0019, Hosts), started through volee host spawn:

Background sessions (claude --bg) are the ones volee 0.7 launched, and any you start by hand. volee shows them and does not drive them:

A background session volee did not start is opened with claude attach <id>, in the person’s terminal (volee attach) or in a view inside the interface (ADR 0027): the same session in the same process, running or finished. The view runs in the session’s directory, so that Claude Code’s own agents view, one key away in claude attach, opens in a directory the person already trusts it with. Adopting a session (ADR 0023) is something else: it stops it with claude stop and resumes its conversation in a host. A conversation whose worktree still exists resumes in that worktree rather than with --worktree from the main checkout: a repository Claude Code trusts covers its worktrees, and in one it does not trust yet Claude Code asks in the host instead of exiting.

<id> is the id of a background session, kept exactly as claude agents lists it (the session’s handle). Interactive sessions started by hand have no handle: volee shows them but cannot stop or delete them, and previews and reaches only the ones that run in a tuios or tmux pane, through the multiplexer (ADR 0015).

claude logs replays the session’s recent drawing, not a log of its text: rows placed by cursor moves from the top left of the session’s own terminal, which can be far wider than 200 columns, some of them (the lines of a diff) padded with colored blanks to its right edge, and nothing for what was drawn before the replay starts, such as the frame of the prompt. The interface replays it in a terminal emulator at least as wide as the widest row it writes, so that no row wraps onto the next, and keeps a run of blank rows as one, so that the end of the conversation stays in view (crates/volee-tui/src/preview.rs; measured on 2.1.319 with a session 308 columns wide). It is one of the reasons volee no longer launches background sessions (ADR 0019): a host holds the whole screen from the start.

Every launch passes the agent’s settings file (--settings: volee’s hooks, a rule that allows volee’s own MCP tools, and a status line that tells volee how much of its context the agent uses, then shows the person’s own, ADR 0035) and its MCP configuration (--mcp-config with --strict-mcp-config, so the agent loads volee’s tools and nothing else). The permission mode and tool rules come from volee’s configuration only, never from an agent’s request, and there is no way to ask for bypassPermissions. Every launch and resume passes --permission-mode: the configured mode, else manual, never the person’s own default, which may skip every check.

Every value travels inside its option (--name=alpha, not --name alpha), so no value can be read as an option and no list option can swallow the next argument; Claude Code 2.1.319 accepts this form and rejects unknown options (measured on claude agents, read-only). The prompt comes last, after --. A one-word prompt gets a trailing newline and a prompt starting with - a leading one, so that no prompt can run a Claude Code subcommand such as claude update or be read as an option.

Environment and directories

Claude Code sets variables in the environment of the processes it starts (shell commands, hooks, MCP servers, background sessions) that tie them to one session: CLAUDECODE, CLAUDE_CODE_SESSION_ID, CLAUDE_CODE_ENTRYPOINT, CLAUDE_CODE_MESSAGING_SOCKET, CLAUDE_CODE_MESSAGING_TOKEN, CLAUDE_JOB_DIR, CLAUDE_PID, CLAUDE_EFFORT and a few more. volee removes all of them from every claude it runs, so a daemon started from inside an agent never launches or controls sessions as that agent. The user’s own configuration variables, such as CLAUDE_CODE_SUBAGENT_MODEL, are kept.

Queries and controls (--version, agents, stop, rm, logs) run from /, a directory that always exists and holds no project settings; launches run in the agent’s worktree.

Session states

Background sessions report a state; interactive sessions only report the status of their process, which is also the fallback when state is missing or unknown.

Each listed session also carries its id, its process id while it runs, and when it started. Hooks refine these states for the agents volee launched, for example with the tool that waits for permission. The agents volee runs in hosts are interactive sessions, so their hooks carry most of their state.

Hooks

The settings file of an agent adds one hook per event to the user’s own hooks; the user’s settings file is never edited. Each hook runs volee hook <event> --agent <id> with a ten-second timeout (except SessionEnd, which keeps Claude Code’s short exit budget), and the Stop and SessionStart events have a second handler that waits for messages while the agent is idle: after a turn, and from the start of a session that waits at its prompt without one (an adopted agent). The daemon keeps one waiter per agent, the newest. Claude Code gives that waiter 30 seconds more than its own wait, which is at most a day, so it always ends on its own:

"Stop": [{ "hooks": [
  { "type": "command", "command": "/usr/local/bin/volee hook stop --agent ag_01jc...", "timeout": 10 },
  { "type": "command", "command": "/usr/local/bin/volee hook wait --agent ag_01jc... --timeout 3600",
    "asyncRewake": true, "timeout": 3630 }
]}],
"permissions": { "allow": ["mcp__volee"] }

Messages

Messages reach a working agent through the Stop hook, which prints {"decision":"block","reason":"<messages>"}, and an idle agent through the waiter, which exits with status 2 and the messages on standard error (ADR 0006).

The text cannot impersonate anyone: only volee writes the [n] question from ... lines, every line of a message body is quoted with > , and sender names and references are cut to one line without control characters. A delivery holds at most 8,000 characters (Claude Code drops hook output beyond 10,000); messages that do not fit are counted, and the agent is told to read them with the MCP tool read_messages.

Trust, deletion and session ids

What the adapter knows, and how it knows it:

• Untrusted directories (documented). claude --bg checks workspace trust before it starts. Without a terminal to ask in, it refuses with Workspace not trusted. Run `claude` in <dir> once and accept the trust prompt, then retry. (two variants name the home directory and a directory that cannot be found). volee reports it as UntrustedDirectory with the directory. In a host, claude runs interactive, with a terminal to ask in; the guides still ask you to run claude once in each repository before volee launches agents there.
• Trust and worktrees (measured with 2.1.319 in a trusted sandbox repository, clean environment). Trust is recorded per path, and a repository nested in a trusted folder does not inherit it. A worktree made with git worktree add is untrusted wherever it lives, even under a trusted repository’s .claude/worktrees/. From the trusted main checkout, claude --bg --worktree=<name> works, and when .claude/worktrees/<name> already exists Claude Code reuses it on its current branch and locks it. That is how volee launches every agent, now without --bg, in a host (SpawnSpec::worktree, ADR 0013).
• Resuming (measured). From the trusted main checkout, claude --bg --worktree=<name> --resume=<session id> continues a stopped session’s conversation in its worktree, as a fork with a new id. volee 0.7 resumed agents this way to deliver messages (ADR 0006); volee now runs the same command without --bg, in a new host. Once two sessions record the same worktree, claude rm refuses to delete it and offers no way to force it. The resumed session starts its MCP servers again, but the conversation it continues may say that the volee server disconnected (it stopped with the old session). A resumed model took that for the current state and wrote that it could not answer, with its tools connected, so volee’s resume prompt starts by saying that the tools work in the new session.
• Unknown sessions (measured). claude stop and claude logs answer No job matching '<id>'. Run 'claude agents' to list running sessions., claude rm answers No job matching '<id>', all with exit status 1. volee reports UnknownSession.
• Deleting a session (measured for the cases below). claude rm deletes a worktree Claude Code created for the session. For a worktree that existed before the session (every agent volee launches), it refused while the branch had commits it could not find on a remote: it kept the session and the worktree, still locked, said kept <id> (volee reports SessionKept) and offered --discard-unpushed <token>, which volee never passes. volee still refuses to delete a session whose directory is in a linked git worktree unless the daemon passes WorktreeRemoval::Delivered, which it does only after tidy_verdict found delivery evidence (ADR 0011).
• Choosing the session id (documented). --session-id <uuid> is documented as a general option. volee passes a new random UUID with every launch in a host, so the daemon knows the session before its first hook. Its effect with --bg is neither documented nor measured, so the background launches of volee 0.7 did not use it: the daemon learned a new session’s full id from its first hook or the next listing.

Tolerance

Claude Code evolves quickly, so the adapter reads its output defensively:

• Unknown fields are ignored, every event-specific field is optional, and a field with an unexpected type is treated as missing.
• A listing element that cannot be read is skipped and marks the listing as incomplete, so it can never make an agent look gone.
• Terminal escape sequences and extra lines around the backgrounded line are ignored.

Git

volee reads repositories through the Git trait of the volee-git crate (ADR 0010). Its implementation runs your own git executable, so volee sees what you see, your configuration included. Code that depends on git is tested against a fake implementation of the trait; the implementation itself is tested against real temporary repositories, also under a deliberately hostile git configuration.

How volee runs git

• Every command runs as git -C <dir> --no-optional-locks ... with standard input closed. Queries never change a repository, and never refresh the index of a worktree an agent is working in.
• git never waits for you, and nothing it starts can read your keystrokes. Terminal prompts are disabled (GIT_TERMINAL_PROMPT=0, GCM_INTERACTIVE=never, SSH_ASKPASS_REQUIRE=never), ssh runs in batch mode for fetches and checkouts unless you chose your own ssh command (GIT_SSH_COMMAND, GIT_SSH or core.sshCommand), and each git runs in a process group of its own. A fetch that needs credentials fails instead of hanging: use a credential helper or an SSH agent.
• Messages are read in English (LC_ALL=C) and only machine-readable formats are parsed. Your configuration cannot change what volee reads: untracked files are always looked for, submodule changes always count, and diffs are produced without colors, external diff programs, relative paths or custom prefixes.
• Queries time out after 30 seconds, creating or removing a worktree after 10 minutes, a fetch after 5 minutes. A command that times out is stopped with everything it started: SIGTERM first, so git can remove its lock files and half-made worktrees, then SIGKILL two seconds later. At most four commands run at the same time.
• A fetch forgets remote branches deleted on the remote (--prune) and does not overwrite FETCH_HEAD.

The base branch

Delivery evidence compares an agent’s branch with its base branch (main, develop…). volee uses origin/<base> when that remote-tracking branch exists, because agents branch from it and pull requests merge into it, and the local branch otherwise.

Delivery evidence

ADR 0011 lets volee remove a worktree only on evidence. The evidence describes the agent’s branch, not wherever its worktree happens to point: when HEAD is detached or another branch is checked out, volee says so and still reports on the branch. Here is how each fact is computed:

Proving a merge needs memory. A branch whose commits were merged has no commit left that its base branch lacks, exactly like a branch that never had any. So the evidence records the last tip seen with commits of its own (unmerged_tip), and the next check, given that memory, reports the work as merged once that commit is part of the base branch. The daemon keeps the memory in its delivery-updated events. Some consequences are worth knowing:

• A branch never seen with commits of its own is never “merged”, even though its tip is in the base branch: fast-forwarding an empty branch to a newer base proves nothing.
• New commits after a merge are new work: the branch is not merged again until they are.
• A branch that was merged and then deleted still counts as merged.
• A squash-merged branch is never in its base’s history: its evidence is the merged pull request, which comes from the forge.

When the daemon checks

The daemon keeps the workspace and evidence of every agent up to date by itself, sessions volee did not launch included, so the interface and the mission supervisor never wait for git:

• Workspaces. When an agent registers, or its working directory changes, the daemon reads where the directory sits: the repository (named after its [repos.<name>] entry in the configuration when one matches, otherwise after its folder), the main checkout, the worktree when it is a linked one, the branch, and the base branch (the one already known, else the configured one, else the repository’s default branch). The branch an agent was launched on, or first seen on, stays its branch even when HEAD moves.
• Evidence. It is read again the moment an agent finishes a turn, stops or fails, when the supervisor judges it, and every minute for live agents. The previous evidence’s unmerged_tip is passed back, so merges are proven. Before reading an agent’s evidence, the daemon fetches its repository, at most every five minutes and in batch mode, when the [git] fetch setting allows it: by default for agents volee launched, never for sessions it only discovered, whose remotes belong to the person who started them. A delivery-updated event is recorded only when the evidence changed, or when it is the first check since the agent’s state changed, which the supervisor waits for.
• git and the forge never run under the daemon’s state lock or on a request path: they run on background threads, for four agents at a time and one job per agent, and triggers that arrive meanwhile are merged into the next job. A failure is logged and the next trigger tries again.

Pull requests

With the GitHub CLI installed and signed in, the daemon looks up the pull request of each agent’s branch, in the repository’s directory so gh finds the GitHub repository from its remotes, and maps its state (draft, open, merged, closed) and its checks (passing, pending, failing). A branch is looked up at most once a minute, and again right after its agent stopped. When gh is missing or signed out, pull requests stay unknown and volee daemon status says why. volee never sees a token: gh uses your own sign-in.

A branch name alone does not identify a pull request: the name may have been used before (an old pull request, merged long ago), and forks may have branches of the same name. gh pr list --head <branch> --state all returns the ten most recent pull requests with that name, and volee keeps the most recent one that is really the branch’s:

• its head repository is the one origin points to (owner/name, read from git remote get-url origin); when origin is not a repository on a forge, no pull request is the branch’s;
• its head commit is the tip of the agent’s branch, exactly. A pull request whose head is a later commit (someone pushed to it from elsewhere) counts once the agent’s branch has that commit too.

The pull request records its head commit, and counts as delivery evidence only while the branch is still at that commit: commits made after it are not part of it, until the next look-up finds them in it.

Worktrees volee creates

• The worktree is created detached at origin/<base>, as the last fetch left it, and the branch is created inside it, with no upstream until the agent pushes it. A failure therefore never leaves a stray branch; when the worktree exists but a later step failed (a hook, a checkout stopped at its timeout), volee says the worktree is there.
• volee refuses to reuse an existing branch or directory, and checks both before it touches the repository, with one exception (ADR 0016): what a failed launch left untouched. When the agent of an earlier launch on the same branch, in the same worktree and from the same base, failed before any session started, git still registers that worktree for the branch, the worktree has no change and no untracked file, and the branch has no commit beyond its merge base with the base branch, the same launch run again reuses the worktree and forgets the failed agent.
• Removing a worktree is never forced. volee refuses to remove the main checkout, a locked worktree, a worktree with uncommitted changes or untracked files, and a detached HEAD that no branch, tag or remote-tracking branch contains, since those commits would be lost with the worktree. Ignored files, such as build outputs, are deleted with it. The branch is always kept.

Decisions

volee records its significant design decisions as architecture decision records (ADRs), in the MADR style. An ADR is never edited after it is accepted: a later ADR supersedes it.

Not built yet

Some decisions describe more than volee does today. These parts are still to come:

• 0004: a setting for how often volee lists Claude Code sessions. 0.1.0 lists them every two to ten seconds while the interface is open (two after a listing that changed something, slowing down while nothing does), and every thirty seconds otherwise.
• 0005: CLI commands that give harnesses without MCP the operations of the MCP tools.
• 0006: configurable routing policies, and a wake action for sessions volee did not launch, which cannot receive messages yet.
• 0008: a location adapter for Zellij. tuios (0015) and tmux have one; a session running in a Zellij pane is listed, and you switch to its pane yourself.
• 0011: volee tidy --force. 0.1.0 cannot remove a worktree without delivery evidence.
• 0012: the Homebrew formula and the crates.io release.
• 0022: profiles for Codex CLI, Gemini CLI, Grok Build and the others the ADR lists. Only Claude Code and OpenCode (measured on OpenCode 2.2.5) have one; other programs run with the generic profile, as agents of the list (volee run, 0029) or in a host on its own (volee host spawn): a state read on the screen, and no resume. ACP as a source of states for hosted agents is not built either.
• 0023: finding agents in the process table for harnesses other than OpenCode (Claude Code sessions are still found through claude agents --json), and adopting them (codex resume, gemini --resume), which needs their profiles. In a tuios pane they are found through tuios (0030); in tmux or in a plain terminal they are not.
• 0030: the states a multiplexer’s hooks report for such an agent, and the panes whose harness a hook reported rather than the program in the foreground. Built on stand-in programs: Codex CLI and Gemini CLI themselves were not available where it was made.
• 0027: a door for a session in a tmux pane (the pane is brought forward instead) and for an agent of another harness started in a plain terminal (in a tuios pane, it opens like any agent in a pane; started with volee run, it runs in a host and has one, 0029). A Claude Code session in a plain terminal opens once the person moved it to the background (0034).
• 0034: pressing the left arrow for the person where the terminal application has a door for it (Ghostty 1.4 on macOS was measured to have one), and waiting from volee attach as the interface does.
• 0029: exact states for volee run -- claude, by joining the session Claude Code lists to the agent; a way to remove the records of ended hosts.
• 0028: a live preview of a Claude Code background session that is not open, which would need a client on the session; volee shows its replay, and says what it folds. Also not built: a tile or a preview that leaves out a harness’s prompt and status lines, to show more of the conversation in a small space.
• 0024: with resume_after_reboot = false, interrupted agents show as stopped and resume when you write to them, rather than offering a resume action.

To propose a new decision, copy the template, number it, and open a pull request.

0000. Record architecture decisions

• Status: Accepted
• Date: 2026-11-06

Context

volee is an open-source project meant to welcome contributors, many of whom will work with coding agents. Both humans and agents need to know why the code is shaped the way it is, without archaeology in commit history.

Decision

Every significant decision is written as an ADR in docs/src/adr/, numbered, in the MADR style, and published with the documentation site. A pull request that changes a decision updates or supersedes the matching ADR in the same pull request.

Consequences

• Reviewers can point to an ADR instead of re-arguing a choice.
• Agents working on the repository read the ADRs through AGENTS.md.
• Writing an ADR costs a few minutes; we accept that cost.

Alternatives considered

• Design notes in issues or discussions. Easy to write, hard to find and not versioned with the code.
• A single design document. Grows stale and loses the history of why a choice changed.

0001. An agent is a unit of work, not a pane or a process

• Status: Accepted
• Date: 2026-11-06

Context

volee grew out of a prototype that identified an agent by the terminal pane it ran in. A review of that prototype on 2026-11-06 found that this single choice caused most of its visible bugs:

• When a pane closed, the agent was shown as gone while its session kept running.
• When a session was attached from another pane, the same agent appeared twice.
• A stale record whose pane had disappeared took over the state of an unrelated agent in the same multiplexer session.

Meanwhile, coding harnesses moved on. Claude Code background sessions exist independently of any terminal, can be attached from anywhere, and are reaped and restarted by their supervisor. Resuming a stopped session can create a new session (a fork) that continues the same conversation.

Decision

• An agent is a unit of work with a volee identifier (AgentId, a sortable ULID rendered as ag_...). It has a role, an optional parent, an optional mission, a workspace (repository, worktree, branch, base) and a lifecycle state.
• An agent has one or more harness sessions (for Claude Code: session UUIDs). Sessions form a lineage: start, resume, fork. Exactly one session is current.
• A location (background supervisor, multiplexer pane, plain terminal) is an attribute that can change at any time and is never used as identity.
• Sessions that volee did not launch get an agent on first sight, keyed by their session id, with the role independent.

Consequences

• Closing, moving or re-attaching a terminal never changes what volee shows.
• A resumed or forked session stays the same agent in the TUI, with its history.
• Every join between sources uses session ids, never names or positions.
• volee must store the session lineage; this is one more table.

Alternatives considered

• Pane as identity (the prototype). Rejected for the reasons above.
• Harness session id as identity. Simple, but a resume that forks would create a new agent and lose its history, missions and messages.
• Process id. Changes on every restart and is reused by the OS.

0002. The harness owns agent processes

• Status: Superseded by 0019
• Date: 2026-11-06

Context

Someone has to keep agent processes alive, give them a terminal, survive the user closing windows, and let the user take over an agent. Terminal multiplexers do this; so does Claude Code itself since its background sessions (claude --bg), its supervisor daemon and claude attach.

Measured on Claude Code 2.1.319: claude --bg returns at once with a short id; claude agents --json lists every session with its state; claude attach <id> opens the session in the current terminal and Ctrl+Z returns control to the calling program with exit status 0.

Decision

volee never owns agent processes or their terminals. For Claude Code, every agent volee launches is a background session started with claude --bg inside its worktree. Taking over an agent from the TUI suspends the TUI, runs claude attach <id> in the same terminal, and resumes the TUI on the same row when the user leaves with Ctrl+Z.

Consequences

• Agents survive the TUI, the daemon and every terminal window being closed.
• volee needs no PTY code, no scrollback, no resize handling for agents.
• volee depends on the harness’s supervisor features. They are new and labelled research preview, so volee checks the harness version at startup and degrades to read-only discovery when a feature is missing.
• Agents running in a multiplexer pane (started by hand) are still visible; taking them over goes through a location adapter (ADR 0008).

Alternatives considered

• Own the processes in PTYs (like ccmanager). Re-implements what the harness and multiplexers already do, and dies with the TUI.
• Require a multiplexer (like the prototype on tuios, or tools built on tmux). Ties volee to one terminal stack and brings back pane identity.

0003. A daemon with an event log is the single source of truth

• Status: Accepted
• Date: 2026-11-06

Context

The prototype had four different ways to join its state file with live data, and its CLI and its TUI could disagree about the same agent. Several clients need the same view of the world: the TUI, the CLI, the MCP server used by agents, and the hook command called by agents dozens of times per turn.

Decision

• One daemon (volee daemon) owns all state. It is started on demand by any client and listens on a Unix socket with user-only permissions.
• The protocol is JSON-RPC 2.0, one JSON object per line. Clients can subscribe to state changes; nobody polls the daemon.
• State lives in SQLite (WAL mode). Facts arrive as events in an append-only table; the current state (agents, sessions, messages, missions) is a projection of those events, updated in the same transaction.
• volee hook must never slow an agent down: it sends its event with a short timeout and falls back to appending to a spool file when the daemon is unreachable. The daemon ingests the spool at start.

Consequences

• One join rule, one place to test it, one answer everywhere.
• The event log gives the timeline view and debugging for free.
• The daemon becomes a component to supervise. It is small, restarts on demand, and loses nothing thanks to the spool.

Alternatives considered

• A shared state file with file locks (the prototype). Every reader joins it with live data on its own, which is how the four joins appeared.
• A server per client. Duplicates reconciliation and work.
• jsonrpsee or tarpc for IPC. Heavier than needed, or Rust-only. Line delimited JSON-RPC is trivial to speak from any language and from nc.

0004. Hooks, harness listing, git and forge are reconciled into one model

• Status: Accepted
• Date: 2026-11-06

Context

No single source knows everything:

• Hooks give rich, immediate events, but only for sessions started with volee’s settings.
• claude agents --json --all lists every Claude Code session on the machine with a coarse state, and is documented as the supported way to read it.
• Git knows worktrees, branches, commits and push state.
• The forge knows pull requests and checks.

Claude Code also keeps internal files (~/.claude/jobs, ~/.claude/sessions, transcripts) whose format is explicitly not a stable interface.

Decision

• Each source is authoritative for one kind of fact (see the architecture overview). Conflicts are resolved by that rule, not by recency.
• Hooks are injected per agent with claude --settings <file>. volee never edits the user’s ~/.claude/settings.json; hooks passed this way are added to the user’s own hooks.
• claude agents --json --all is polled (every few seconds while a client is connected, slower otherwise) and reconciled by session id.
• volee does not parse Claude Code internal files. Transcript paths received in hook payloads may be shown, never parsed for state.
• Git and forge queries are triggered by events (an edit, a commit, a push seen in a hook) and by a slow timer.

Consequences

• Agents volee did not launch are visible with a coarse state; agents it launched get the fine-grained one.
• volee keeps working when Claude Code changes its internal files.
• Polling claude agents costs a process start every few seconds while the TUI is open; this is acceptable and configurable.

Alternatives considered

• Parse ~/.claude/sessions/*.json and transcripts. Cheaper and richer, but undocumented and unstable.
• Global hooks in the user’s settings. Would see every session in detail, but edits a file the user owns and affects every session they start.

0005. Agents talk to volee through MCP and the CLI

• Status: Accepted
• Date: 2026-11-06

Context

Agents need to find each other, send messages, report progress and, for coordinators, spawn workers. The prototype gave its agents multiplexer commands in their prompts (more than fifty calls across two prompts), which tied every agent to that multiplexer.

Users run more than one AI. An agent of one harness should be able to message an agent of another one on the same machine.

Decision

• volee exposes an MCP server over stdio (volee mcp). Every agent volee launches gets it through --mcp-config and --strict-mcp-config, so a project .mcp.json approval can never stall a background session.
• The tools are harness-neutral: whoami, list_agents, send_message, read_messages, report, and for coordinators spawn_worker and close_mission.
• The same operations exist as CLI commands for scripts and for harnesses without MCP.
• Prompts given to agents never mention a multiplexer.

Consequences

• Any MCP-capable harness can join the conversation; only process launching and state detection need a per-harness adapter.
• The MCP surface is a public API: it is versioned and documented.

Alternatives considered

• Multiplexer commands in prompts. Couples agents to one terminal stack.
• Claude Code cross-session messaging. Claude-only, and its wire format is not published.

0006. Typed, threaded messages delivered through documented hooks

• Status: Accepted (amended by 0031: a question to the person may offer its answers)
• Date: 2026-11-06

Context

Understanding how agents interact is a core goal. Messages must be readable by humans (who asked what, who answered, what was agreed) and must reach agents reliably whether they are working, idle or stopped.

Claude Code 2.1.319 has no supported way to type a prompt into a running background session. Probes on 2026-11-06 established what works:

Decision

• A message has a sender (human, agent or system), recipients, a kind (question, answer, contract, report, alert, note), a markdown body, references (file and line, commit, pull request, URL), a thread, and per-recipient delivery and read timestamps.
• Threads: one per mission, one per pair of agents outside missions, and the human inbox. Questions to the human stay pinned until answered.
• Routing: inside a mission every member can write to every member; outside a mission an agent can write to its parent, its coordinator and the human. The human can write to anyone. Policies are configurable.
• Delivery to a Claude Code agent launched by volee:
  1. working: queued, delivered by the Stop block at the end of the turn;
  2. idle: delivered by the asyncRewake waiter armed at every Stop;
  3. stopped or reaped: delivered by --bg --resume, and the new session is linked to the same agent (ADR 0001). The resume starts from the repository’s main checkout with --worktree (ADR 0013), carries the pending messages as its prompt and the agent’s instructions again, and the daemon links the new session by the handle the harness printed, before any listing could take it for a stranger. Two holds prevent a resume: the human stopped the agent (lifted by the human’s next message to it, never by an agent’s), or its mission is over (never lifted). An aborted mission’s notice goes only to its live agents.
• Agents that volee did not launch can be messaged only through an explicit “wake” action by the human, because it forks their session.
• Thread summaries by an LLM are opt-in and show their cost.

Consequences

• Messages are never typed into a terminal, so pasting multi-line text is safe and no agent is interrupted mid-tool.
• A message to a working agent waits for its turn to end; urgent messages can be flagged in the TUI, which may offer a wake action.
• Only one asyncRewake waiter per agent may be active; the daemon retires older ones.

Alternatives considered

• Typing into panes (the prototype). Interrupts agents, breaks on paste, needs a multiplexer.
• Claude Code cross-session inbox socket. Promising, but the message format is undocumented; kept as a possible future adapter.
• Channels (research preview). Requires flags and a plugin allowlist not available to every user.

0007. Missions are run by a supervisor program and a coordinator agent

• Status: Accepted (amended by 0032: the coordinator presents its report and merges only after the person approved; it no longer closes on its own word, and closing tidies the mission; and by 0033: a lead starts missions, whose coordinator answers to it)
• Date: 2026-11-06

Context

In the prototype, a mission was led by an LLM agent that waited on its workers in a loop, with broad permissions. If it died or ran out of context, the mission stayed “active” forever. “Done” meant “finished a turn”, not “delivered”.

Decision

A mission has a goal, one or more repositories, a kind (change delivers branches and pull requests; analysis delivers reports) and two halves:

• The supervisor, a program inside the daemon. It launches the coordinator, tracks workers, waits for them without tokens, verifies delivery evidence (ADR 0011) when a worker stops, retries or escalates, and closes the mission only when every worker has delivered or been abandoned by the human.
• The coordinator agent, an LLM session with the MCP tools spawn_worker, send_message, report and close_mission. It splits the goal, writes worker tasks, answers their questions or escalates them to the human, and writes the final report. It is woken by messages from the supervisor and its workers; it never polls.

A mission can be aborted at any time; aborting never deletes work.

Consequences

• Waiting costs nothing; the LLM is used for judgement only.
• Delivery is checked by code, so “done” means pushed, reviewed or reported.
• The coordinator needs no multiplexer or administrator rights.

Alternatives considered

• LLM-only coordinator (the prototype). Fragile, expensive while waiting, and unverifiable.
• Program-only coordinator. Cannot split a fuzzy goal or answer a worker’s design question.

0008. Multiplexers are optional location adapters

• Status: Accepted
• Date: 2026-11-06

Context

Developers use tmux, Zellij, herdr, tuios, WezTerm or Ghostty tabs. Some agents are started by hand inside a pane; volee must show them and let the user jump to them. But volee itself must not require any multiplexer.

Decision

• A location adapter answers two questions for agents that live in a pane: “where is this session?” (by process id or session id) and “focus it”. Optionally it can capture the pane for a preview.
• Adapters are optional and detected at runtime. The first ones are tmux and tuios; Zellij follows.
• Without an adapter, a pane-hosted agent is still listed with its state; taking it over is offered only when its harness supports attaching from another terminal.

Consequences

• volee works in a plain terminal; multiplexer users get one more shortcut.
• Adapters stay small (a handful of commands each) and easy to contribute.

Alternatives considered

• Build on one multiplexer. Rejected: excludes most users and brings back pane identity.

0009. The TUI follows the Elm architecture with one keymap table

• Status: Accepted
• Date: 2026-11-06

Context

The prototype’s interface was a single class of more than 2,500 lines whose drawing code also changed state, and whose keys were described in three hand-written lists (dispatch, help, key bar) that had already drifted apart. Opening an agent created windows in five different places.

Decision

• Elm architecture. A Model, a Msg enum, a pure update(model, msg) -> effects and a pure view(model, frame). Drawing never mutates the model; hit areas for the mouse are computed by the layout and stored in the model by update.
• One keymap table. Every binding is declared once with its context, its action and its description. Dispatch, the help screen and the key hint bar are generated from it. Users override bindings in config.toml.
• One screen. Previews, diffs and messages open inside volee. The only ways out are explicit: taking over an agent (suspend and attach) and opening an external tool the user configured. Both return to the same row.
• Semantic themes. Widgets ask for roles (state.working, edge.pulse, diff.added), never for colors. Themes map roles to colors, with built-in Catppuccin flavors and a theme that uses the terminal’s own ANSI palette.
• Semantic zoom. Each graph view has three levels of detail (cards, compact, dots) chosen by size and changeable by the user.
• Render only when needed. Animation ticks run only while something moves; otherwise the TUI redraws on input and on daemon events.

Consequences

• Key handling and layout are unit-tested without a terminal; rendering is snapshot-tested with ratatui’s test backend.
• Adding a binding is a one-line change that also updates the help.

Alternatives considered

• Component objects with their own state (the prototype). Hard to test, and state leaks into drawing.

0010. Git is read through the git CLI behind a trait

• Status: Accepted
• Date: 2026-11-06

Context

volee needs worktrees, branches, upstream tracking, ahead and behind counts, dirty state, diff statistics against a merge base, commit lists and full diffs, for many repositories. gix (gitoxide) reads most of this natively and fast, but some porcelain operations and worktree writes are incomplete, and behaviour must match what users see in their own git.

Decision

• All git access goes through a Git trait in volee-git.
• The first implementation shells out to the git CLI with porcelain formats, a timeout and a concurrency limit.
• Results are cached per worktree and invalidated by events, so git runs at most once a minute per worktree unless something changed.
• Tests use real temporary repositories.

Consequences

• Identical results to the user’s git, including their configuration.
• A gix implementation can replace hot paths later without touching callers.

Alternatives considered

• gix everywhere now. Faster, but more code and edge cases for little gain at volee’s polling rate.
• libgit2 (git2). C dependency, lags behind git features.

0011. Destructive actions require delivery evidence

• Status: Accepted (amended by 0032: the evidence says when a repository has no remote, where committed work is ready and a merge into the base branch is what lands it; closing a mission tidies its workers under the same rule)
• Date: 2026-11-06

Context

The prototype’s cleanup removed a worktree as soon as its multiplexer session had disappeared, which happens when the last window closes or while the multiplexer restarts. It could also kill a whole shared session because one agent in it had been adopted.

Decision

• Delivery evidence is computed by code from git and the forge: commits since the agent started, branch pushed (tip present on the remote), pull request opened, merged or closed, checks state; for analysis work, a report message.
• volee tidy removes a worktree only when its work is delivered (merged into the base, or pull request merged, or report delivered) and the tree is clean. Otherwise it explains what is missing. --force is explicit and never the default.
• volee never deletes a branch.
• volee stops only sessions it launched, never a pane or a session it merely observes.
• An agent that disappears is marked lost with the evidence of its disappearance, never “done”.

Consequences

• Cleanup is slower to reach “all tidy”, and always safe to run.
• Users see exactly why something is kept.

Alternatives considered

• Trust absence as completion (the prototype). Lost work during restarts.

0012. Rust, dual MIT/Apache-2.0, Unix first

• Status: Accepted
• Date: 2026-11-06

Context

volee is a long-running daemon plus an interactive terminal UI, distributed to developers who expect a single binary installed in seconds. The prototype was written in TypeScript on Bun and required the Bun runtime.

Decision

• Rust, edition 2024, with ratatui for the interface, tokio for IO, rusqlite (bundled SQLite) for storage and rmcp for the MCP server. The MSRV is declared in Cargo.toml and tested in CI.
• License: MIT OR Apache-2.0, the usual dual license of the Rust ecosystem.
• Platforms: macOS and Linux. Windows is out of scope for now (Unix sockets, harness support); contributions welcome later.
• Language: English for code, documentation and interface.

Consequences

• One static binary per platform, prebuilt by CI, installable with Homebrew, a shell installer or Cargo.
• Contributors need a Rust toolchain; rust-toolchain.toml pins it.

Alternatives considered

• Go with Bubble Tea. Faster to write, an excellent TUI ecosystem (lazygit, k9s). Rust won on control, memory use for the daemon, and the ratatui ecosystem around tools volee’s users already run (gitui, yazi, zellij).
• Keep TypeScript. Requires a JavaScript runtime on every machine.

0013. Agent worktrees live in their repository

• Status: Accepted
• Date: 2026-11-07

Context

volee gives every worker its own git worktree, on its own branch, so that agents never edit the same files. The first design put worktrees under volee’s data directory (~/.local/share/volee/worktrees/<repo>/<branch>) and started each agent there with claude --bg.

Claude Code refuses to start a background session in a directory the user has not trusted. We measured it with Claude Code 2.1.319, with the clean environment the daemon uses:

• Trust is recorded per path. A repository nested in a trusted folder does not inherit its trust (since 2.1.232).
• claude --bg in an untrusted directory prints Workspace not trusted. Run claude in <dir> once and accept the trust prompt, then retry. and starts nothing. A worktree created with git worktree add is untrusted wherever it lives, even under a trusted repository’s .claude/worktrees/.
• From a trusted repository’s main checkout, claude --bg --worktree=<name> works. When .claude/worktrees/<name> already exists, Claude Code reuses it, on whatever branch it has checked out, and runs the session there.
• Claude Code locks the worktrees it runs in. claude rm deletes a worktree it created itself, but keeps a pre-existing one whose commits it cannot see on a remote (kept <id>).

Making volee’s own worktrees trusted would mean editing Claude Code’s configuration file, which volee never does (see the agent rules).

Decision

• volee creates each worktree itself, with git, at <repository>/.claude/worktrees/<branch with / replaced by ->, on the agent’s branch from the chosen base (ADR 0010). It adds .claude/worktrees/ to the repository’s local exclude file, as Claude Code does.
• The session starts from the repository’s main checkout with --worktree=<name>, so Claude Code checks trust where the user gave it and reuses volee’s worktree.
• The location is not configurable. A repository volee launches agents in must be trusted once by the user (run claude there and accept). volee reports an untrusted repository with that instruction and starts nothing.
• Cleaning a worktree up stays volee’s job, with delivery evidence (ADR 0011): it unlocks the worktree only after the evidence allows it.

Consequences

• Launching works for every repository the user already uses Claude Code in, which is the usual case, with no change to the user’s configuration.
• Worktrees sit next to Claude Code’s own, so tools that know Claude Code’s layout (and claude rm) see them where they expect them.
• People who wanted worktrees on another disk cannot have them, as long as Claude Code’s trust model stays per path.

Alternatives considered

• Worktrees under volee’s data directory. Simple and tidy, but every launch fails on trust.
• Writing trust entries into Claude Code’s configuration. Works, but edits a file volee does not own and bypasses a security prompt the user should answer.
• Letting Claude Code create the worktree (--worktree with a fresh name). Trusted, but the branch is named worktree-<name> and starts from HEAD, so volee would lose control of the branch name and its base.
• Starting the agent in the main checkout and telling it to work in the worktree. Fragile: tools and hooks would see the main checkout as the project, and one wrong path would edit the user’s own checkout.

0014. Agents of other harnesses join through MCP

• Status: Accepted
• Date: 2026-11-07

Context

volee discovers Claude Code sessions only (ADR 0004). An agent of another harness, such as Codex CLI or Gemini CLI, can run volee mcp, which ADR 0005 made the harness-neutral way in, but the server needs an agent identity, and only agents volee launched or discovered have one. So an agent of another AI cannot take part in conversations yet. The product owner wants an agent of AI A to talk to an agent of AI B, and chose “free inside a mission” for routing: ADR 0006 already lets members of a mission write to each other, and it stays as it is.

Such an agent gives volee nothing but its MCP server: no hooks, no session listing, no process volee owns.

Decision

• Identity. volee mcp --join <name> [--harness <kind>] [--mission <mission>] calls agents.join with the name, the harness, the directory the server runs in, and the mission. The daemon looks for an agent that joined with the same name, harness and directory, and was not forgotten. It finds that agent again, or it registers a new one: launched_by: outside, harness Other(<kind>), role independent, workspace at that directory, enriched from git like any workspace. The name is what people and agents type, the directory tells two projects apart, and the harness tells two AIs in one project apart. An agent of another harness that volee did not launch is a joined one (Agent::joined), since volee discovers the sessions of no other harness yet.
• State. A joined agent is alive while a connection that joined for it stays open: the connection of its MCP server, which lives as long as its harness. It is idle when it joins. Each of its tool calls is recorded as its activity (agents.activity, sent by its server). When the last such connection closes, it is stopped. When the daemon starts, no connection is open yet, so joined agents still recorded as alive are stopped until their server joins again. volee never resumes a joined agent: it did not launch it.
• Routing. ADR 0006 unchanged. Outside a mission, a joined agent writes to the person, and the person to it. With --mission, it joins an open mission as a member: members of the mission and the agent write to each other, which is the AI A to AI B case. A new event, membership-changed, records the mission a joined agent takes part in when it joins again with another mission, or with none; only joined agents change missions. The supervisor judges workers only, so a member that joined is never judged, and the mission’s coordinator hears that it joined.
• Messages. Nothing hands a joined agent its messages: there are no hooks to deliver them at the end of a turn or to wake it. They wait in its threads until it calls read_messages, which marks them read. Its MCP server’s instructions tell the model so, and volee msg send says it. When the agent is gone, its messages wait for its next join.

Consequences

• Any harness that can start an MCP server over stdio takes part, with one line of its configuration and no adapter in volee.
• A joined agent’s state is coarse: idle while connected, stopped once its server is gone. volee cannot tell when it works, and the interface shows it that way.
• A message reaches a joined agent only when its model calls read_messages. The instructions ask it to do so at the start of a task, after a question, and before it finishes; a model that forgets leaves messages unread.
• Two servers of the same identity (the same CLI open twice in one project) are one agent, alive until both close.
• If volee later discovers sessions of another harness, Agent::joined will need an explicit marker to tell those from the agents that joined.

Alternatives considered

• A token or a file to keep the identity. Robust across renames, but one more thing to configure and to lose. Name, harness and directory are what the person already writes in the harness’s configuration.
• Identity including the mission. No new event, but joining a new mission would create a second agent with the same name, and commands that take a name would become ambiguous.
• Liveness from tool calls with a timeout. Works without a connection, but an idle agent that thinks for a while would flicker to stopped. The server’s connection is exact and costs nothing.
• Free routing between any agents. Simpler for the AI A to AI B case, but ADR 0006 keeps conversations inside missions on purpose; joining a mission gives the same reach where it is wanted.

0015. tuios is the first location adapter

• Status: Accepted
• Date: 2026-11-07

Context

ADR 0008 plans location adapters: for an agent that lives in a multiplexer pane, find the pane, focus it, and optionally capture it for a preview. volee 0.1 has none. A Claude Code session started by hand (an interactive session) is listed, but its preview and its take over are refused: “switch to that terminal”. Most interactive sessions of the product owner run in tuios panes.

Measured on 2026-11-07 with tuios 0.12.1 and Claude Code 2.1.319, from a throwaway tuios session:

• claude agents --json --all gives every live session its process id. Interactive sessions have no handle, so claude logs and claude attach cannot reach them.
• tuios call list-agents '{"all_sessions":true}' lists the agent panes of every session in one call of about 11 ms. Each one carries its session, its window id, its harness and agent_session_id. tuios’s own Claude Code hooks (tuios integration install claude-code) fill that id with the exact Claude Code session id.
• Without those hooks, tuios call resolve-pane '{"pids":[...]}' names the pane whose process is the nearest ancestor of a process, in about 11 ms. For a process outside every pane, it answers window_not_found. One ps -axo pid=,ppid= (about 17 ms) gives the ancestors.
• Working directories do not tell panes apart: the person’s own pane and the probe both ran in ~/Developer.
• A background session that a pane shows through claude agents is not in that pane’s process tree. It stays a background session, which claude attach takes over.
• tuios call capture-pane with styled returns the pane’s rows with their colors.
• tuios focus-window -s S W focuses a pane and shows its workspace. tuios switch-session S, run from a pane, switches the client that shows that pane’s session; from outside every pane it switches the only attached client, and needs a client to be named when there are several.

Decision

• Where. A Multiplexer trait in a new crate, volee-mux, answers four questions: which panes some sessions run in, what a pane shows, how to bring it forward, and whether the multiplexer can be used now. Tuios is the first implementation. tmux and Zellij can follow behind the same trait. It starts programs through volee-harness’s CommandRunner, which gives timeouts and a fake for tests.

• Optional. volee daemon run uses tuios only when tuios is on the PATH. Each call needs a running tuios server. Without one, a round changes nothing and the next round asks again. There is nothing to configure, and volee daemon status says what it found.

• Matching. After each discovery round, for live interactive sessions only:

  1. tuios’s own record: the agent pane whose harness is claude-code and whose agent_session_id is the session’s id;
  2. otherwise, the session’s process: its pid and its ancestors, given to resolve-pane, which says whether a pane runs it;
  3. never the working directory.

  A match is recorded as Location::Pane { multiplexer: "tuios", target: "<session>:<window id>" }, with a LocationChanged event. A session that is no longer in a pane goes back to Terminal. A failed round changes nothing. Every adapter writes its addresses as <session>:<pane>, so the interface can name the session.

• Preview. agents.preview of an agent in a pane captures the pane, and returns its rows placed with cursor moves. The interface draws them as it draws claude logs.

• Take over. agents.attach answers with focus: the commands that bring the pane forward (tuios focus-window -s S W, then tuios switch-session S). The client runs them in its own environment, without giving up its terminal. When volee runs in a tuios pane, tuios then switches the person’s own client, even when several are attached.

• Read and focus only. volee reads (list-agents, resolve-pane, capture-pane) and focuses (focus-window, switch-session). It never types into a pane, never creates, closes or moves one, and never installs tuios’s hooks.

Consequences

• An interactive session in a tuios pane can be watched from volee and reached in one key; nothing changes without tuios.
• A round costs one tuios call when tuios’s hooks report session ids. Each interactive session they leave unmatched adds one ps and one call, and a session found outside every pane is not asked about again.
• The client runs commands the daemon sends, as it already does for claude attach.
• A pane found once is followed one round late: a focus in between fails and says why. A session run in tmux inside a tuios pane is not matched: its terminal is tmux’s, and that is a tmux adapter’s job.

Alternatives considered

• The interface finds and focuses panes itself. Each client would need the adapters and the process table, and two clients could disagree. The daemon matches once and records the location for every client.
• The daemon focuses the pane. It runs outside every pane, so tuios would switch “the only attached client”: the wrong one, or none, as soon as two are attached.
• Matching on the working directory or the pane title. Ambiguous, as measured.
• A switch in the configuration. ADR 0008 keeps adapters optional and detected; detection costs one PATH lookup.

0016. Reuse or tidy what a failed launch left untouched

• Status: Accepted
• Date: 2026-11-07
• Refines: 0011

Context

volee spawn creates the agent’s worktree and its new branch, then starts the session. The most common first-run failure comes after that: Claude Code refuses a background session in a repository it does not trust yet. Both the worktree and the branch stay, because volee deletes nothing without evidence and never deletes a branch (ADR 0011). The person trusts the repository and runs the same command again, which is refused: the branch exists. They had to remove the worktree and the branch with git first.

What such a failure leaves holds no work: the agent never ran, so nothing was written in the worktree and nothing was committed on the branch. That is evidence too, and it can be checked.

Decision

• A launch on a branch that exists reuses what a failed launch left, only when all of these hold:

  • an agent volee launched on that branch, in the worktree this launch would use (<repository>/.claude/worktrees/<branch>), from the same base, failed without ever having a session;
  • git registers that worktree for that branch, unlocked;
  • the worktree is clean: no change and no untracked file;
  • the branch holds no commit of its own: none beyond its merge base with the base branch.

  The failed agent is then forgotten, and the launch goes on as usual in that worktree, from the branch’s tip. In every other case the existing refusal stands: the branch or the directory exists.

• The check runs again, under the state lock, right before the failed agent is forgotten, so two launches cannot claim the same worktree.

• volee tidy accepts the same evidence for removing such a worktree: an agent whose launch failed before any session started, with fresh delivery evidence showing a clean tree and no commit of its own. git still refuses any change or untracked file when it removes the worktree. The branch is kept.

• The message of a failed launch says that the same command can simply run again once the cause is fixed.

ADR 0011 stands otherwise: volee never deletes a branch, and removes or reuses nothing that could hold work.

Consequences

• Trusting the repository and running the same volee spawn again works, without a git step. So does a retry after any other launch failure that happened before the session started.
• A worktree in which anything happened (a file written, a commit, a session started) is never reused or tidied by this rule.
• A failed agent that the person forgot (volee forget) leaves nothing that proves where the worktree came from: the branch is refused, as before. A Claude Code worktree of the same name is never taken for volee’s leftover.
• The reused branch starts where the failed launch started it. If the base moved since, the new agent starts from the older commit; it can rebase.

Alternatives considered

• Roll back a failed launch, branch included. Leaves nothing behind, but needs an exception to “volee never deletes a branch”, and a rollback that fails halfway leaves the same state anyway.
• Accept any existing branch that holds no commit of its own. Simpler, but a branch someone created by hand, or a worktree Claude Code made, would be taken over. Requiring the failed agent ties the reuse to volee’s own leftover.
• Ask the person to run volee tidy first. Safe, but it is one more step for the most common first-run failure, and the person would still have to know about it.

0017. Setup commands prepare a new worktree before its agent starts

• Status: Accepted
• Date: 2026-11-07

Context

volee launches an agent in a new git worktree (ADR 0013). A worktree holds the tracked files only: no node_modules, no virtual environment, none of the ignored files a project needs to run, such as .env.local. An agent that starts there spends its first minutes, and tokens, installing dependencies; in Claude Code’s manual permission mode it waits for the person to allow each install command; and some projects cannot run their tests at all without a file that git ignores.

tuios-cockpit, the prototype volee replaces, had an install command per repository for this. People moving to volee asked for the same thing, and the configuration written from the cockpit’s registry had to leave those commands out.

Decision

• Where. setup in a repository’s table: a list of commands, such as ["cp \"$VOLEE_REPO_ROOT/.env.local\" .", "bun install"]. They come from the person’s own configuration file, which agents do not write.
• When. For every agent volee launches in a new worktree, including a worktree that a failed launch left untouched and that a new launch reuses (ADR 0016): after the worktree exists and the agent is registered, before its session starts. The coordinator of a mission, which works in a main checkout, has none.
• How. The daemon runs them in order, each with /bin/sh -c, in the worktree, in a process group of its own, with standard input closed. Each gets the daemon’s environment plus VOLEE_REPO (the repository’s name), VOLEE_REPO_ROOT (its main checkout), VOLEE_WORKTREE, VOLEE_BRANCH and VOLEE_BASE. Each may run for 15 minutes; then it is killed with its whole process group.
• What people see. The agent is listed as launching, its detail naming the command that runs (setting up: bun install). What the commands print goes to setup.log in the agent’s state directory as they print it, so it can be followed while they run; volee spawn names that file.
• Failure. The first command that exits with a failure status, or runs out of time, stops the setup; so does a log that cannot be written. The launch then fails as a failed session start does: the agent is marked failed with the command and the last line it printed, no session starts, the worktree and branch stay (ADR 0011), and the same command can run again once the problem is fixed: it reuses the worktree while git sees it clean, and runs the setup again.
• Interruption. Before each command and before the session starts, the launch checks under the state lock that the agent is still launching. If its mission ended meanwhile, the launch stops there: the agent is marked stopped, no session starts, and the worktree and branch stay.

Consequences

• An agent starts in a worktree that runs, with no install step of its own and no permission prompt for it.
• A launch takes as long as its setup. volee spawn, the launch dialog and an agent that asks volee for a worker over MCP wait for it; volee spawn says so before it waits.
• Setup commands should be safe to run twice: a launch that reuses a worktree runs them again. A setup that changes tracked files, or leaves files git does not ignore, makes the worktree no longer untouched, so it is not reused: the person removes it before launching again. Commands that write only ignored files (dependencies, a .env.local listed in .gitignore) keep it reusable.

Alternatives considered

• Tell the agent to run the setup first. It costs tokens on every launch, waits for permissions in manual mode, and depends on the agent doing it before anything else.
• A git post-checkout hook. It runs for every checkout in the repository, the person’s own included, and volee would have to install it in their repository.
• Start the session at once and set up beside it. The agent would work in a worktree that is still being prepared, and see half-installed dependencies.

0018. A pane that shows a background session is its preview

• Status: Superseded by 0023
• Date: 2026-11-08

Context

The preview of a Claude Code background session comes from claude logs, which replays only the session’s recent output. What was drawn before the replay starts and never redrawn since, such as the frame of the prompt and the status line, is missing: on a session that has run for hours, the preview shows the conversation with gaps and no status line.

People often keep such a session open in a pane: claude agents shows the session they pick, and claude attach <id> shows one session. That pane holds the session’s whole screen. The session runs in Claude Code’s background supervisor, not in the pane, so the location adapters of ADR 0015, which walk from a session’s process up to a pane, never find it, and the daemon did not even ask them about background sessions.

The only link between such a pane and its session is the pane’s title: Claude Code titles its terminal with the name of the session it shows, after a status mark (◑ fix the parser). tuios 0.12.1 reports that title for each agent pane it knows, and no session id (measured on this machine: agent_session_id is empty for a pane that runs claude agents).

Decision

After each discovery round, the daemon asks each multiplexer which panes show the live background sessions, given by name. A pane shows a session when its title, without the status mark, is the session’s name, and only names that no other live session shares are asked about. The answer, a mirror, is kept in memory until the next round.

A mirror is not a location: the agent stays where it runs (background), and no event is recorded, so moving around in claude agents changes nothing in the registry or the timeline. The preview, and so the full-screen view, reads the mirror’s pane when there is one, and falls back to claude logs when there is none or the pane does not answer.

tuios finds mirrors from list-agents; the other multiplexers find none for now.

Consequences

• A background session open in a tuios pane previews exactly as that pane shows it, status line and prompt included, and follows the pane: the mirror appears or goes within a discovery round (2 to 10 seconds while the interface is open).
• The match is by name. Two live sessions with one name are never mirrored, but a pane titled with a session’s name that shows something else (another program setting the same title) would be read as its mirror. Claude Code’s names are several words long, which makes this unlikely.
• Take over (a) still runs claude attach in the interface’s terminal, even when a pane already shows the session.

Alternatives considered

• Make the pane the agent’s location. It would also send take over to the pane, but every visit to another session in claude agents would record two LocationChanged events, and the session does not run in the pane: stopping the pane’s program does not stop it.
• Match by process. The pane’s program (claude agents, or claude attach with an id) does not say which session claude agents shows, and claude attach clients are not the only way to show one.
• Keep the replay and accumulate it. Reading claude logs repeatedly and stitching the replays together still misses what was drawn before volee first read it.

0019. A volee-host process holds each agent’s terminal

• Status: Accepted (supersedes 0002)
• Date: 2026-11-08

Context

ADR 0002 left agent processes and their terminals to the harness: every Claude Code agent volee launches is a background session (claude --bg), watched through claude logs and taken over through claude attach. Two days of use showed its limits:

• claude logs replays only recent output. What was drawn before the replay and never redrawn (the prompt frame, the status line) is missing, so a long session previews with holes. Version 0.7.0 patched this with mirrors (ADR 0018), which tie volee to a multiplexer and do nothing for a session no pane shows. The product owner rejected them.
• claude attach imposes the size of the last client on every client, and the size sticks after it leaves (measured on 2.1.319). A preview cannot read the screen without changing it.
• Only Claude Code has a supervisor. Codex CLI, Gemini CLI and the others run in a terminal and nowhere else, so volee could not host them at all.
• Known Claude Code bugs hit background sessions and multiplexers: background sessions never get SIGWINCH (claude-code issue 86775), and redraws corrupt under tmux (52309) and tmux with Ghostty (77689).

Tools that keep a terminal alive for a program fall in two families. dtach and abduco pass bytes and keep no screen, so a new client sees nothing until the program redraws. shpool (one client, vt100) and zmx (one daemon per session, libghostty-vt, restores the screen on reattach) keep the screen in the process that holds the terminal. Mitchell Hashimoto’s server-side multiplexer work on libghostty takes the same path and calls tmux, Zellij and screen too slow for this job.

Decision

One host per agent. For each agent volee launches or adopts, volee starts a small process, volee host run, from its own binary. The host:

• starts the agent’s command line in a new pseudo-terminal (portable-pty), in the agent’s directory, with the agent’s environment;
• feeds everything the program writes into a terminal emulator (ADR 0020), so it always knows the exact screen;
• detaches from the terminal that started it (its own session, no controlling terminal), so it survives that terminal, the interface and the daemon;
• serves a Unix socket, and keeps a small record of itself next to it.

Claude Code runs interactive inside its host. volee no longer starts agents with claude --bg, and does not need them to appear in claude agents. Hooks still come from --settings (ADR 0004), and worktrees are still created as ADR 0013 says.

Files. Hosts live in <state>/hosts/ (mode 0700, created by volee): <agent id>.sock and <agent id>.json. The record holds the host’s process id, the program’s process id, the command line, the directory, the harness profile (ADR 0022), the start time and, once the program ends, its exit status. It is written atomically and survives a reboot (ADR 0024).

Protocol. Frames of a 4-byte length, a 1-byte kind and a payload. Control messages are JSON; screen bytes are raw. The first frame from each side carries a protocol version: a host can outlive an upgrade of volee, so a newer volee must keep speaking the versions of the hosts still running.

Clients. A client says what it wants when it connects:

• a watcher receives a snapshot of the screen, then the stream of output. It never writes and never changes the size. Previews, the full-screen view, the wall of screens and the daemon are watchers.
• the input owner also sends keys and its terminal size. There is one at a time. Its size is the terminal’s size; when it leaves, the size stays. A new input owner takes the input from the previous one, which is told why and returns to its caller.

Snapshot. On connection the host renders its screen as VT sequences (text, colors, cursor, modes, keyboard protocol, scrolling region, tab stops) and sends it before any further output. The host reads the program’s output in chunks cut between complete sequences and characters, so a snapshot never falls in the middle of one. While the program holds synchronized output (DEC mode 2026), snapshots wait for the end of the update, one second at most.

Terminal queries. Programs ask their terminal questions (device attributes, cursor position, colors, version, keyboard protocol, size). While an input owner is connected, its own terminal sees the questions and answers them. While none is, the host answers them from its emulator. A snapshot contains state, not the stream, so replaying it never asks a question again.

Slow watchers. Each client has a bounded queue. A watcher that falls behind stops receiving output and gets a fresh snapshot once it catches up; the program is never slowed down by a watcher.

End. When the program ends, the host records its exit status, tells its clients, keeps the last screen for ten minutes so that the daemon and the interface can show it, then removes its socket. volee stop asks the host to end the program like a closed terminal would (SIGHUP to its process group), then SIGKILL after a grace period.

Daemon. The daemon finds hosts by listing <state>/hosts/, connects to each as a watcher, and learns activity, title, bell and exit from it. A host whose socket refuses connections and whose program is gone is stale: the daemon records how it ended and removes its socket.

Consequences

• Every agent volee runs, of any harness, has an exact screen that any number of watchers read without changing it.
• volee now owns PTY code: sizes, signals, process groups, terminal queries. The host is small and has one job, and its rules are tested without a terminal.
• An agent survives the interface and the daemon, but not its host. A crashed host ends its agent; ADR 0024 resumes it.
• Claude Code’s own supervisor (reaping, claude attach) no longer applies to volee’s agents. Claude Code’s background-session bugs no longer apply either.
• The protocol is a compatibility surface between versions of volee.
• Each host costs a process and its emulator’s memory (measured by the prototype, see the pull request).

Alternatives considered

• Keep claude --bg and improve the replay. The replay cannot show what was drawn before it started, claude attach cannot watch without resizing, and other harnesses have no supervisor.
• Run agents in tmux (or another multiplexer). Brings back pane identity (ADR 0001) and the redraw bugs, and requires a multiplexer (ADR 0008).
• One server for every agent. One crash would end every agent, and an upgrade would have to restart them all. A host per agent fails alone.
• The daemon holds the terminals. Restarting or upgrading the daemon would end every agent.
• dtach or abduco. No screen state: a new client sees nothing until the program redraws.

0020. libghostty-vt emulates every terminal volee reads

• Status: Accepted
• Date: 2026-11-08

Context

volee reads screens in three places: the host keeps each agent’s screen (ADR 0019), watchers draw that screen into the interface, and some sources of agents volee does not host still arrive as a byte stream (claude logs, a pane capture). Until 0.7.0 the interface used the vt100 crate for the last case.

What the host needs from an emulator goes beyond drawing cells:

• render its state back as VT sequences, so that a client that connects late gets the exact screen (the snapshot);
• answer the program’s terminal queries itself while no person is attached;
• understand what agents’ interfaces use today: synchronized output (DEC 2026), the kitty keyboard protocol, colors queried with OSC 10 and 11, hyperlinks, wide graphemes.

vt100 does none of the first two and little of the third. Ghostty’s terminal core is published as a C library, libghostty-vt, with no dependency on Ghostty’s interface. It has a formatter that writes a screen as VT sequences (with modes, cursor, keyboard protocol, palette, scrolling region and tab stops), callbacks for every query (device attributes, cursor position, version, colors, size), and a render state with row and cell iterators that fill a ratatui buffer directly. zmx, cmux and agent-tty already build on it.

Rust bindings, as of 2026-11-08:

Decision

• volee uses libghostty-vt, pinned to an exact version (=0.2.2) in the workspace. Its build script fetches Ghostty’s official repository at one pinned commit and builds the library with Zig. volee’s own code calls only the safe API, so the workspace keeps unsafe_code = "forbid".
• A new crate, volee-term, wraps it: a Screen (one terminal: feed bytes, resize, snapshot as VT, answer queries) and a ratatui widget that draws a Screen into a buffer. No other crate depends on libghostty-vt directly, so a change of binding touches one crate.
• The handles of libghostty-vt are neither Send nor Sync: each Screen lives on one thread (the host’s terminal thread, the interface’s thread).
• vt100 is removed. The previews of sources volee does not host go through volee-term too.
• Zig becomes a build dependency, at the version the pinned commit requires (0.15.2 today):
  • contributors install it (brew install zig@0.15, the official archive, or any version manager) and CONTRIBUTING.md says so;
  • CI installs it with a pinned setup action;
  • the release workflow gets it through github-build-setup in dist-workspace.toml, and release.yml is regenerated with dist generate, never edited by hand.
• The MSRV becomes 1.90, the binding’s own.
• An update of the binding is a pull request of its own, checked by the host’s snapshot tests and a run on a real agent.

Consequences

• A screen is the same everywhere: in the host, in a preview, in the wall of screens and after an attach, with the colors and modes Ghostty would show.
• Building volee needs Zig and, on the first build, network access to github.com (or GHOSTTY_SOURCE_DIR pointing at a checkout of the pinned commit). The first build takes about a minute and a half more; later builds reuse the library.
• The library is linked statically: no runtime dependency for people who install the release binaries.
• libghostty-vt’s C API is young (its 1.0 tag is the first stable ABI, and names changed before it). Pinning the binding exactly keeps surprises to deliberate updates.
• If the binding stalls, the fallback is our own -sys crate over the official source tarball, behind the same volee-term API.

Alternatives considered

• vt100 first, libghostty-vt later. Cheaper to start, but no snapshot formatter and no query answers, which the host needs from day one. The product owner chose libghostty-vt right away.
• ghostty-vt (gpui-cn). Builds from the official tarball checked against a sha256, which is better, and uses Zig 0.17. But it serves one application, is licensed Apache-2.0 only and needs Rust 1.96. Worth revisiting if libghostty-vt stops following Ghostty.
• ghostty-vt-rs-sys. Prebuilt static libraries from a third party: a binary in the supply chain that nobody here built.
• alacritty_terminal. Pure Rust and mature, but no formatter back to VT sequences and no query callbacks; the host would have to write both.
• Our own -sys crate now. More work before the first prototype, for a benefit (the tarball and its sha256) that the fallback above keeps open.

0021. Take over with a or volee attach, leave with Ctrl+Q, watch on a wall

• Status: Accepted; taking over from the interface amended by 0026, the wall by 0028
• Date: 2026-11-08

Since ADR 0028, the interface’s wall is a view of the interface itself, on every agent of the list that runs, in a volee host or not. volee host wall stays the wall described below.

Since ADR 0026, i or a in the interface enters edit mode inside volee’s full-screen view instead of handing over the whole terminal, and that view is live. volee attach, the leave key, the size rules and the wall stay as below.

Context

With a host per agent (ADR 0019), volee itself connects a terminal to an agent: there is no claude attach to call any more. Three ways of looking at agents need rules:

• take over: type into the agent from the interface (a) or from any terminal, and come back;
• watch: the preview beside the list, and the full-screen view (z);
• several at once: the product owner wants a wall of live screens, to see what every agent is doing without opening each one.

Until 0.7.0, Ctrl+Z left a claude attach because Claude Code chose that key. volee now chooses. A key that leaves must never reach the agent, must be rare in agents’ own shortcuts, and must survive the keyboard protocols agents switch on: once a program enables the kitty keyboard protocol, the person’s terminal no longer sends 0x11 for Ctrl+Q but ESC [ 113 ; 5 u.

Decision

Take over. a on an agent suspends the interface, connects its terminal to the agent’s host as the input owner, and comes back to the same row when the person leaves. volee attach <agent> does the same from any terminal and returns to the shell. Before switching, it prints one line saying how to come back.

Leave with Ctrl+Q. The client reads the person’s keys and removes Ctrl+Q before they reach the host, in every encoding: the plain byte 0x11, the kitty keyboard protocol (CSI 113 ; 5 u, with any event type), and xterm’s modifyOtherKeys (CSI 27 ; 5 ; 113 ~). Agents never receive Ctrl+Q. The key becomes configurable later if someone needs Ctrl+Q inside an agent.

One owner, one size. The input owner’s terminal size is the agent’s size: the client sends it when it connects and each time the terminal is resized. When the owner leaves, the size stays. Taking over from a second terminal moves the input there; the first client is told and returns to its caller. No one else ever resizes an agent.

Clean entry and exit. On entry the client switches the person’s terminal to the alternate screen, clears it and writes the host’s snapshot. On exit it turns off what the agent may have left on (mouse reporting, bracketed paste, focus events, kitty keyboard flags, hidden cursor, the agent’s own alternate screen), then restores the person’s screen.

Watch. The preview and the full-screen view are watchers: a socket to the host, a Screen of volee-term fed by the snapshot and the stream, drawn into a ratatui buffer cell by cell with its colors. An agent’s screen is drawn at the agent’s size, never resized for the view. When the area has fewer rows, runs of blank rows shrink to one (an agent sized by a tall terminal leaves a gap between its conversation and its prompt), then the view keeps the rows from the bottom of what is drawn, or the cursor, upwards. Columns that do not fit are cut on the right.

The wall of screens. A fifth view (5, after the hierarchy, the network, the repositories and the timeline) shows the agents of the current list as tiles of live screens, as many as the terminal can hold at a readable size (1, 2, 4, 6 or 9). Arrows or hjkl move between tiles, a takes over the selected one, z shows it full screen, and the filter (/) narrows the wall like the other views. Only visible tiles keep a watcher; tiles that scroll away close theirs.

Agents volee does not host. Their screen comes from what their location offers, drawn by the same emulator: a pane capture when a location adapter knows their pane, the harness’s replay (claude logs) for a Claude Code background session, nothing otherwise. volee never types into them: a focuses their pane when an adapter knows it, and otherwise offers to adopt them (ADR 0023).

Consequences

• Taking over works the same for every harness and from any terminal, and leaving never depends on the agent’s own shortcuts.
• Watching costs one socket and one emulator per visible screen, and never disturbs the agent: no resize, no redraw, no query.
• An agent sized by a wide terminal shows cut in a narrow tile. The wall favors seeing many agents over seeing all of one; z shows all of one.
• Ctrl+Q is taken from agents. None of the supported harnesses binds it today, and flow control (XON) is off in the raw mode clients use.

Alternatives considered

• Keep Ctrl+Z. It suspends programs in every shell and some agents use it; intercepting it would surprise people more than Ctrl+Q does.
• A prefix key, like tmux. Costs a key press on every shortcut, for one action.
• Scale screens down to fit a tile. Text cannot be scaled in a terminal; dropping columns makes code unreadable. Cutting keeps what is shown exact.
• The newest client sets the size, as claude attach does. Measured: a watcher that connects resizes everybody, and the size sticks after it leaves. Only the person typing should decide it.

0022. A profile per harness says how to launch, resume, find and read it

• Status: Accepted
• Date: 2026-11-08

Context

Until 0.7.0, volee launched only Claude Code, and other harnesses could only join through MCP (ADR 0014). A host (ADR 0019) runs any command line in a terminal, so volee can launch and watch any harness. What differs between harnesses is small and factual: the command that starts a session with a first prompt, the one that resumes it, the process that shows it is running, and where its state can be read.

The product owner’s order: Claude Code, Codex CLI, Gemini CLI and Grok Build first, then the most used ones (OpenCode, Copilot CLI, Aider, Amp, Cursor’s agent, Qwen Code), and any other command line.

Decision

A harness profile is a value in volee-harness, with these parts:

States, best source first. The vocabulary stays (working, needs you, idle, done, failed, stopped). Each profile lists its sources in order:

1. the harness’s hooks, for agents volee launched with its own settings;
2. a server or listing the harness documents (claude agents --json, Codex’s app-server), for any agent;
3. the screen, as a last resort: output in the last seconds means working, the bell or a profile’s prompt pattern means needs you, silence means idle. The host gives every watcher these signals (activity, title, bell) without a parser of its own.

The generic profile runs any command line. It has no resume, no session id and only screen states. It is how a new harness is used before it has a profile, and how a person runs a script or a REPL in a host.

Profiles land one at a time, each with a probe on the real program that measures its commands, its processes and its states, written down in the reference docs (as the Claude Code mechanics were). A profile states the harness version it was measured on, and volee checks it at launch as it does for Claude Code. What a probe did not measure stays out of the profile.

Consequences

• Launching an agent of another harness is a choice in the launch dialog and a --harness flag, not new code paths through the daemon.
• States are as good as the harness allows: exact with hooks, coarse with a listing, guessed from the screen otherwise, and the interface says which.
• Each new harness costs a probe and a small profile; the generic profile covers the time in between.
• Harnesses change their flags often. A profile that fails its version check falls back to the generic profile for screen states and says so.

Alternatives considered

• ACP (the Agent Client Protocol) for every harness. About forty agents speak it, natively or through an adapter, and it gives structured states. But the ACP client spawns and owns the agent and renders it itself: there is no terminal to take over, and it cannot observe a session started elsewhere. It stays a possible later source of states for hosted agents.
• Screen parsing only. Works everywhere, but guesses where hooks and listings know.
• Profiles in the configuration file. Lets people add a harness without a release, but the launch and resume rules need tests. The generic profile already covers “run this command”; user-defined profiles can come later.

0023. volee shows every agent on the machine, and adopts the ones it did not start

• Status: Accepted (supersedes 0018; amends 0004 and 0015). Amended by 0027: an agent volee did not start is no longer read only, opening it needs no adoption, and adopting one is a choice.
• Date: 2026-11-08

Context

volee’s promise is to show every coding agent on the machine. Until 0.7.0 it found agents through claude agents --json only, so a Codex CLI or Gemini CLI started in a terminal was invisible unless it joined through MCP (ADR 0014). With hosts (ADR 0019) volee’s own agents are easy to see; the others need a source that works for every harness.

Every running agent is a process. Its program says which harness it is, and its working directory gives the repository and branch through git. Reading the process table (ps) and a process’s directory (/proc on Linux, lsof on macOS) uses documented system interfaces, not a harness’s internal files, which ADR 0004 forbids.

Mirrors (ADR 0018) matched a pane to a session by its title. The product owner rejected them.

Decision

Sources. The daemon reconciles four sources into one list:

1. hosts: volee’s own agents, exact and live;
2. the process table: every process of the current user that a harness profile (ADR 0022) recognizes, without its helpers, with its directory, and so its repository and branch;
3. harness listings and servers where they exist (claude agents --json, Claude Code hooks, Codex’s app-server), which add session ids and states;
4. location adapters (tuios, tmux), now only a read-only source of screens for agents that run in a pane, matched by the multiplexer’s own record of the session id or by process ancestry, never by title.

Joins use, in order: the host’s own record, the harness session id, the process id with its start time. A process seen in the table and in a listing is one agent.

Identity. ADR 0001 does not change: an agent started elsewhere gets an agent on first sight, with the role independent, keyed by its session id when its profile gives one, else by its process and start time.

Read only. volee never types into, resizes or stops an agent it does not host. Its screen comes from its location, as ADR 0021 says.

Adopt. For a harness whose profile can resume, A on an agent started elsewhere moves its conversation into a host:

1. the original must end first, so that two programs never write the same conversation: volee stops a background session with the harness’s own command (claude stop), and asks the person to quit an agent that runs in a terminal, then waits for its process to end;
2. volee runs the profile’s resume command (claude --resume, codex resume, gemini --resume) in the same directory, in a new host;
3. the agent keeps its volee identity; the resumed session joins its lineage.

Mirrors are removed in the release that brings hosts, with their code (mirrors in the daemon, Multiplexer::mirrors).

Cost. One ps per discovery round (about 17 ms measured on this machine), and one directory lookup per process seen for the first time, cached by process id and start time.

Consequences

• An agent of any known harness appears within a discovery round, wherever it was started, with its repository and branch.
• Agents started elsewhere have the states their harness exposes: exact for a Claude Code session (listing), coarse or none for others until adopted.
• Adopting is the one way to take full control of an agent volee did not start, and it never runs two copies of a conversation.
• A harness that renames its program, or runs as a generic interpreter, needs its profile updated; the profile’s probe says what to match.
• Only the current user’s processes are read.

Alternatives considered

• claude agents --json only. Sees Claude Code only.
• Every harness joins through MCP. Needs the person to configure each harness, and shows nothing for an agent that was not.
• Read harnesses’ session files. Rich, but undocumented and unstable, as ADR 0004 says.
• Match panes by title (ADR 0018). Ambiguous, and tied to a multiplexer.
• Adopt without stopping the original. Two programs would write the same conversation.

0024. Agents interrupted by a reboot come back in new hosts

• Status: Accepted
• Date: 2026-11-08

Context

A host (ADR 0019) keeps its agent alive while the machine runs. A reboot, a logout or a crash of the host ends the program, but the conversation is saved by the harness and the worktree is on disk. The product owner wants volee to bring such agents back by itself.

Some agents must stay down: one stopped with volee stop comes back only when someone writes to it, and the agents of a mission that is over never come back (ADR 0007). An agent that crashes as soon as it starts must not be restarted in a loop.

Decision

• Interrupted. A host record whose program has no exit status, whose host process is gone, and whose agent was not stopped by volee, is an interrupted agent. A machine that stopped leaves exactly that.
• Resume. When the daemon starts and finds interrupted agents, it runs each one’s resume command (ADR 0022) in a new host, in the same directory and worktree, with the same settings. The resumed session joins the agent’s lineage (ADR 0001).
• Not resumed: agents stopped by volee, agents of a mission that is over, agents whose harness cannot resume (the generic profile: they are shown as interrupted, with a relaunch action), and agents interrupted twice within ten minutes (shown as failed, with the reason).
• When. The daemon starts the first time volee is used after the reboot, as today. volee daemon install registers it to start at login (a launchd agent on macOS, a systemd user unit on Linux), so that agents come back without opening volee. volee never installs it unasked.
• Setting. [agents] resume_after_reboot = true by default; false shows interrupted agents with a resume action instead.

Consequences

• After a reboot, every agent that was working comes back with its conversation, in its worktree, and the timeline shows the interruption.
• A resumed agent has lost what it was doing in the middle of a turn (a command running, a half-written answer): the harness resumes from the last saved message. The resume prompt says the machine restarted.
• Without the login item, nothing comes back until volee runs once.
• Records of hosts accumulate in <state>/hosts/; the daemon removes the ones of agents that are forgotten or tidied.

Alternatives considered

• Resume nothing, offer a button. Simpler and safe, but the product owner wants agents to continue on their own.
• Keep agents alive across reboots. Impossible without the harness; its saved conversation is what survives.
• Install the login item on first run. Changes the person’s system without asking.

0025. Key sequences, a leader key and which-key popups; every key configurable

• Status: Proposed
• Date: 2026-11-09

Context

ADR 0009 put every binding in one table, from which dispatch, the help and the hint bar are generated, and let users move an action to one other key. By 0.8.1 the product owner hit four limits:

• The help scrolled. It was one column of about 160 lines: at 120x40, only “Everywhere” and part of the agents list were in sight.
• Keys were not the ones people expect. volee is used by people who live in vim, LazyVim and terminal tools such as lazygit or k9s. n and N launched an agent and a mission where those people expect the next and previous match; g went to the top in one key where they type gg; there was no Ctrl+d / Ctrl+u, no :.
• The theme could not be found. Themes existed ([tui] theme, five built-in, user files), but nothing in the interface said so or let anyone change it.
• Not every key could be changed. Overrides were one key per action, in every context at once, never none. The wall, the text fields, the launch dialog’s choices and the leave key of a take over (Ctrl+Q, ADR 0021: “configurable later”) were written in code.

He chose, among proposals: a which-key popup at the bottom right, a leader on the space bar as in LazyVim, vim-aligned keys, every key configurable, and a theme picker with a live preview that keeps its choice, plus a light or dark guess when no theme is set.

Decision

Sequences. A binding is a sequence of one to three keys: q, g g, space n. The interface keeps the keys typed so far: a key that starts longer sequences waits for the next one, a whole sequence acts, anything else (Esc included) drops it. There is no timeout: a key is either an action or a prefix where it applies, and the keymap refuses a key that would be both (g alone would hide gg), so nothing ever waits to guess.

The leader. The space bar starts the less frequent actions: Space n new agent, Space N new mission, Space t theme, Space w wall, Space k every key, Space o / a / f open with, adopt, forget. Frequent actions keep one key (j, k, a, m, d, /, ?). This is not the prefix key ADR 0021 refused: that one would have cost a key press on every shortcut, the leader costs one on rare ones only.

Which-key popups. While a sequence waits, a popup at the bottom right lists what can follow, a key and a label each, groups marked. ? opens the same kind of popup with the keys of the current screen (the focused panel, then everywhere), pairs folded into one entry (h/j/k/l move, gg/G first/last, 1-4 views) and laid out in columns so that nothing scrolls; any other key closes it and acts. ? ? (or Space k) lists every key of every context in columns. Every binding gets a short label for these popups, next to its description for the guide.

Vim-aligned defaults. gg / G, Ctrl+d / Ctrl+u (and Page Down / Up) wherever something scrolls, n / N through the agents that match the filter, H / L previous and next view, : a command palette that runs any action of the screen, or a theme, by name. New agent and new mission move behind the leader.

Every key configurable. [tui.keys] takes one key, a list, or [] to unbind, for an action in every context, and [tui.keys.<context>] tables for one context. The wall (wall), the text fields (editing), the dialog’s choices (choice), the popups and the palette have contexts like the panels. The leave key is the leave action of the attached context: Control and a letter, the only keys that reach volee the same way in raw mode, under the kitty keyboard protocol and with modifyOtherKeys; not h, i, j or m, whose Control bytes are also Backspace, Tab, Line Feed and Enter. volee attach, volee host attach and the wall read it from the configuration. Typing keys (characters, Backspace, the arrows in a text) are not shortcuts and stay fixed.

Themes. Space t or :theme opens a picker at the bottom right; moving shows each theme at once, Enter writes [tui] theme into the configuration file without touching anything else in it (comments, order, other keys), Esc restores the theme there was. Without a configured theme, volee asks the terminal for its background colour (OSC 11, bounded wait, skipped when not a terminal, then COLORFGBG) and picks catppuccin-latte on a light background, catppuccin-mocha otherwise. volee --theme <name> overrides both for one run.

Consequences

• The popups, the hints, the palette and the guide’s key tables all come from the one table: a binding is still one line, now with a label.
• People used to 0.8 lose n / N for launching (now Space n / Space N) and g alone for the top (now gg); the hint bar announces ␣ more, and ? shows the new keys.
• A configuration with a typo fails to start the interface with the line and the action named; the wall and a take over from a shell fall back to the default keys with a warning rather than refusing to work.
• The light or dark guess queries the terminal once at start; a terminal that does not answer costs the bounded wait (700 ms) and keeps the default.

Alternatives considered

• A timeout for ambiguous keys, as vim’s timeoutlen. Allows g and gg together, but makes g slow and the interface guess. Refusing the ambiguity is simpler and keeps every key instant.
• A larger help page. The product owner asked for less scrolling; a page at least as big as the screen cannot give that once the keys grow.
• Keep n / N for launching. Launching is rare and costs money; the next match is a reflex. The leader keeps launching two keys away.
• Configure the leave key as any key. Only Control and a letter survives every keyboard protocol an agent may switch on.