Skip to content

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:

Terminal
excellent install-agent-mcps

It 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.

AgentFile it writesEntry
Amazon Q Developer CLI~/.aws/amazonq/mcp.jsonmcpServers
Amp~/.config/amp/settings.jsonamp.mcpServers
Antigravity CLI~/.gemini/config/mcp_config.jsonmcpServers
Auggie CLI~/.augment/settings.jsonmcpServers
Claude Code~/.claude.jsonmcpServers
Cline CLI~/.cline/data/settings/cline_mcp_settings.jsonmcpServers
Codebuff~/.agents/mcp.jsonmcpServers
Codex~/.codex/config.toml[mcp_servers.excellent]
Crush~/.config/crush/crush.jsonmcp
Cursor Agent~/.cursor/mcp.jsonmcpServers
Devin CLI~/.config/devin/mcp_config.jsonmcpServers
Factory Droid~/.factory/mcp.jsonmcpServers
Gemini CLI~/.gemini/settings.jsonmcpServers
GitHub Copilot CLI~/.copilot/mcp-config.jsonmcpServers
GitLab Duo CLI~/.gitlab/duo/mcp.jsonmcpServers
goose~/.config/goose/config.yamlextensions
Grok Build~/.grok/config.toml[mcp_servers.excellent]
Hermes Agent~/.hermes/config.yamlmcp_servers
Junie CLI~/.junie/mcp/mcp.jsonmcpServers
Kilo Code CLI~/.config/kilo/kilo.jsonmcp, a local server
Kimi Code CLI~/.kimi-code/mcp.jsonmcpServers
Kiro CLI~/.kiro/settings/mcp.jsonmcpServers
Open Interpreter~/.openinterpreter/config.toml[mcp_servers.excellent]
OpenClawOpenClaw's own registry, through openclaw mcpopenclaw mcp set
OpenCode~/.config/opencode/opencode.jsonmcp, a local server
Qwen Code~/.qwen/settings.jsonmcpServers
Rovo Dev CLI~/.rovodev/mcp_config.jsonmcpServers, with transport
Windsurf Cascade~/.codeium/windsurf/mcp_config.jsonmcpServers

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:

AgentWhy not
Zed AgentZed'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 VibeThe same: its MCP schema does not establish the working directory.
OpenHands CLIThe same: there is no reviewed way to persist the server's working directory.
AiderIt has no native MCP client.
Continue CLIIt takes MCP servers from its own platform config, not a local file.
Grok BotIt is a desktop control surface. The work runs on Grok Bot's cloud computer.
Jules ToolsThe work runs in a cloud VM, not on your machine.
mini-SWE-agentNo native MCP client is documented.
Pi AgentIt ships no native MCP client, on purpose.
PlandexNo persistent MCP config is documented.
Roo Code CLIIts MCP settings are per editor profile or per project, so there is no single file to write.
Sourcegraph Cody CLINo persistent MCP config is documented.
SWE-agentIt uses its own tool bundles rather than a persistent MCP config.
Trae AgentIts MCP map lives in a project YAML you choose, so there is no single file to write.
Warp OzIt 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:

JSON
{
  "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:

JSON
{
  "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:

JSON
{
  "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:

JSON
{
  "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:

JSON
{
  "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

TOML
[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

YAML
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:

YAML
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: 300

OpenClaw

OpenClaw owns its config file, so Excellent does not edit it. It registers through OpenClaw's own command instead:

Terminal
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:

  1. Find your agent in the table above and open its file. Create it if it does not exist.
  2. 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 set command instead.
  3. Replace the two placeholder paths with the output of node -p process.execPath and echo "$(npm root -g)/@excellent-so/cli/dist".
  4. 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_dispatch
  • universal_verification_status, universal_verification_open_attempt, universal_verification_submit_attempt, universal_verification_propose_amendment, universal_verification_request_review, universal_verification_trust_root
  • session_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:

Terminal
excellent chat --cli cursor

That 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:

Terminal
openclaw mcp unset excellent

Excellent 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.

  • MCP: connecting anything else that speaks MCP.
  • Quickstart: the whole path, end to end.
  • CLI reference: every command and environment variable.

Was this page helpful?

Start here

  • StartWhat Excellent does
  • StartInstall
  • StartQuickstart
  • StartConnect an agent
  • StartRun the first task
  • StartRead a result