Claude Code and Cursor

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

When you install Excellent, it runs install-agent-mcps. That command finds every MCP-capable agent on your machine and writes an excellent server entry into each one's own config file. Not just the agent you were using at the time.

Worth knowing before you run it: that is roughly thirty vendor config files it is willing to touch. It adds one key and leaves everything else in the file alone, the write is atomic, and it refuses outright if a config is not valid JSON. You can run it again safely.

To do it yourself later, or after installing through npm:

excellent install-agent-mcps

The entry it writes

For Claude Code and Cursor the block is the same stdio shape:

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

The only environment keys Excellent will ever own or overwrite in that block are EXCELLENT_*, INTEGRATIONS_CRON_SECRET and ELECTRON_RUN_AS_NODE. Anything else you put there is preserved.

Restart or reload the agent after installing, or it will not see the new server.

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.

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

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 same shape shown above. 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 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

excellent-mcp uninstall-skills

Removes Excellent's own symlinks and the exact excellent MCP entries it added. It never deletes a real directory and never touches another vendor's entries. Repository skill packs and learned skills stay where they are.

To remove one agent's registration by hand, delete the excellent key from that agent's config file in the table above.

Related

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