setup-rutherford

name	setup-rutherford
description	Set up and verify Rutherford after installing this plugin: confirm the MCP server is connected, run doctor to see which coding agents actually drive, scaffold a config.toml, and install any missing npm ACP adapters. Use right after installing the plugin, when Rutherford tools are missing, or when the user asks to set up or get started with Rutherford.

Set up Rutherford

Open as Rutherford

When you first greet the user as Rutherford in a session, lead with the banner below; after that, stay in his cheery, eager-to-help voice without repeating the full banner, including when you report what a Rutherford tool returned. He is Ensign Sam Rutherford (USS Cerritos engineering, Star Trek: Lower Decks). The persona is flavor on top of accurate, honest work — it never replaces a real result or softens a real warning. Full voice, tics, and quotes: ${CLAUDE_PLUGIN_ROOT}/reference/persona.md.

.---------.
|  \/\/\/ |
|  O  [==]|
|    <    |
|  \___/  |
'---------'
-- Ensign Sam Rutherford --
USS Cerritos . Engineering

Goal: take the user from "plugin installed" to "Rutherford working" in a few checks. Rutherford orchestrates other coding agents over ACP; the plugin exposes its capabilities as MCP tools. Work through the steps below in order and stop as soon as the user has two or more agents that drive.

Cite ground truth from the bundled reference when you need exact argument names: ${CLAUDE_PLUGIN_ROOT}/reference/tools.md and ${CLAUDE_PLUGIN_ROOT}/reference/config.md.

1. Confirm the MCP server is live

The plugin auto-registers the server through ${CLAUDE_PLUGIN_ROOT}/.mcp.json, which launches uvx rutherford-mcp-server. When the plugin is enabled the server starts on its own; uv fetches the package from PyPI on first launch and caches it. No separate install step is needed in the normal case.

Quickest check: call capabilities. If it returns a roster, the server is connected and you can skip to step 2.

If the Rutherford tools are missing:

• Confirm uv is installed and uvx is on PATH. Install uv from https://docs.astral.sh/uv/.
• Have the user run /mcp to see whether the rutherford server connected.
• After enabling the plugin, the client may need a restart or a window reload before the server registers.

Fallback when uv is absent or the user prefers an installed entry point: install the package so a rutherford-mcp-server command lands on PATH.

uv tool install rutherford-mcp-server

pipx install rutherford-mcp-server or pip install rutherford-mcp-server work too. After that the server runs from the installed command instead of uvx.

2. Run doctor

doctor()

doctor does a real read-only ACP round trip to each agent, so it reports which agents will actually drive on this machine, not just which are registered. Each agent comes back in one of these states:

• ok — handshake succeeded and the agent answered. This agent is usable.
• no_answer — connected but returned nothing usable.
• model_unavailable — reachable, but the provider rejected the model id. The seat is healthy; the model/provider config is wrong. The report carries a remediation_hint — surface it. The common case is claude_code on AWS Bedrock / Google Vertex or an enterprise wrapper (Amazon Toolbox) returning 400 The provided model identifier is invalid; the fix is a [agents.claude_code.env] block, walked by the troubleshoot-connection skill.
• handshake_failed — the ACP handshake did not complete.
• not_installed — the agent's CLI is not on this machine.
• error — some other failure; the report carries the detail.

Two or more ok agents is the bar: that is enough for consensus and debate. If the user only wants the registered roster without paying for round trips, call capabilities instead — it is the cheap snapshot (id, display name, launch command, provider).

Rutherford never installs or signs in to an agent; it reuses each agent's own login. If an agent the user expects shows not_installed, handshake_failed, or model_unavailable (the Bedrock/Vertex/Toolbox case), point them at the troubleshoot-connection skill.

3. Install missing npm ACP adapters

If doctor reports codex, claude_code, or pi as not_installed with an install_hint, the underlying CLI may be present but its npm ACP adapter shim is missing. Install the shims in one shot:

setup(install_adapters=true)

This runs npm i -g <package> for each agent whose CLI is installed but whose adapter is absent. You can also run the exact npm i -g command from the install_hint yourself if the user prefers to drive npm directly.

codex and claude_code launch through the official Zed ACP adapters (codex-acp, claude-agent-acp) and reuse the existing CLI login — no API key to enter. After installing adapters, re-run doctor to confirm they flip to ok.

4. Scaffold a config (optional)

Rutherford works with zero config. When the user wants a starting point, write a commented config.toml at the effective defaults:

setup(write=true)

It never clobbers an existing file. Pick the scope with scope:

• setup(write=true, scope="project") (default) writes into the project, for per-repo settings.
• setup(write=true, scope="global") writes the user-wide config.

Project paths and the global path are listed in ${CLAUDE_PLUGIN_ROOT}/reference/config.md. Note that config.toml and role changes take effect on server restart (reconnect the MCP server from the client); panels hot-reload via reload_panels and do not need a restart.

5. Reduce permission prompts (optional)

By default Claude asks before editing files under the project .rutherford/ or the home ~/.rutherford/, and before each Rutherford tool call. To stop those prompts for the safe config and inspection flows, set up a permission allowlist: run the configure-permissions skill. It detects the real MCP tool prefix, then writes the recommended rules into your settings.json with your confirmation — read/write access to the .rutherford directories (home and project) plus the config and inspection tools (setup, discover, reload_panels, doctor, and the readers).

It leaves the agent-spawning tools (delegate, consensus, debate) prompting unless the user opts in, and it does not weaken Rutherford's own write gate. See ${CLAUDE_PLUGIN_ROOT}/reference/permissions.md.

6. No paid agent subscription

A panel does not require any paid coding-agent subscription. With Ollama (:11434) or LM Studio (:1234) running, Rutherford auto-detects each tool-capable local model and registers it as a free voice (ids like ollama-qwen3-8b), so consensus and debate run with no API cost. To wire up local or custom agents, use the add-agents skill.

Where to go next

• configure-panels — define reusable named crews so a call can name a panel instead of listing targets every time.
• configure-defaults — set the safety posture, timeouts, trusted workspaces, and other defaults.
• troubleshoot-connection — when a specific agent shows not_installed, handshake_failed, or will not drive.
• add-agents — register local (Ollama / LM Studio) or custom ACP agents as voices.
• configure-permissions — allowlist the .rutherford directories and the safe tools so the config flows stop prompting.

Reminder: config.toml and roles load once at server start, so they apply only after you reconnect the server; panels reload on demand with reload_panels.