Quickstart

You need vexillum, Claude Code (the default commander; Pi and OpenCode work too, see Pi as the commander and OpenCode as the commander) and herdr installed. See Install.

1. Prepare your projectCopy Anchor Link

From the root of a git repository:

vx init

init changes files of yours, so it tells you which ones and asks first. Step by step:

1. Where the block goes. If the project has no AGENTS.md, init proposes putting the vexillum block in CLAUDE.md instead of creating an AGENTS.md:

   Copy Text

   This project has no AGENTS.md. Put the vexillum block in CLAUDE.md instead of creating an AGENTS.md? [Y/n]

   The default is yes (CLAUDE.md is created if it does not exist). Answer n to create an AGENTS.md instead. When the project already has an AGENTS.md, the question is not asked and the block goes there. See The AGENTS.md slot.

2. The notice. It lists the files of yours it is about to change, then vexillum's own files:

   Copy Text

   vx init will change these files of yours in /path/to/project:
     CLAUDE.md                  create it with the vexillum block
     .claude/settings.json      add the sentinel Stop hook
   It also writes vexillum's own files: .vexillum/config.json; .vexillum/.gitignore; .vexillum/models.json; .claude/skills/ (vexillum, forum and muster, you are asked first).
   Continue? [Y/n]

   Answer n and nothing is changed.

3. The AGENTS.md slot. The commander core is written between markers in the file you chose (CLAUDE.md by default, or AGENTS.md), in the language it detects there. You confirm or override the language.

4. The CLAUDE.md import. Only when the block is in AGENTS.md: CLAUDE.md gets the line @AGENTS.md so Claude Code sees the block. An existing CLAUDE.md is edited only after a second question.

5. The skills. Install the vexillum, forum and muster skills? [Y/n]. Yes writes them to .claude/skills/.

6. models.json. .vexillum/models.json is written with the default model and effort profiles. An existing one is never overwritten.

7. The sentinel hook. An async Stop hook in .claude/settings.json (a one-line command that runs vx sentinel await and finds vx without relying on your PATH) lets the sentinel wake the commander. Existing settings and hooks are merged, never overwritten.

It also creates ~/.vexillum/ if it is missing, and running init again changes nothing that is already in place.

Without a terminal (scripts, CI) init asks nothing and changes nothing unless you pass --yes:

vexillum installs per project only: run init in each project you want to orchestrate.

2. Check the environmentCopy Anchor Link

vx doctor

Everything required should read [ok].

3. Start the commander inside herdrCopy Anchor Link

Open a herdr pane, cd into the project and start your commander (Claude Code by default). vx dispatch needs HERDR_WORKSPACE_ID, which herdr sets in the panes it manages; outside one it refuses to dispatch.

4. Ask for workCopy Anchor Link

> dispatch a soldier to fix the flaky login test

The commander runs vx dispatch "fix the flaky login test" --kind mission, which prints the task id, the camp branch (vexillum/<task-id>), and status=running. The first dispatch also starts the sentinel in the background.

You can keep talking to the commander while the soldier works. That is the magic of vexillum.

5. Hear backCopy Anchor Link

When the soldier settles (done or blocked), the sentinel wakes the commander, which reports to you. To look yourself:

vx status

6. Land itCopy Anchor Link

When the mission is done, review it and tell the commander to land it. It runs:

vx land <task-id>

That fast-forwards your checkout to the mission's branch and returns the camp to the pool. If you want a reviewed pull request instead, see Land vs ship.