vexillum

CLI orchestrator for code agents, written in Go. You talk to a commander (Claude Code by default, or Pi or OpenCode), and it dispatches soldiers in parallel, each isolated in its own git worktree (camp), returning a PR (mission) or a report (scout). A sentinel process watches dispatched soldiers and wakes the commander when something needs attention.

See AGENTS.md for how vexillum itself is built.

Install

Requirements:

• macOS or Linux, amd64 or arm64 (Windows is not supported)
• Claude Code, installed and logged in (subscription or API key), for the default commander and soldiers; a project whose commander runs in Pi or OpenCode needs that CLI instead
• herdr (brew install herdr works)
• a git repository for your project
• optional: gh (for vx ship)
• optional: Pi, only if a model profile sets "harness": "pi" to run its soldiers on Pi instead of Claude Code
• optional: OpenCode (1.x from 1.18.29, or 2.x), only if a model profile sets "harness": "opencode", or to run the commander in OpenCode 2.x (vx init --commander opencode, see the guide); Pi can run the commander too (vx init --commander pi, see the guide)

Example models.json profiles that run scouts and missions on Pi or OpenCode with free and cheap models are in Models for other harnesses and in docs/examples/.

vx doctor checks that the CLI of each of the project's commander harnesses (Claude Code by default), herdr and git are present, and that the project scaffold is healthy. It does not check that Claude Code is logged in, your OS or architecture, or that you are inside a herdr pane; vx dispatch only works inside a herdr pane.

Warning: soldiers run Claude Code with --dangerously-skip-permissions (or Pi, which has no permission prompts at all, or OpenCode with --auto), as your OS user, with no container or sandbox. Landing a mission is the approval gate: nothing reaches your project's real history until you approve it. Never dispatch against a repository or machine where reading credentials would be a problem.

macOS / Linux, via Homebrew:

brew install isaias-alt/tap/vexillum

macOS / Linux, via curl:

curl -fsSL https://raw.githubusercontent.com/isaias-alt/vexillum/v0.1.1/scripts/install.sh | bash

Both install a prebuilt binary for your platform (amd64/arm64). The curl script verifies the release checksum before installing.

Both install the latest stable release. To try the latest canary build (no stability promise) or an exact version, pass an option to the script:

curl -fsSL https://raw.githubusercontent.com/isaias-alt/vexillum/v0.1.1/scripts/install.sh | bash -s -- --channel canary
curl -fsSL https://raw.githubusercontent.com/isaias-alt/vexillum/v0.1.1/scripts/install.sh | bash -s -- --version v0.1.1

Usage

Command	Description
vx init	Prepare the current project to be orchestrated by vexillum
vx upgrade	Update vx to the latest release, then refresh the project's vexillum scaffold
vx doctor	Report on the health of the vexillum environment
vx dispatch	Dispatch a soldier (mission or scout) into an isolated camp
vx models	List the model and effort profiles a dispatch can use
vx yolo	Turn yolo mode on or off for this project, or print whether it is on
vx redispatch	Re-dispatch an interrupted task from its original prompt
vx decide	Answer a blocked task's open question so it can continue
vx prompt	Send a follow-up prompt to a soldier that already finished
vx pending	Record and clear the commander's own pending decisions
vx status	Report the troop: every mission and scout in the current project
vx land	Land a finished mission's work into this project's base branch
vx ship	Ship a finished mission through vexillum's own tribunal pipeline, opening a real pull request
vx strike	Strike a soldier's camp (dismantle it and return it to the pool) once its work has landed
vx sentinel	Watch dispatched soldiers and record status changes
vx forum	Open a local HTML artifact for visual review and collect the user's feedback

Run vx --help for the full command list, or vx <command> -h for a specific command.

Files and folders

vx init scaffolds this inside your project; commit it (the backups and forum/ aside):

<project>/
  AGENTS.md or CLAUDE.md     the vexillum block (CLAUDE.md is "@AGENTS.md" when AGENTS.md exists)
  .claude/
    settings.json            the sentinel Stop hook (Claude Code commander)
    skills/                  the vexillum, forum and muster skills
  .pi/                       only for a Pi commander: settings.json and extensions/vexillum-wake.ts
  .vexillum/
    config.json              marks the project initialized and records its commander harnesses
    models.json              model and effort profiles (yours to edit)
    yolo.json                yolo mode switch, only after `vx yolo`
    .gitignore               ignores forum/
    forum/                   scratch artifacts written by agents (gitignored)

Machine-level state lives in ~/.vexillum/, outside your repositories. It is plain JSON, written atomically, and one namespace per project:

~/.vexillum/
  models.json                optional global model profiles
  sentinel.*, sentinel-awaiters/   the single sentinel: locks, build record, log
  forum/, forums/<session>/        the forum server, listener and review sessions
  projects/<repo>-<hash>/
    tasks/                   one JSON file per task
    camps/                   the worktree pool: pool.json and <slot>/<repo>/
    wakes/  forum-inbox/     pending notifications for the commander
    pending/                 the commander's pending decisions
    reports/  pauses/        scout reports and declared soldier pauses

Do not delete camps/ or a task file by hand; use vx strike. See Files in the docs for every entry and whether it is safe to delete.

Contributing

See CONTRIBUTING.md for how to build, test, and submit a PR. Found a bug or have a feature request? Open an issue using the templates in .github/ISSUE_TEMPLATE/. To report a vulnerability, do not open an issue: follow SECURITY.md. Everyone taking part is expected to follow the Code of Conduct.

Regenerating the command reference

The command list is defined once, in the registry in internal/cli/commands.go (name, one-line summary, full usage). vx --help, the table above, and the per-command pages under site/content/docs/en/reference/cli/ are all derived from it - do not edit the generated parts by hand. After adding or changing a command, regenerate and commit the result:

go run ./tools/docgen

go test ./... fails with that same instruction if the committed files drift from the registry. tools/docgen is a dev-only tool: it is never part of the vx binary or its installation.

License

MIT