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.
| ADR | Decision | Status |
|---|---|---|
| 0000 | Record architecture decisions | Accepted |
| 0001 | An agent is a unit of work, not a pane or a process | Accepted |
| 0002 | The harness owns agent processes | Superseded by 0019 |
| 0003 | A daemon with an event log is the single source of truth | Accepted |
| 0004 | Hooks, harness listing, git and forge are reconciled into one model | Accepted |
| 0005 | Agents talk to volee through MCP and the CLI | Accepted |
| 0006 | Typed, threaded messages delivered through documented hooks (amended by 0031) | Accepted |
| 0007 | Missions are run by a supervisor program and a coordinator agent (amended by 0032 and 0033) | Accepted |
| 0008 | Multiplexers are optional location adapters | Accepted |
| 0009 | The TUI follows the Elm architecture with one keymap table | Accepted |
| 0010 | Git is read through the git CLI behind a trait | Accepted |
| 0011 | Destructive actions require delivery evidence (amended by 0032) | Accepted |
| 0012 | Rust, dual MIT/Apache-2.0, Unix first | Accepted |
| 0013 | Agent worktrees live in their repository | Accepted |
| 0014 | Agents of other harnesses join through MCP | Accepted |
| 0015 | tuios is the first location adapter (amended by 0030) | Accepted |
| 0016 | Reuse or tidy what a failed launch left untouched (refines 0011) | Accepted |
| 0017 | Setup commands prepare a new worktree before its agent starts | Accepted |
| 0018 | A pane that shows a background session is its preview | Superseded by 0023 |
| 0019 | A volee-host process holds each agent’s terminal (supersedes 0002) | Accepted |
| 0020 | libghostty-vt emulates every terminal volee reads | Accepted |
| 0021 | Take over with a or volee attach, leave with Ctrl+Q, watch on a wall | Accepted |
| 0022 | A profile per harness says how to launch, resume, find and read it (amended by 0029) | Accepted |
| 0023 | volee shows every agent on the machine, and adopts the ones it did not start (supersedes 0018; amended by 0027, 0029 and 0030) | Accepted |
| 0024 | Agents interrupted by a reboot come back in new hosts | Accepted |
| 0025 | Key sequences, a leader key and which-key popups; every key configurable | Proposed |
| 0026 | Edit mode types into an agent inside volee; the host encodes keys | Proposed |
| 0027 | volee opens every agent where it runs, and its list shows what runs (amends 0023, 0026, 0021 and 0004; amended by 0034) | Accepted |
| 0028 | One emulator for every screen, and the wall inside the interface (completes 0020; amends 0021, 0026 and 0027) | Accepted |
| 0029 | volee run makes any program an agent, in the terminal it is typed in (amends 0022 and 0023) | Accepted |
| 0030 | A multiplexer may say which of its panes run an agent (amends 0023 and 0015) | Accepted |
| 0031 | A question to the person may offer its answers (amends 0006) | Accepted |
| 0032 | A mission is merged only after the person approved its report (amends 0007 and 0011) | Accepted |
| 0033 | A lead is the agent you talk to, and it makes others work (amends 0007) | Accepted |
| 0034 | A session in a terminal of its own opens once it left it, on the same row (amends 0027) | Accepted |
| 0035 | The context an agent uses comes from its status line | Accepted |
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 attachas 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.