Rehearsal agent plugin

The Rehearsal plugin for AI coding agents. It installs two things:

The Rehearsal skill (skills/rehearsal/): how to build a practice world, run an evaluation, read why episodes failed, and improve an agent, and to ask before anything that spends the workspace's allowance.
The Rehearsal MCP server: 18 tools (add applications, build worlds, run evaluations, explain episodes, improve agents, act as a bring-your-own agent). It runs on your machine from PyPI: uvx --from "rehearsal-kit[mcp]" rehearsal mcp. You need uv.

The plugin follows the Agent Plugins 1.0.0 layout: plugin.json, skills/, mcp.json. The client-specific files next to them are generated by scripts/build_agent_plugin.py; do not edit them by hand.

Sign in once

Every client below uses the same sign-in. Create an API key with Build and evaluate access on the console's API keys page, then run:

uvx --from rehearsal-kit rehearsal login

It asks for the server URL and the key, checks them, and saves them for your user only (~/.config/rehearsal/config.json, mode 600). The MCP server, the CLI and the Python SDK all read it. REHEARSAL_URL and REHEARSAL_API_KEY in the environment take precedence. Without a saved key the MCP server still starts, and its tools tell the assistant to ask you to sign in.

Install

Clients with a plugin system

Client	Install
Claude Code	`claude plugin marketplace add MitudruDutta/rehearsal` then `claude plugin install rehearsal@rehearsal`. Optional: set the server URL and key in `/config` instead of `rehearsal login`
Codex CLI	`codex plugin marketplace add MitudruDutta/rehearsal` then `codex plugin add rehearsal@rehearsal`
GitHub Copilot CLI	`copilot plugin marketplace add MitudruDutta/rehearsal` then `copilot plugin install rehearsal@rehearsal`
Factory Droid	`droid plugin marketplace add MitudruDutta/rehearsal` then `droid plugin install rehearsal@rehearsal`
Augment (Auggie)	`auggie plugin marketplace add MitudruDutta/rehearsal` then `auggie plugin install rehearsal@rehearsal`
Grok Build	`grok plugin marketplace add MitudruDutta/rehearsal` then `grok plugin install rehearsal --trust`
Cursor	Clone the repository and link the plugin folder: `git clone --depth 1 https://github.com/MitudruDutta/rehearsal ~/.rehearsal-src && ln -s ~/.rehearsal-src/agent-plugin ~/.cursor/plugins/local/rehearsal`, then restart Cursor
Antigravity CLI (`agy`, formerly Gemini CLI)	`git clone --depth 1 https://github.com/MitudruDutta/rehearsal ~/.rehearsal-src && agy plugin install ~/.rehearsal-src/agent-plugin/providers/antigravity`. Antigravity's own manifest format cannot share a folder with the Agent Plugins manifest, so it has a separate bundle. To update, `git pull` and install again
Hermes Agent, OpenClaw, OpenHands, NanoClaw	These load Agent Plugins folders natively: point the client at `agent-plugin/` in a clone of the repository

Hermes Agent, OpenClaw, Goose and Qwen Code load a plugin from the root of a repository. python scripts/build_agent_plugin.py --export DIR writes that standalone layout, ready to publish as its own repository.

Clients without a plugin system: the skill and the MCP server

Install the skill into the client's skills folder (any client that reads Agent Skills SKILL.md folders):

uvx --from rehearsal-kit rehearsal skill install --dir <skills folder>

Add the MCP server. Most clients accept this stdio entry in their MCP settings (Claude Desktop, Windsurf, Cline, Roo Code, Kiro, Cursor):

{
  "mcpServers": {
    "rehearsal": {
      "command": "uvx",
      "args": ["--from", "rehearsal-kit[mcp]>=0.1.1", "rehearsal", "mcp"]
    }
  }
}

Client	MCP server
Antigravity CLI	`~/.gemini/config/mcp_config.json` (or `.agents/mcp_config.json` in a project): `{"mcpServers": {"rehearsal": {"command": "uvx", "args": ["--from", "rehearsal-kit[mcp]>=0.1.1", "rehearsal", "mcp"]}}}`
VS Code (Copilot agent mode)	`.vscode/mcp.json`: `{"servers": {"rehearsal": {"type": "stdio", "command": "uvx", "args": ["--from", "rehearsal-kit[mcp]>=0.1.1", "rehearsal", "mcp"]}}}`
Hermes Agent	`hermes mcp add`, or `~/.hermes/config.yaml` under `mcp_servers:` with `command: uvx` and the `args` above
OpenClaw	`openclaw mcp add`, or the `mcp` section of `openclaw.json`; add the skill folder with `skills.load.extraDirs`
Goose	`goose configure` → Add extension → Command-line extension: `uvx --from rehearsal-kit[mcp]>=0.1.1 rehearsal mcp`
Zed	`settings.json` → `context_servers` with the same command and arguments

Check each client's own documentation for the exact place; the command and arguments are the same everywhere.

Assistants with shell access but no MCP

The skill alone is enough: it falls back to the CLI. Install the skill, then pip install rehearsal-kit (or use uvx --from rehearsal-kit rehearsal ...) and rehearsal login.

What the assistant may do

Every call uses your API key and only what its access allows. Keys with Build and evaluate access can add applications, build worlds, run evaluations and read results; they cannot manage keys or billing.
The skill tells the assistant to state the cost and ask before build_world, run_evaluation, improve_agent and recheck_world. Your plan's limits and monthly model-spend cap still apply to every request.
Revoke the key on the API keys page at any time; the assistant loses access at once.

For maintainers

python scripts/build_agent_plugin.py           # regenerate after editing plugin.json, mcp.json, overlays/ or the skill
python scripts/build_agent_plugin.py --check   # CI: fails when generated files are stale
claude plugin validate ./agent-plugin          # Claude Code's own manifest check

The plugin's version must equal the package version in pyproject.toml; the release workflow refuses a release otherwise.