Docs · Advanced
Orchestration.
On top of conflict prevention, Regente has an optional planning layer: turn a goal into dependency-aware tasks, route each to the agent that owns its lane, and pump the pipeline forward — all on the same claim, fence, and auto-handoff primitives. It stays join-don't-spawn: it assigns and reserves, it never writes code for your agents, and the only thing it ever launches is a summon command you declared yourself.
Tasks
A task has a title, description, optional deps (other task ids) and paths
(the files it touches), an assignee, and, once the work is done, a result. Claiming a task reserves all its paths at once — in sorted
order, all-or-nothing — so multi-file tasks can't deadlock, and it reuses the very same fence +
auto-handoff queue as ordinary claims (no second system).
todoCreated, not yet assigned.assignedRouted to an agent (by lane); its files are reserved.in_progressThe agent has claimed it and is working.blockedWaiting on a dependency or a file another agent holds — queued for auto-handoff.in_reviewWork is done and awaiting review.doneComplete.regente task create "Add export endpoint" --paths server/api/export.ts --deps task_3
regente task list --state todo
regente task claim task_7 --agent codex
regente task update task_7 --state in_reviewTask results
Tasks carry their outcome, not just a state. update_task accepts a
result (text, up to 8192 characters) and artifacts (up to 32 paths or
URLs); both are stored on the task with result_by and result_at.
Completion events carry a has_result flag, and check_handoffs delivers a
task's result in-band to its assignee, so the next agent reads the outcome without leaving its
session.
Messages and handoffs link back to tasks: post_message and
create_handoff accept a task_id, and list_messages can
filter by task_id or agent (plus a limit).
Review gates — regente go
The easy path is one command that walks the whole flow with an accept / edit / reject gate at each step — nothing is written until you accept, like a plan-mode approval:
regente go "Add a /health endpoint and a status badge"
Proposed plan (2 tasks):
1. Implement /health server/api.js
2. Status badge public/badge.js after #1
Plan: [a]ccept · [e]dit · [r]eject › # edit opens $EDITOR; reject writes nothing
Assignment:
task_… Implement /health → @codex-1 (server)
task_… Status badge → @gemini-1 (public)
Assignment: [a]ccept · [e]dit · [r]eject › # edit = reassign; accept → drive --yes skips the gates (CI / automation), --no-drive stops after assigning,
and --json runs it non-interactively and emits each stage. In a pipe (no TTY) it requires
--yes so it never silently commits. The desktop dashboard mirrors this exactly:
Plan opens an editable review card, Accept shows the assignment with a per-task reassign
dropdown, and Accept there assigns and drives — the live board updating underneath.
The granular commands
Prefer to script it? The three steps stand alone (and are what go orchestrates):
regente plan "<goal>" LLM (BYO key). Decompose a goal into dependency-aware tasks. Proposes only — you review before assigning. regente assign [taskIds…] [--no-reserve] No LLM. Route ready tasks to the agent that owns their lane and pre-reserve the files in a stable all-or-nothing order. regente drive [--no-assign] [--replan "<goal>"] No LLM*. Pump the pipeline: unblock what's ready, assign it, and surface a re-plan suggestion. *--replan calls the planner.
The same steps exist over MCP (assign_tasks, advance_tasks, plus the task
tools) and the HTTP API (POST /api/plan, /api/assign, /api/drive,
plus the review-gate routes /api/plan/propose, /api/plan/commit,
/api/assign/preview).
Summon (waking an offline assignee)
A role can declare a summon shell command: regente role ... --summon on the
CLI, or HTTP POST /api/role, with config.summon_default as the
fleet-wide fallback. Because the command executes on your machine, it is operator-configured:
the MCP assign_role tool accepts summon only when the bridge runs with
REGENTE_MCP_SUMMON=1. When a task is assigned
(assign_tasks, call_agent, an update_task assignee change,
or the drive loop) to an agent whose presence is offline, Regente runs that command
once per task and assignee, fire-and-forget, with REGENTE_ROOT, REGENTE_SUMMON_AGENT,
REGENTE_SUMMON_ROLE, REGENTE_SUMMON_TASK_ID, and
REGENTE_SUMMON_TASK_TITLE in the environment, and emits an
agent.summoned event. It runs under the same local trust model as hooks; set
REGENTE_SUMMON_DISABLE=1 to turn it off.
Bring your own LLM key (plan)
Only plan (and drive --replan) calls a model. Point it at your own key —
REGENTE_LLM_API_KEY, a provider key (OPENAI_API_KEY /
ANTHROPIC_API_KEY), or ~/.regente/llm.env. Planning is metered locally so you
can see token use. assign and plain drive are free and never touch a model.
Honest scope
The orchestration layer is real and wired across the CLI, MCP, HTTP, and dashboard — but it's early, and it's deliberately assist-only: the planner proposes, you approve and assign, and your agents do the work in their own sessions. The free wedge is the cross-vendor, pre-merge conflict prevention; orchestration and the signed system-of-record are where the paid tier is headed.