One agent on one repo, in five steps

The agent does the work. Excellent starts it, observes it, checks it, and tests changes to the setup before anything is promoted.

curl -fsSL https://excellent.so/install.sh | sh

macOS today. Windows and Linux are not supported yet. Needs Node.js 22.3 or newer. Read the quickstart

Set up once: install, set up the repo and connect your agents

Four commands, once per machine and repository. The installer runs the third for you when your CLI has it.

~/your-repo · zsh

~curl -fsSL https://excellent.so/install.sh | sh

# installs @excellent-so/cli and checks it against SHA256SUMS

~cd your-repo

~/your-repoexcellent init

✓ created AGENTS.md

✓ created .excellent/context.md

✓ created .excellent/cli.toml

Edit these, then run 'excellent' here — the chat reads them as context.

~/your-repoexcellent install-agent-mcps

# writes an excellent entry into each detected agent's config

~/your-repoexcellent doctor

# reports the runtime, the database, providers, your PATH and the keystore

~/your-repo

The excellent init lines are real output, from the quickstart

The CLI on npm today, 0.1.0 (checked October 27, 2026), predates install-agent-mcps, run and verify. The installer skips the agent step and says so; the agents page has every entry to add by hand.

Run the agent through Excellent

Excellent starts the agent in an isolated worktree and records the exact agent version, model, instructions, tools, repo state, and task.

~/your-repo · zsh

~/your-repoexcellent run --agent <role> --task <task-id>

~/your-repo

Both flags are required. --agent is the role name; --task is an existing numeric task id.
A free-text objective is refused with a hint: file it as a task first.
Every run prints a correlationId on stderr.
Exit codes: 0 completed · 1 not completed · 2 usage or goal refusal.

~/your-repo · zsh

~curl -fsSL https://excellent.so/install.sh | sh

# installs @excellent-so/cli and checks it against SHA256SUMS

~cd your-repo

~/your-repoexcellent init

✓ created AGENTS.md

✓ created .excellent/context.md

✓ created .excellent/cli.toml

Edit these, then run 'excellent' here — the chat reads them as context.

~/your-repoexcellent install-agent-mcps

# writes an excellent entry into each detected agent's config; restart the agent

~/your-repoexcellent run --agent <role> --task <task-id>

# attempt 1 is recorded; the checks run

check-verification-product-fixtures PASS

check-verification-canonical-client-coverage PASS

test-checker-gate-decision: FAIL — 58/59 checks, 35/36 mutants caught

# returned to the agent with the unmet check

# the agent works on it and submits again; attempt 2 links back to attempt 1

check-verification-product-fixtures PASS

check-verification-canonical-client-coverage PASS

test-checker-gate-decision: PASS — 215/215 checks, 105/105 mutants caught

# receipt written, kept on this machine

~/your-repo

ReceiptVerified

Task `<task-id>`

agent <role> 10 of 10 steps

Every check passed, so the attempt is verified. Each accepted result leaves a receipt you can open later, cite during review, or use to compare agent setups.

Installchecked against the published SHA256SUMS
01
Set up the repositoryAGENTS.md and .excellent/
02
Connect your agentsone excellent entry in each agent’s config
03
Attempt 1in an isolated worktree, then frozen and checked
04
Returnedexpected 59 of 59 checks, observed 58 of 59
05
Attempt 2links back to attempt 1, which is never rewritten
06
Verifiedreceipt written, kept on this machine
07

Checks, this attempt

check-verification-product-fixturesPass
check-verification-canonical-client-coveragePass
test-checker-gate-decision215/215

Commands from the docs. The check lines are verbatim from our own logs, 24 September to 4 October 2026: the gate that failed on 3 October passed on 4 October.

With the terminal focused: space plays or pauses · R replays · End skips

The same run carries on through steps 2 and 3: the checks, a return and a second attempt.

Run the first task Work and attempts Agents and versions

Check what happened

Done is a claim. Excellent freezes the resulting tree and gathers evidence from the repo and tools connected to the task.

~/your-repo · zsh

~/your-repoexcellent verify <work-id>

~/your-repo

A work id starts a verification; a ver_ id reads one that exists.

Evidence it gathers

Git tree and commit
Test runner
Type checker
Browser test
Build
CI
API
Database
Deployment

Git and test evidence are the most settled. Browser, CI and deployment observers are newer. When a check cannot run, Excellent says so instead of implying a pass.

How a check decides

Return what is still wrong

A returned attempt includes the unmet check, the observed result, the expected result, the supporting evidence, and the next action.

~/your-repo · zsh

~/your-repoexcellent verify <work-id> --json

~/your-repo

From inside an agent, the same read is the universal_verification_status tool.

Result states

VerifiedReturnedNeeds a decisionNot checked

Receipt · attempt 1Returned

invoices-csv-export

Claude Code 1 of 6 checks failed

Attempt startedin an isolated worktree
01
Evidence gatheredresulting tree frozen
02
Checked6 checks
03
ReturnedThe export ignored the active invoice filter. Expected 12 rows, found 47.
04

Sent back to the agent with this evidence.

Receipt · attempt 2Verified

invoices-csv-export

Claude Code 6 checks · second attempt

Attempt startedafter the return
01
Evidence gatheredresulting tree frozen
02
Checked6 checks
03
VerifiedSecond attempt passed all six checks, including the browser check on the filtered view.
04

A result shows what was requested, what the agent changed, what it claimed, what Excellent checked, what passed, what failed, and what could not be checked.

Read a result Checks and results

Compare better ways of running the agent

Once Excellent has enough representative work, it establishes a baseline and tests candidate setups against work the candidate system did not see.

What a candidate can change

01Instructions
02Model selection
03Tool descriptions
04Context selection
05Planning
06Check timing
07Retry behavior
08Stopping rules

If a candidate sees the held-out tasks or lacks required evidence, it is invalid.

We have not published a verified improvement yet.

Experiments and candidates

Promote only what holds up

A candidate moves through historical comparison, held-out tasks, shadow, canary, promotion, and ongoing observation. A higher average score is not enough.

The promotion path, in order

01Historical comparison
02Held-out tasks
03Shadow
04Canary
05Promotion
06Ongoing observation

Promotion shows the exact diff before anything changes. If regressions appear, roll back from the promotion receipt; the rollback is a new record.

Promotion and rollback

The agent does not grade itself

The producing agent's words are useful context. They are not independent proof.

The strongest checks come from systems that can directly observe the requested result: the repo, test runner, browser, CI, API, database, or deployment.

Only a check that ran, or a person, can carry a pass.

How checks decide

How we talk about this

Held-out: Work a candidate setup never saw while it was being tuned, so its score can't be memorized.
Read the definition
Candidate: An alternate agent setup (prompt, model, tools, or rules) compared against the current one.
Read the definition
Promotion: Making a candidate the new default, only after it holds up on evidence it didn't see.
Read the definition
Verified / Returned / Needs a decision / Not checked: The four result states every check lands in.
Read the definition

Run the first task

Copy the install command, run it in a repository you already use, and hand your agent its first task. The quickstart walks through it.

curl -fsSL https://excellent.so/install.sh | sh

Read the quickstart

Task <task-id>

invoices-csv-export

invoices-csv-export

Run the first task

Task `<task-id>`