Multi-Agent Orchestration

Run multiple AI agents on one project in parallel, without them stepping on each other. luvus coordinates the team through a shared task board: every worker runs in its own isolated git worktree, path leases stop overlapping edits from even being assigned, quality gates verify work before it counts, and a merge gate integrates finished branches without ever touching your checkout.

TL;DR

Open the board (Ctrl+Space o), press a to add a task, s to start an isolated worker for it, d to finish (runs its quality gate), m to merge.

The concepts

Concept	What it is
Task	A unit of work: title, the file globs it will touch, dependencies, and an optional quality-gate command. Gets an id like t1.
Lease	A reservation on file paths. Two workers can’t hold overlapping globs, so conflicting work can’t be assigned.
Worker	A pane running an agent in a dedicated git worktree on its own branch (luvus/<id>) for physical isolation, so two workers literally edit different files on disk.
Quality gate	A command (e.g. cargo test) that runs when a task is marked done. It must pass before the task can merge.
Merge gate	Integrates a finished branch into luvus/integration inside a dedicated worktree, never your working checkout. A conflict blocks the task instead of corrupting anything.

Task lifecycle: queued → claimed/running → done (gate passed) or review (gate failed, so fix and retry) → merged, or blocked on a merge conflict. The ledger lives in ~/.luvus/orch.json, separate from your session.

The board

Open the ◇ orch tab with Ctrl+Space o. It shows every task (status · id · title · dependencies · worker pane and branch once started) and the active leases, live. Navigate with j/k, the wheel, or click a row.

Key	Action
a	new task: a Title / Paths / Deps / Gate form (⇥ between fields, ⏎ creates)
s	start an isolated worktree worker for the selected task
d	done: runs its quality gate (pass → done, fail → held at review)
m	merge into luvus/integration
⏎	jump to its worker pane
x	release it back to the queue
q	close the board

A worked example

Say you want an auth module and an API layer that depends on it:

1. a → Title OAuth token module, Paths src/auth/**, Gate cargo test auth, ⏎.
2. a → Title API layer, Paths src/api/**, Deps t1, ⏎.
3. Select t1 and press s. luvus creates a worktree on branch luvus/t1, opens a pane in it, and takes you there. Run your agent in that pane (or pass --agent via the CLI to launch one automatically).
4. When the work looks finished: back to the board, d. The gate (cargo test auth) runs in the background. Pass and t1 is done. Fail and it’s held at review with the output saved on the task.
5. t2 is now claimable (its dependency is done), so select it, s, repeat.
6. Select a done task, m, and the branch merges into luvus/integration in an isolated worktree. A conflict marks the task blocked rather than half-merging anything.

Your own checkout on main was never touched at any point.

Driving it from the CLI (and from agents)

Everything the board does is a command, which is how an orchestrator agent can run the whole loop itself:

# create + inspect
luvus task add "OAuth module" --paths "src/auth/**" --gate "cargo test auth"
luvus task list · get t1 · update t1 --status running --note "learning: …"

# start workers (parallel, isolated)
luvus task start t1 --agent "claude"
luvus task next --start --agent "claude"   # claim + start the next ready task

# finish + integrate
luvus task heartbeat t1 --context 0.6      # context gate: >0.85 blocks `done`
luvus task done t1                          # runs the quality gate
luvus task merge t1

# leases (usually automatic via task start)
luvus lease acquire "src/auth/**" --task t1

# react to everything, live (newline-delimited JSON)
luvus events

Inside a luvus pane, commands default to the calling pane via $LUVUS_PANE_ID, so a worker agent can luvus task heartbeat itself.

Events on the bus: task.added · task.claimed · task.started · task.ready · task.gate_running · task.gate_passed · task.gate_failed · task.needs_compaction · task.done · task.merged · task.merge_conflict · task.released · lease.acquired · lease.released.

The safety model

• Nothing spawns unattended. Workers start only when you press s or run task start.
• Your checkout is never touched. Workers edit in their own worktrees. Merges happen in a dedicated integration worktree.
• Conflicts can’t corrupt. The merge gate aborts cleanly on conflict and surfaces it (task → blocked).
• Two layers of isolation. Leases prevent overlapping work from being assigned, and worktrees mean even a misbehaving agent’s clash only surfaces (safely) at merge time.
• A context gate. Workers report context usage via heartbeat. Above 85%, done is blocked until the agent compacts, so there are no half-remembered finishes.

Troubleshooting

Symptom	Fix
s → not a git repo	The board needs a workspace that’s a git repository (workers are worktrees).
s → deps not done	A dependency task isn’t done yet.
d → needs compaction	The worker’s context is over 85%, so compact (e.g. /compact), then retry.
Stuck at review	The gate failed. luvus task get <id> shows the output. Fix and d again.
blocked after m	Merge conflict. Resolve in the task’s worktree, then m again.

Clean up a finished worker with luvus worktree remove <path> (the branch is kept).