Operating Excellent

Running headless

Operate your whole workspace from a terminal — run agent roles as workers, drain the review queue, and drive work to done without opening the app.

Everything Excellent does in the UI is available from the command line through excellent-mcp. That's how you operate a workspace from your editor, on a server, or without ever opening the window.

Get the command line

excellent-mcp ships with the Excellent source. Once you've set it up from source, wire it into your terminal:

excellent-mcp install-skills

This installs a launcher at ~/.local/bin/excellent-mcp, registers Excellent's MCP server with Claude Code and Codex, and adds the Excellent skills. Then check who you are and what you're holding:

excellent-mcp agent id          # your stable agent identity
excellent-mcp agent claimed     # tasks you're holding
excellent-mcp agent ship-check  # are you clear to ship?

Run an agent role

Spawn any role as a worker that claims matching work and runs it under a budget:

excellent-mcp agent run shipper             # ship the next todo
excellent-mcp agent run verifier            # verify the review queue
excellent-mcp agent run shipper --goal 42   # scope to one goal
excellent-mcp agent run verifier --loop 5m  # keep running, every 5 min

The roles are shipper, verifier, triager, scribe, and planner. Each headless worker is a claude -p (or codex exec) session, only one worker per role runs at a time, and every role is capped by a wall-clock budget.

Drive the review queue

excellent-mcp review queue                          # what's awaiting me
excellent-mcp review approve 42 --note "verified"   # mark #42 done
excellent-mcp review reject 42 --note "test fails"  # bounce it back

Because of the ship/verify gate, you can only approve work you didn't ship — so a headless verifier is a genuine second party, not a rubber stamp.

Drive everything to done

One command alternates a verifier pass and a shipper pass, cycle after cycle, until the queue is clean (or it stalls):

excellent-mcp agent converge

Standing goals

excellent-mcp goal new "Keep the review queue empty" --role verifier
excellent-mcp goal list
excellent-mcp goal reconcile --apply   # close goals whose work is all done

Point it at a different workspace

~/.excellent/data.db is the default. Set EXCELLENT_DATA_DIR to operate a different (or disposable) database, and EXCELLENT_HOME if you're running the CLI from outside the source checkout. See Settings & configuration for the full list.

Scaling up

For running many agents at once, Excellent has a manager/orchestrator layer (agent manage, agent orchestrate) that fans work across isolated worktrees and merges verified branches — with the final promotion to your main line held for a human. To let any of this run on a schedule instead of on demand, see Autopilot.

← Back to docs