Install Excellent

• macOS. The platform we develop and test on.
• Node.js 22.3 or newer. The installer checks your Node version and refuses to continue below 22.3.0. The published package’s own engines field is looser than that, so npm install -g will not stop you on an older Node — the CLI just needs 22.3.
• Permission to install a global npm package. Excellent installs as @excellent-so/cli with npm install -g. If your global npm prefix needs sudo, fix the prefix rather than running the installer as root.

• Checks your Node version and stops if it is too old.
• Picks an install source: a local monorepo checkout if you are in one, otherwise the published npm package, otherwise the release tarball on our CDN.
• Verifies any downloaded tarball against the SHA256SUMS file published beside it. This fails closed: a mismatch, a missing checksum file, or a missing entry for the artifact aborts the install with a non-zero exit.
• Registers the Excellent MCP server in every MCP-capable coding agent it detects — Claude Code, Cursor, Codex and others — by writing an excellent entry into each one’s own config file. It adds that entry and leaves the rest of the file alone. See Claude Code and Cursor for the exact files and how to undo it.
• Tells you if ~/.local/bin is missing from your PATH.

It is idempotent — re-running it is safe. Add --dry-run to print what it would do and change nothing.

excellent --version

That prints excellent and the version you installed. From npm today that is 0.1.0, checked September 23, 2026. If the command is not found, open a new terminal so your shell picks up ~/.local/bin, then try again.

Next, run excellent doctor, which reports the runtime it resolved, the local database, detected model providers and coding CLIs, your PATH, and the keystore. The quickstart shows its output on a real machine.

Set EXCELLENT_DATA_DIR to move the local database and sessions somewhere else.

excellent-mcp uninstall-skills   # remove the MCP registrations and shims
npm uninstall -g @excellent-so/cli
rm -rf ~/.excellent              # deletes the local database and all local records

The last step is irreversible. Everything Excellent recorded is in that directory.

Windows. There is a PowerShell installer at excellent.so/install.ps1, run with irm https://excellent.so/install.ps1 | iex. It mirrors the shell installer and installs the same package. Windows is not a platform we test on, and it has no CI coverage, so treat it as unsupported for now.

Linux and WSL. The installer is POSIX shell and the CLI is plain Node, so it generally works. It is also untested. If you run Excellent on either, tell us what broke: hello@excellent.so.

A macOS desktop app is in progress. We will not offer a download until there is a signed, notarized build, so today the CLI is the product.

The copied command installs the CLI, moves into your repository and runs excellent init. That scaffolds AGENTS.md and .excellent/ in the repository. The quickstart takes it from there, through a first checked task.

Using AI agents across a team? Email Matt.