quorum

Orchestrate long-running coding tasks with the coding agent you already use — cross-harness, local-first, policy-owned, and supervised by the same harness that does the work. Point quorum at your repos, queue tasks in plain English, and let your coding agent CLI — claude, codex, opencode, anything that takes a prompt — do the work in isolated git worktrees. The supervisor is an agent too: quorum's manager periodically hands your harness a digest of everything happening (every task's status, output, and liveness, plus its own past actions and their outcomes) and lets it decide — launch, nudge, relaunch, spin up follow-up work, or escalate to you. Supervision policy is a prompt you can edit, not code. One process, no root, no cron, no database; everything is a plain file you can cat.

quorum task add my-api "add rate limiting to the public endpoints, then open a PR"
        │
┌─ quorum up ─────────────────────────────────────────────────────┐
│  manager    your harness, reading the whole situation and       │
│             acting: launch, nudge, relaunch, task add,          │
│             escalate — every action journaled and auditable     │
│                                                                 │
│  task runs  your harness (claude/codex/opencode/...) working    │
│             in worktrees/<task>/, reporting progress back       │
│             through `quorum task report` and reading guidance   │
│             from `quorum task inbox`                            │
└──────────────────── all state in ~/.quorum ─────────────────────┘
        ▲                    ▲                    ▲
   quorum status        quorum tui           quorum web
   quorum manager tell  (steer with `n`)     (localhost only)

Install

Needs Python 3.11+.

uv tool install quorum-orchestrator              # includes the TUI dashboard
uv tool install "quorum-orchestrator[web]"       # + the localhost web dashboard
uvx --from quorum-orchestrator quorum --help     # zero-install trial run

