Claude Code, Cursor and other agents
How Excellent attaches to the agent you already use: the file and the exact MCP entry the installer writes for each of the 28 agents it supports, and how to undo it.
On this page
Excellent does not replace your agent and does not ship a model. It attaches to the agent you already run, as an MCP server, and checks what that agent produces.
What the installer does to your machine
Warning
If you installed 0.1.0 from npm. @excellent-so/cli 0.1.0, the release npm
serves (checked October 23, 2026), predates install-agent-mcps. The installer
skips this step and says so, and no agent config is changed. You can register that
release's server by hand: find your agent in the table below
and follow Adding the entry by hand. That release does not
have the verification tools this page lists: with no profile set it advertises 234
tools, and none of the fourteen named under Claude Code is among them. The rest of
this page describes the next CLI release.
When you install Excellent, it runs install-agent-mcps. That command finds every
agent on your machine that it knows how to configure, and writes an excellent server
entry into each one's own config file. Not just the agent you were using at the time.
If it finds none, each excellent command you run checks again until one setup succeeds.
Worth knowing before you run it: it knows 28 agents, so it may touch up to 27 vendor
config files, plus OpenClaw's own registry through OpenClaw's command line. It adds one
excellent entry and leaves the rest of each file's content alone. Every write goes to
a temporary file that is then renamed into place. It refuses a config it cannot parse,
and a TOML or YAML config whose excellent entry is ambiguous. JSON files are written
back with two-space indentation; OpenCode and Kilo Code keep the comments in their JSONC.
You can run it again safely: once an entry matches this install, it is left as it is.
To do it yourself later, or after installing through npm:
excellent install-agent-mcpsIt prints one line for each agent it configured, naming the file it wrote, and asks you
to restart those agents. Agents it cannot configure get no line; they are listed
below. Add --json for the full report.
Every agent and its file
Names are as the installer prints them. Paths are for macOS, the one platform Excellent supports today.
| Agent | File it writes | Entry |
|---|---|---|
| Amazon Q Developer CLI | ~/.aws/amazonq/mcp.json | mcpServers |
| Amp | ~/.config/amp/settings.json | amp.mcpServers |
| Antigravity CLI | ~/.gemini/config/mcp_config.json | mcpServers |
| Auggie CLI | ~/.augment/settings.json | mcpServers |
| Claude Code | ~/.claude.json | mcpServers |
| Cline CLI | ~/.cline/data/settings/cline_mcp_settings.json | mcpServers |
| Codebuff | ~/.agents/mcp.json | mcpServers |
| Codex | ~/.codex/config.toml | [mcp_servers.excellent] |
| Crush | ~/.config/crush/crush.json | mcp |
| Cursor Agent | ~/.cursor/mcp.json | mcpServers |
| Devin CLI | ~/.config/devin/mcp_config.json | mcpServers |
| Factory Droid | ~/.factory/mcp.json | mcpServers |
| Gemini CLI | ~/.gemini/settings.json | mcpServers |
| GitHub Copilot CLI | ~/.copilot/mcp-config.json | mcpServers |
| GitLab Duo CLI | ~/.gitlab/duo/mcp.json | mcpServers |
| goose | ~/.config/goose/config.yaml | extensions |
| Grok Build | ~/.grok/config.toml | [mcp_servers.excellent] |
| Hermes Agent | ~/.hermes/config.yaml | mcp_servers |
| Junie CLI | ~/.junie/mcp/mcp.json | mcpServers |
| Kilo Code CLI | ~/.config/kilo/kilo.json | mcp, a local server |
| Kimi Code CLI | ~/.kimi-code/mcp.json | mcpServers |
| Kiro CLI | ~/.kiro/settings/mcp.json | mcpServers |
| Open Interpreter | ~/.openinterpreter/config.toml | [mcp_servers.excellent] |
| OpenClaw | OpenClaw's own registry, through openclaw mcp | openclaw mcp set |
| OpenCode | ~/.config/opencode/opencode.json | mcp, a local server |
| Qwen Code | ~/.qwen/settings.json | mcpServers |
| Rovo Dev CLI | ~/.rovodev/mcp_config.json | mcpServers, with transport |
| Windsurf Cascade | ~/.codeium/windsurf/mcp_config.json | mcpServers |
Some agents move their config with an environment variable, and Excellent follows it:
GROK_HOME (Grok Build), HERMES_HOME (Hermes Agent), COPILOT_HOME (GitHub Copilot
CLI), KIMI_CODE_HOME (Kimi Code CLI), CLINE_DATA_DIR (Cline CLI), ROVODEV_HOME
(Rovo Dev CLI), OPENCODE_CONFIG (OpenCode), GLAB_CONFIG_DIR (GitLab Duo CLI), and
OPENCLAW_CONFIG_PATH or OPENCLAW_STATE_DIR (OpenClaw). XDG_CONFIG_HOME moves every
~/.config path above, and GitLab Duo CLI's file to $XDG_CONFIG_HOME/gitlab/duo/mcp.json.
OpenCode uses opencode.jsonc when that is the only one of the two files that exists.
Rovo Dev CLI uses the mcpConfigPath set in ~/.rovodev/config.yml, and otherwise
falls back to an existing legacy mcp.json.
Agents it detects but does not configure
Excellent recognizes these agents but writes no config for them:
| Agent | Why not |
|---|---|
| Zed Agent | Zed's documented MCP server settings do not establish which working directory the server runs in, so Excellent will not create an entry it cannot verify as portable. |
| Mistral Vibe | The same: its MCP schema does not establish the working directory. |
| OpenHands CLI | The same: there is no reviewed way to persist the server's working directory. |
| Aider | It has no native MCP client. |
| Continue CLI | It takes MCP servers from its own platform config, not a local file. |
| Grok Bot | It is a desktop control surface. The work runs on Grok Bot's cloud computer. |
| Jules Tools | The work runs in a cloud VM, not on your machine. |
| mini-SWE-agent | No native MCP client is documented. |
| Pi Agent | It ships no native MCP client, on purpose. |
| Plandex | No persistent MCP config is documented. |
| Roo Code CLI | Its MCP settings are per editor profile or per project, so there is no single file to write. |
| Sourcegraph Cody CLI | No persistent MCP config is documented. |
| SWE-agent | It uses its own tool bundles rather than a persistent MCP config. |
| Trae Agent | Its MCP map lives in a project YAML you choose, so there is no single file to write. |
| Warp Oz | It takes MCP servers per run (--mcp) or from Warp's cloud, with no local file. |
The entry it writes
Two paths appear in every entry. /absolute/path/to/node is the Node.js that ran the
installer; node -p process.execPath prints it. /absolute/path/to/@excellent-so/cli/dist
is the installed package's dist folder, which holds server.js;
echo "$(npm root -g)/@excellent-so/cli/dist" prints it. An npm or curl | sh install
writes no environment variables.
The standard mcpServers entry
Claude Code, Cursor Agent, Gemini CLI, GitHub Copilot CLI, Windsurf Cascade, Amazon Q Developer CLI, Antigravity CLI, Auggie CLI, Cline CLI, Codebuff, Devin CLI, Factory Droid, GitLab Duo CLI, Junie CLI, Kimi Code CLI, Kiro CLI and Qwen Code all get the same stdio block:
{
"mcpServers": {
"excellent": {
"type": "stdio",
"command": "/absolute/path/to/node",
"args": ["/absolute/path/to/@excellent-so/cli/dist/server.js"],
"cwd": "/absolute/path/to/@excellent-so/cli/dist",
"env": {}
}
}
}Other JSON entries
Rovo Dev CLI
The same block, but Rovo Dev names stdio with transport instead of type:
{
"mcpServers": {
"excellent": {
"transport": "stdio",
"command": "/absolute/path/to/node",
"args": ["/absolute/path/to/@excellent-so/cli/dist/server.js"],
"cwd": "/absolute/path/to/@excellent-so/cli/dist",
"env": {}
}
}
}Amp
Amp's map is one key with a dot in its name, amp.mcpServers, and the entry has no type:
{
"amp.mcpServers": {
"excellent": {
"command": "/absolute/path/to/node",
"args": ["/absolute/path/to/@excellent-so/cli/dist/server.js"],
"cwd": "/absolute/path/to/@excellent-so/cli/dist",
"env": {}
}
}
}Crush
Crush keeps its servers under mcp:
{
"mcp": {
"excellent": {
"type": "stdio",
"command": "/absolute/path/to/node",
"args": ["/absolute/path/to/@excellent-so/cli/dist/server.js"],
"cwd": "/absolute/path/to/@excellent-so/cli/dist",
"env": {}
}
}
}OpenCode and Kilo Code CLI
A local server, with Node and the server script together in one command array:
{
"mcp": {
"excellent": {
"type": "local",
"command": [
"/absolute/path/to/node",
"/absolute/path/to/@excellent-so/cli/dist/server.js"
],
"cwd": "/absolute/path/to/@excellent-so/cli/dist",
"environment": {},
"enabled": true
}
}
}If the file already nests its servers under mcp.servers (OpenCode v2), the entry goes
there, with "disabled": false in place of "enabled": true.
TOML: Codex, Grok Build and Open Interpreter
[mcp_servers.excellent]
command = "/absolute/path/to/node"
args = [ "/absolute/path/to/@excellent-so/cli/dist/server.js" ]
cwd = "/absolute/path/to/@excellent-so/cli/dist"
env = {}YAML entries
Hermes Agent
mcp_servers:
excellent:
command: "/absolute/path/to/node"
cwd: "/absolute/path/to/@excellent-so/cli/dist"
args:
- "/absolute/path/to/@excellent-so/cli/dist/server.js"
env: {}goose
goose gets a stdio extension:
extensions:
excellent:
type: "stdio"
name: "Excellent"
enabled: true
cmd: "/absolute/path/to/node"
cwd: "/absolute/path/to/@excellent-so/cli/dist"
args:
- "/absolute/path/to/@excellent-so/cli/dist/server.js"
env_keys: []
envs: {}
timeout: 300OpenClaw
OpenClaw owns its config file, so Excellent does not edit it. It registers through OpenClaw's own command instead:
openclaw mcp set excellent '{"command":"/absolute/path/to/node","args":["/absolute/path/to/@excellent-so/cli/dist/server.js"],"cwd":"/absolute/path/to/@excellent-so/cli/dist","env":{},"transport":"stdio"}'The only environment keys Excellent will ever own or overwrite in an entry are
EXCELLENT_*, INTEGRATIONS_CRON_SECRET and ELECTRON_RUN_AS_NODE. In the JSON entries,
anything else you put in env is preserved when Excellent rewrites the entry. When it
rewrites a TOML, YAML or OpenClaw entry it writes only its own keys, so keep your own
variables out of those.
Restart or reload the agent after installing, or it will not see the new server.
Adding the entry by hand
With 0.1.0, or if you would rather not let the installer write agent configs:
- Find your agent in the table above and open its file. Create it if it does not exist.
- Add the entry for its shape from The entry it writes inside the
map that is already there, next to any other servers. Do not replace the file. For
OpenClaw, run the
openclaw mcp setcommand instead. - Replace the two placeholder paths with the output of
node -p process.execPathandecho "$(npm root -g)/@excellent-so/cli/dist". - Restart the agent.
Excellent does not write an entry for Zed, Mistral Vibe or OpenHands, and does not offer one to copy, for the reason in the table above.
Claude Code
After a restart, Claude Code lists the Excellent tools under the excellent server.
By default it sees 14 tools, not the full registry. The default profile is
product, which is the verification journey and nothing else:
verification_v2_commands,verification_v2_dispatchuniversal_verification_status,universal_verification_open_attempt,universal_verification_submit_attempt,universal_verification_propose_amendment,universal_verification_request_review,universal_verification_trust_rootsession_create,session_attach,session_event,session_evidence_record,session_trajectory,session_claim
Set EXCELLENT_MCP_PROFILE=core or full in the server's env block for a wider
belt. Treat the profile as a menu rather than a fence: the enforced boundary is
EXCELLENT_MCP_ALLOW, which is checked at dispatch. Both are EXCELLENT_* keys, which
Excellent owns, so the next install-agent-mcps finds an entry that differs from the one
it would write and writes it back without them. Set them again after a re-run.
In use, you do not call these yourself. The agent opens an attempt against a Work item, submits its output, and reads the status back. Excellent records the attempt and, separately, a verifier reaches a verdict, which the agent cannot issue for itself. See How verification decides.
Hooks and skills
Note
Only in a monorepo checkout. If you installed with curl | sh or
npm i -g @excellent-so/cli, you get MCP registration and nothing else. No hooks,
no skills. The hook and skill wiring needs an Excellent monorepo root and is skipped
without one.
Inside a checkout, excellent-mcp install-skills additionally writes three Claude Code
hooks into <repo>/.claude/settings.json: SessionStart, Stop, and PreToolUse
matching Bash. There is no PostToolUse hook. It only adds missing entries; your own
hooks are left alone, and an unparseable settings file is refused rather than rewritten.
What they do: the session hook reaps MCP server processes whose host died. The stop
hook reminds you if you still hold in-progress work. The Bash hook is the interesting
one: it blocks a git commit or git push when the agent holds no claim, and blocks
bulk staging (git add -A, git commit -a) in a shared working tree.
It also symlinks the shipped skill packs into ~/.claude/skills/. That mirror is for
Claude Code's UI only; the skill_list and skill_get tools read the repo directly and
do not need it.
Cursor
Cursor gets MCP and only MCP: an excellent entry in ~/.cursor/mcp.json, in
the standard shape. The installer calls it Cursor
Agent. Excellent writes no .cursorrules, no .cursor/rules/*.mdc, no hooks and no
project-scoped config.
Cursor is detected from the cursor-agent binary or from Cursor.app being installed.
The bare agent alias is deliberately not accepted as evidence, since it belongs to
too many things.
Separately, Cursor can be a backend for Excellent's own REPL:
excellent chat --cli cursorThat routes each turn through your local cursor-agent using its auth, with no API key.
claude is the first-class backend there. It gets the full belt and resumable
sessions; the others run headless.
Repository context
excellent init writes AGENTS.md and .excellent/context.md into the repository.
The Excellent chat reads AGENTS.md, CLAUDE.md and .excellent/context.md per
directory. Claude Code reads CLAUDE.md and AGENTS.md on its own. Keeping the
repository facts in those files means both tools see the same thing.
Undoing it
To disconnect one agent, delete the excellent entry from its file in
the table above, then restart the agent. For OpenClaw, run:
openclaw mcp unset excellentExcellent does not put a removed entry back by itself. After the first setup that
succeeds, it records that in ~/.excellent/agent-mcp-first-use-v1.json, and from then on
it writes agent configs only when you ask it to, as with install-agent-mcps.
In a source checkout, excellent-mcp uninstall-skills removes Excellent's own symlinks
and the exact excellent entries it added. It never deletes a real directory and never
touches another vendor's entries. In an npm or curl | sh install it does not recognize
the installer's entries as its own and leaves them in place, so remove them by hand as
above.
Related
- MCP: connecting anything else that speaks MCP.
- Quickstart: the whole path, end to end.
- CLI reference: every command and environment variable.