Docs
CLI reference.
The regente CLI is a thin dispatcher over the same engine the agents (via MCP), the HTTP
API, and the dashboard all share. Add --json to most read commands for machine output, and
--root <path> to target a repo other than the current directory.
Setup
regente install [--no-wait] [--wait-minutes N] [--json]End to end: initializes .regente/, writes session hooks + MCP config + the regente agent skill for Claude Code, Codex, Gemini, and Cursor, VERIFIES the wiring per tool, prints the connect-your-first-agent steps, and (in a terminal) waits until a real agent joins so success means verified. --no-wait skips the wait; --json prints machine output.regente install --tools <list>Limit or customize the vendor set, e.g. --tools claude-code,codex. Defaults to codex,claude-code,gemini,cursor (all four).regente promptPrint the paste-into-any-agent onboarding prompt (join, claim/release discipline, inbox + receipts, task results, exact usage reporting). Also available as a copy button in the dashboard's onboarding card.regente init [--reset]Low-level state setup only. Usually unnecessary because regente install initializes the workspace.Coordinate
regente join --agent <id> [--tool <t>] [--role <r>] [--task <s>]Join the workspace. Usually automatic via the session hook; use it to attach a session by hand.regente symbols <file> [--json]List the claimable symbols (functions/classes/methods) in a file, with line ranges. JS/TS and Python.regente claim <path> --agent <id> [--symbol <name>] [--mode write|read] [--reason <t>] [--fence <n>]Claim a whole file, or one function with --symbol. Prints the granted fence; a blocked claim is queued and reports your position.regente release <path> [--symbol <name>] [--agent <id>] [--fence <n>] [--force]Release a file or symbol claim you can prove you own (by --agent or --fence) — auto-hands it to the next waiter. --force is the operator escape hatch.regente role --agent <id> --role <role> [--paths "a,b"] [--summon "<cmd>"]Give an agent a role; presets carry default lanes, or set custom lanes with --paths. One role per agent. --summon declares a shell command Regente runs (once per task and assignee, REGENTE_SUMMON_* env vars) when a task is assigned to this role while its agent is offline; --summon '' clears it.regente roles [--json]List every role, the agents holding it, and its lanes.regente lanes [--json] [--apply]Show the lanes Regente INFERRED from each agent's claims (zero-config territory). --apply materializes them as roles for agents that haven't declared one.regente context add "<why>" --agent <id> [--kind decision|finding|warning|note|question] [--paths "a,b"] [--task <id>]Share the WHY behind a change, tied to files/a task. Auto-delivered to agents that pick up coupled work.regente context [--path <p>] [--task <id>] [--agent <id>]Read shared context, filtered by file, task, or agent.regente handoff --from <id> --to <id> --task <t> --summary <s> --next-step <n> [--task-id <id>]Record an explicit handoff note from one agent to another. --task-id ties it to a tracked task for an auditable trail.regente msg --from <id> --text <t> [--to <id>] [--task-id <id>]Post a message to the backchannel (broadcast, or direct with --to). --task-id links it to a task. Direct messages carry delivered_at (stamped when the recipient fetches them) and read_at (stamped on ack).regente ack <messageId…> --agent <you> [--json]Acknowledge direct messages addressed to you: stamps read_at so the sender can tell delivered-and-read from ignored. Only the addressed recipient can ack; room messages carry no ack state.regente announce "<text>" --from <id> [--to <id>]Post a fleet-wide announcement. Use --to only when an announcement should be scoped to one agent.regente call <target-agent> "<title>" --from <id> [--summary <s>] [--next <n>] [--paths a,b]Delegate work to another joined agent. Creates an assigned task, direct call message, and handoff.regente usage --agent <id> [--tool <t>] [--tokens-used N] [--tokens-limit N] [--context-used N] [--context-limit N] [--source <s>] [--json]Report real per-agent token and context usage for dashboard bars (the MCP equivalent is report_usage). Omit unknown values; Regente will not guess vendor limits.Enforce
regente enforce [off|warn|strict]Set (or, with no arg, print) the enforcement mode for this repo. Default warn.regente guard <path> [--line <n>] [--symbol <s>] --agent <id> [--mode <m>] [--json]Pre-edit guard (used by the Claude Code PreToolUse and Gemini BeforeTool hooks): exit 0 = allowed, 2 = blocked. An allowed edit auto-claims an unclaimed file for the editor (set auto_claim to false in .regente/config.json to disable) and warns when a different online agent edited the same file within the last 30 minutes (config recent_edit_warn_minutes). --line resolves to the symbol it lands in.regente verify-commit --agent <id> [--files a,b] [--json]Git pre-commit guard: blocks committing files held by another agent. Reads staged paths with git -z; fails closed on a git error.Inspect & maintain
regente watch [--once] [--interval <s>] [--limit <n>]Live terminal view of the fleet, claims, conflicts, and queue — refreshes in place (~2s). --once prints a single snapshot.regente status [--limit <n>] [--json]One-shot snapshot: workspace, agents with online/joined counts and per-agent presence (offline rows show last seen), active claims, the queue, recent messages/handoffs.regente queue [--json]Show the auto-handoff queue — who's waiting on which file, granted automatically on release.regente inbox --agent <id> [--cursor <c>] [--json]What's waiting for you: files auto-handed to you, direct messages, and files you're queued on.regente discover [--json]Which Claude / Codex / Gemini / Cursor processes are actually running in this repo.regente metrics [--json]Activation, cross-tool depth, conflicts surfaced, auto-handoffs, plus a usage block (token/context totals covering only the agents that reported real values, labeled with the reporting-agent count). --json prints the full payload.regente doctor [--adapters] [--repair] [--json]Health check. --repair rewrites stale or missing repo-local adapter wiring for Claude Code, Codex, Gemini, and Cursor.regente verify [--json]Verify the signed event log offline against each signer's key.regente sweep [--json]Reclaim contested files held by an agent that's gone dark (no heartbeat for >15 min) and hand them to the next waiter; a fresh waiter skips the grace window when the holder has been dark for twice that. Orphaned auto-claims of dead sessions are released too, and ALL of a holder's claims expire once it has been dark past claim_expiry_minutes (default 60; 0 disables) — an actively working agent can't trip this because every hook event and MCP call refreshes presence. Queued waiters expire on the same window (queue.expired), so a release never grants a file to a long-gone session, and tasks assigned to (or in flight with) a gone agent revert to todo (task.unassigned, reason assignee-gone). The desktop/daemon runs this sweep automatically every 30s.regente prune [--days N] [--json]Roster hygiene: drop agent records that have been dark for N days (default 7) and hold no claims; pruned names also leave role rosters. Keeps long-lived workspaces from burying the live fleet under dead one-shot sessions.regente compact [--json]Compact large state logs into a snapshot so long-running workspaces stay fast.Delivery loop
regente github app configure --app-id N --installation-id N --private-key-path <path>Save local GitHub App polling config. The private key path stays local and should be chmod 600.regente github app status [--json]Inspect whether local GitHub App polling is configured.regente github sync --repo owner/repo --pr N [--auth app|gh] [--json]Pull PR comments, review comments, changed files, check runs, and failed statuses through GitHub App local polling by default; --auth gh uses the GitHub CLI fallback.regente report daily [--json] [--alerts]Summarize conflicts blocked, handoffs completed, routed PR comments, routed CI failures, active agents, and estimated time saved.Orchestration · advanced
regente go "<goal>" [--yes] [--no-drive] [--json]The interactive one-shot: plan → review → assign → review → drive, with an accept/edit/reject gate at each step. --yes skips the gates (CI); --no-drive stops after assign.regente task create "<title>" [--description <t>] [--paths a,b] [--deps t1,t2]Create a dependency-aware unit of work and declare the files it will touch.regente task claim <taskId> --agent <id> [--priority <n>] [--json]Claim a task as an agent; reserves the task paths through the same claim/fence/queue engine.regente task update <taskId> [--state todo|assigned|in_progress|blocked|in_review|done] [--result "<outcome>"] [--artifacts a,b] [--title <t>] [--paths a,b] [--deps t1,t2]Update task state/fields. Record the outcome on the task itself with --result (findings/summary, up to 8192 chars) and --artifacts (paths/URLs). Marking done releases its reserved files.regente task list [--state <state>] [--assignee <id>] [--json]List tasks, optionally filtered.regente plan "<goal>" [--agent <id>] [--json]Decompose a goal into tasks with an LLM. BYO key — see Orchestration.regente assign [taskIds…] [--no-reserve] [--json]Route ready tasks to lane owners and pre-reserve their files. No LLM.regente drive [--no-assign] [--replan "<goal>"] [--json]Pump the pipeline: unblock, assign, and surface a re-plan suggestion. No LLM unless --replan.Planner key
regente llm-key [status|show] [--json]Show whether the planner key is set, masked, and which provider/model will be used.regente llm-key set [--provider openai|anthropic|gemini] [--model <m>] [--base-url <url>] [--key <k>] [--json]Save a planner key to ~/.regente/llm.env (chmod 600), or prompt for it hidden in a TTY.regente llm-key clear [--json]Remove the saved planner key. Environment variables still win if present.Open the dashboard
The web command center isn't a regente subcommand — it's the desktop app, or the local
daemon for development:
regented # start the local server, then open the printed URL
# (default http://127.0.0.1:8787; --host / --port to change)The dashboard binds to loopback only and serves authenticated local actions plus real state — agents, claims, the collision band, the auto-handoff queue, and repo activity.