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.