(or pip install "quorum-orchestrator[web]" if you don't use uv.)

The PyPI distribution is quorum-orchestrator; the command it installs is plain quorum (and the import name is quorum too).

From a checkout: uv sync --all-extras, then prefix commands with uv run.

Five minutes to a running task

quorum init                             # scaffold ~/.quorum

Tell quorum how to invoke your harness: the scaffolded ~/.quorum/config.toml ships ready-to-uncomment blocks for claude, codex, and opencode, plus a template for any custom agentic binary — uncomment one and set default_harness. (Runs are unattended, so the harness needs permission to act without asking; the shipped blocks use a scoped tool allowlist, not a blanket bypass.)

quorum doctor checks that config against reality — the binary on PATH, the argv template, git, projects, the state left behind by earlier runs — one line per check, ✓ / ✗ / –, and a non-zero exit if anything is ✗. Add --smoke and it runs your harness once for real to prove it answers.

Register a repo and queue work:

quorum doctor                           # verify the setup end to end
quorum project add ~/work/my-api
quorum task add my-api "fix the flaky auth tests and open a PR"
quorum up --detach                      # supervisor in the background (`quorum down` stops it)

(quorum up without --detach runs it in the foreground — Ctrl-C stops.) Then:

quorum status                # supervisor, agents, tasks, deadlines
quorum task tail a3f2k9 -f   # live harness transcript
quorum task nudge a3f2k9 "prefer the retry approach over sleeps"
quorum manager tell "the api task is urgent; park everything else"
quorum manager journal       # what the manager did, and why
quorum tui                   # dashboard; select a task, press n to steer
                             # (m tells the manager, s runs, c cancels)
quorum web                   # http://127.0.0.1:8787

What it looks like

What's genuinely different

Plenty of tools run coding agents in parallel. Two things here had no equivalent in a 2026-08 survey of ~30 orchestration projects (agent frameworks, coding-agent orchestrators, harness-native orchestration, and the research literature). That's a snapshot of a landscape that moves monthly, not a permanent claim — if you know of prior art, open an issue and this section gets corrected.

• Your live session becomes a supervised task. quorum task adopt inverts the usual ownership: instead of quorum spawning an agent, the interactive session you are already sitting in is recorded as a task the supervisor can watch and guide (mechanics in Adopt a live session below). The closest neighbor surveyed (Omnara) relays a session to your phone so you can steer it; none of the surveyed tools hand the session to a supervisor.
• The supervisor is the same harness, reading a file digest. Among the open-source tools surveyed, "supervision" meant keystroke automation — daemons pressing enter, blind auto-confirmation. An actual LLM supervisor showed up only in hosted commercial products (Factory's Mission Control, Devin's coordinator), where the inputs and the decisions stay in someone else's cloud. Quorum runs that pattern on your disk, and every input and decision is a file you can open: the task records and transcripts the digest is computed from, the policy that interprets it (~/.quorum/prompts/manager.md), and the journal of what it did and why (quorum manager journal). → The manager, design notes.

Why run an external orchestration layer at all, when (as of that same 2026-08 survey) every major harness ships native subagents and vendor-cloud background runs? Because the same wave made sessions externally addressable — hooks, streaming protocols, control-plane APIs — and an outside layer can still own what a single vendor's cloud cannot: one queue over every harness, on your own disk, under a supervision policy you edit. No daemonization framework, no database, and no open ports beyond the opt-in localhost-only dashboard. The survey's ranked implications became the project roadmap: issue #23.

Adopt a live session

The work is already underway in an interactive session? Don't re-queue it — adopt it:

quorum integration install codex     # once per harness (also: opencode, claude-code)
quorum task adopt "refactoring the auth flow"    # from the session's directory

The session becomes an attached task: the manager observes it (liveness, git state, reports) but never runs it — your nudges and the manager's pokes are delivered inside the live session by the harness's hook the next time it stops. quorum task detach hands it back to the headless runner. See docs/guide.md#adopting-a-live-session and the per-harness adapters under integrations/.

How it works

• A task is a sequence of harness runs. Each run executes in the task's own git worktree (~/.quorum/worktrees/<id>), so parallel tasks on one repo never collide and your checkout stays clean. Session ids are captured from the harness's output so follow-up runs can --resume.
• Status is the harness's own words. The run prompt teaches a simple protocol — report progress with quorum task report, check guidance with quorum task inbox — and the conventional flow is planning → executing → reviewing → pr → done. Quorum records what the harness says; it never enforces a state machine.
• The manager is an agent, not a ruleset. Each cycle it compiles a situation digest — including its own recent actions and whether they changed anything — and your harness decides what to do, with real authority: task run, task nudge, task add, task cancel, escalate. Every action is auto-journaled (quorum manager journal); the journal feeds back into the next digest so the manager never loops on an intervention that isn't working. Steer it with quorum manager tell.
• Guidance is a message, not a keystroke. Your nudges and the manager's pokes travel the same file-based inbox; the next run starts with them in its prompt, and a cooperative harness picks them up mid-run.
• Failure is loud and recovery is automatic. If your LLM service goes down, every harness-driven tick fails visibly — and keeps being scheduled, so the first tick after service returns reads the world from files and relaunches whatever died. No degraded fallback mode to babysit.
• All state is files under QUORUM_HOME (default ~/.quorum): task records, transcripts, a message board, inboxes — written with atomic tmp+rename. The TUI and web dashboard read those files and work even when the supervisor is down; what they write (a nudge, a directive, a run, a cancel) is the same call the CLI makes. Copy the directory and your whole setup moves.

Supervision policy is a prompt

~/.quorum/prompts/manager.md is the manager's constitution: how patient it is, when it escalates, how it words its pokes, when creating follow-up work is warranted. House rules go in manager.local.md next to it — an overlay merged into the template at its {local} slot, so your policy rides along while quorum init keeps upgrading the default underneath it. Edit manager.md itself only when you mean to fork the whole thing (an edited template is never upgraded again; quorum prompt diff manager shows what you are missing), and delete it to restore the default. (An optional [llm] section separately gives plugin agents a small-completion client — the manager and tasks run your full harness directly.)

Optional sandbox

Quorum pairs naturally with nono (kernel-enforced sandboxing via Landlock/Seatbelt): wrap the whole thing with nono run --profile quorum -- quorum up, or set [sandbox] use_nono = true to confine each task run to its worktree plus QUORUM_HOME. Fails closed: if sandboxing was requested and nono-py is missing, nothing runs unsandboxed. See docs/guide.md.

Customizing

• Configure harnesses, schedules, and the manager's action budget in config.toml — quorum never rewrites that file.
• Retune the task preamble and the manager's policy with an overlay, ~/.quorum/prompts/<name>.local.md — never seeded, never upgraded, merged into the template's {local} slot. Editing <name>.md itself still works but freezes that file at your version; delete it to restore the default. quorum prompt list shows which is which.
• Add a prompt-driven agent — a prompt, a schedule, your harness, no Python. quorum agent create babysitter --schedule "every 10m" starts the shipped CI babysitter: it watches your tasks' pull requests with gh and relaunches the ones whose checks went red, giving up to you after two tries. That whole policy is ~/.quorum/prompts/babysitter.md — yours to edit.
• Extend with your own agents: drop a ~20-line Python file into ~/.quorum/plugins/ — examples/steward.py is a complete worked example (a rule-based file organizer with undo).

Everything above, in depth: docs/guide.md. Design record: docs/architecture.md.

Development

uv sync --all-extras
uv run pytest
uv run ruff check .

Repo conventions and the layer-by-layer map live in CLAUDE.md.