Concepts
How vexillum works
The roles, and the life of a task from dispatch to strike.
The roles
| Term | What it is |
|---|---|
| general | You, the human. You talk only to the commander. |
| commander | The agent session you talk to: Claude Code by default, or Pi or OpenCode. It reads your request and the project's rules, then dispatches and tracks soldiers. |
| soldier | An agent session the commander starts to do one task, in its own camp. Claude Code by default, or Pi or OpenCode when its model profile says so. |
| camp | A soldier's isolated git worktree, on its own branch. |
| mission | A task that changes code and delivers something to land. |
| scout | A task that only investigates and reports back. It never commits or pushes. |
| sentinel | A background process that watches soldiers and wakes the commander when one settles. |
The life of a task
- You ask. In the commander's session (Claude Code by default) you say what you want.
- The commander dispatches. Following the project's rules it runs
vx dispatch "<prompt>" --kind mission|scout --model <m> --effort <e>. - A camp is acquired. vexillum takes a clean worktree from the project's pool (or creates one) on a new branch,
vexillum/<task-id>, forked from your current branch. - A soldier starts. A real, interactive session of the soldier's harness (Claude Code by default) opens in a herdr pane inside that camp. The command returns quickly: as soon as herdr sees the soldier working (or already settled), without waiting for the work to finish.
- The sentinel watches. It polls the soldier's live status and records the outcome on disk. See Sentinel.
- The commander is woken. The change is surfaced to the commander, so it reports to you even if its turn had already ended: by a
Stophook in Claude Code, a wake extension in Pi, or the sentinel posting into the session in OpenCode (see Sentinel). - You decide. For a mission, you land it or ship it. For a scout, the commander relays the report.
- The camp is struck, returning to the pool, once there is nothing left to lose.
What isolation does and does not give you
A camp isolates the soldier's commits and working tree from yours. It does not sandbox the process: a soldier has full host access under your OS user. The real safety control is approval before landing.
Where the intelligence lives
The binary is deterministic plumbing (state on disk, worktrees, panes, refusals). Choosing a model, deciding to ask you, phrasing a report: that is the commander's judgment, steered by markdown. See AGENTS.md and rules.