quorum

Orchestrate long-running coding tasks with the harness you already use — supervised by that same harness. 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.)

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
quorum web                   # http://127.0.0.1:8787

What it looks like

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 are pure readers and work even when the supervisor is down. 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. Edit it to retune your manager; 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 by editing ~/.quorum/prompts/*.md; delete a file to restore the default.
• 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.