Skip to content

Start

Quickstart

Install Excellent, wire it to your agent, and read your first checked result.

On this page

This page walks from nothing to a checked result. Every block marked real output was copied from an actual terminal. Where a step has no transcript yet, it says so rather than showing you invented output.

1. Install

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

You need macOS and Node.js 22.3 or newer. The script checks the Node version, downloads the release, verifies it against the published SHA256SUMS, and installs @excellent-so/cli globally. If the checksum is missing or does not match, it stops and installs nothing.

2. Confirm the CLI is there

excellent --version

That prints excellent followed by a version number. No transcript here on purpose: excellent --version reports whatever is in the package.json it was installed from, so the number depends on when you installed and any output pasted here would be wrong by the next publish. The current published version is stated once, on /install.

If the command is not found, open a new terminal so your shell picks up ~/.local/bin.

3. Scaffold a repository

Run this inside a repository you already use with your agent.

Real output:

$ cd your-repo
$ excellent init
✓ created AGENTS.md
✓ created .excellent/context.md
✓ created .excellent/cli.toml
 
Edit these, then run 'excellent' here — the chat reads them as context.

AGENTS.md is what your agent reads. .excellent/context.md is the repository context Excellent itself loads. Edit both before your first real task — they are the difference between a useful check and a vague one.

4. Check the local setup

Real output, from a development machine. Absolute paths are shortened to ~, and the line naming the signed-in model account is removed. Your runtime, providers and coding CLIs lines will differ.

This capture is from a monorepo checkout, not an npm install — that is what the runtime companion (monorepo) line means, and it is why the header reads cli 0.0.0. The monorepo carries a placeholder version; the real number is set at publish time. Installed from npm, that header shows the published version instead.

$ excellent doctor
Excellent CLI doctor  (node v24.20.0 · cli 0.0.0)
 
✓ runtime   companion (monorepo) — monorepo checkout at ~/Sites/micro
  home ~/Sites/micro
✓ database  ~/.excellent/data.db (exists)
  0 workspace(s)
✓ providers no HTTP keys set
  local runtimes: ollama, lmstudio, vllm
✓ coding CLIs claude 2.1.280, codex 0.156.1, grok 1.0.34
✓ PATH      ~/.local/bin on PATH
✓ keystore  present, recovery NOT set
✓ telemetry opt-in, off by default; 16 scrubbed event types disclosed
✓ single-writer off — no writer elected
 
✓ ready — run excellent to start chatting.

Anything marked ! is a thing to fix before you rely on a result.

5. Your agent is already wired

The installer registered the Excellent MCP server in every MCP-capable agent it found on your machine — Claude Code, Cursor, Codex and others. You do not need to configure anything by hand. To see exactly which files it wrote and how to undo it, read Claude Code and Cursor.

If you installed the CLI some other way, register it now:

excellent install-agent-mcps

6. Run a task and get it checked

Work in Excellent is a Work item, an attempt against it, and a verification of that attempt. The agent does not get to close its own loop: the verifier must be a different actor in a different execution boundary, which is why the result means something. How verification decides explains the rules.

Two ways in.

Through your agent. This is the normal path. With the MCP server registered, the agent opens an attempt, submits its output, and asks for a status — using the universal_verification_open_attempt, universal_verification_submit_attempt and universal_verification_status tools. You do not type these; the agent calls them.

From the terminal, against an existing task id:

excellent run --agent <role> --task <task-id>

--agent is a role name and --task must be an existing numeric task id. A free-text objective is refused with a structured hint — file it as a task first. Then:

excellent verify <work-id>

Not yet transcribed. We have not published a real end-to-end transcript of step 6 against a fresh repository. The commands and tool names above are read from the shipped CLI, but the output is deliberately omitted rather than invented.

7. Verify the receipt yourself

A verification produces a signed receipt. You can check the repository's sample receipt and public key with the standalone verifier. It needs no database, network, or Excellent installation. Copy the verifier and signed receipt outside the repo; that is the point of the check:

mkdir /tmp/receipt-check && cd /tmp/receipt-check
cp <repo>/scripts/lib/offline-receipt-verifier.mjs .
cp <repo>/docs/v0/release-receipt.json .
cp <repo>/docs/v0/release-receipt-public-key.pem .
node offline-receipt-verifier.mjs release-receipt.json release-receipt-public-key.pem

Replace <repo> with the path to your Excellent checkout. The real output is:

{
  "bound": true,
  "receiptId": "receipt_v0_release_4df3dd89b3e4d0a0",
  "tenantId": "tenant_v0_release",
  "decisionDisclosure": "UNDISCLOSED",
  "claimedKeyId": "v0-ed25519-2026-08",
  "claimedSignatureAlgorithm": "ed25519",
  "signatureAlgorithm": "ed25519",
  "payloadHashMatches": true,
  "signatureValid": true,
  "excellentReachable": false,
  "excellentResolutionError": "ERR_MODULE_NOT_FOUND",
  …
}

The repository also includes a deliberately altered receipt. Copy it into the same directory and run the verifier again:

cp <repo>/docs/v0/adversary/receipt-tamper-fixtures/tampered-receipt.json .
node offline-receipt-verifier.mjs tampered-receipt.json release-receipt-public-key.pem

It demonstrates the negative result shape:

{ "bound": false, "receiptId": null, "tenantId": null, …,
  "claimed": { "receiptId": "receipt_exp_v0_proof_cand_v0_proof", … },
  "claimedKeyId": "v0-ed25519-2026-08",
  "payloadHashMatches": false,
  "signatureValid": false,
  "tamperedSignatureRejected": true,
  "tamperedContentRejected": true }

A tampered receipt can still produce exit 0 because the verifier reached an answer; read bound and the signature/hash fields. See Sample receipt for the complete document and explanation.

Where to go next

Undo it

There is no excellent uninstall command. Remove it by hand:

excellent-mcp uninstall-skills
npm uninstall -g @excellent-so/cli
rm -rf ~/.excellent

The last command deletes every local record Excellent kept. It is irreversible.

← Back to docs