Architecture

How the pieces fit together, and the decisions that are settled.

The pieces

You talk to a commander. It dispatches soldiers, each in its own camp, and a sentinel wakes it when one settles.

Diagram of vexillum's pieces. The general talks to the commander and reviews its artifacts in the forum. The commander runs vx dispatch on the vexillum binary, which keeps state on disk and opens a camp where a soldier runs in a herdr pane. The sentinel polls herdr, records outcomes in the state and wakes the commander: through the Stop hook in Claude Code, through a wake extension in Pi, or by posting into the session through OpenCode's API. The commander and the soldiers can each run on Claude Code, Pi or OpenCode.
The pieces of vexillum and how they talk to each other.
  • You talk to the commander, a Claude Code session (or Pi or OpenCode, see Pi as the commander and OpenCode as the commander) steered by AGENTS.md and skills. It opens artifacts for you in the forum and reads your feedback from there.
  • The commander runs vx dispatch. The vexillum binary keeps its state on disk, acquires a camp and starts a soldier in a herdr pane.
  • The sentinel polls herdr every 5 seconds, records each outcome in the state and wakes the commander. A Claude Code commander is woken by the Stop hook, a Pi commander by a wake extension that runs inside Pi, and an OpenCode commander by the sentinel posting the wake into its session through OpenCode's API (see Sentinel).

Decisions that are settled

  • Go, shipped as a binary by Homebrew and curl, with no runtime dependencies.
  • Claude Code is the default harness for the commander and for every soldier. A model profile can run its soldiers on Pi or OpenCode instead; the binary reaches all of them through one Harness interface.
  • herdr hosts the panes the soldiers run in.
  • Intelligence is markdown, not Go. The binary does deterministic plumbing; routing and judgment live in the AGENTS.md core and the skills.
  • Domain vocabulary stays in English (commander, soldier, mission, scout, camp, sentinel) in every language.
  • One commander. You always talk to a single commander.

Safety model

LayerGuarantee
campcommits and working tree are isolated from yours
landfast-forward only; refuses a dirty checkout or a diverged branch; never forces
strikerefuses while the camp has uncommitted or unlanded work
shippushes only after every tribunal step passes, deterministically
redispatch, strike --discardthe only operations that discard a camp, so the commander asks first

The process itself is not sandboxed. See the warning on the introduction.

On this page