Add kitaru setup to wire skills and the MCP server into detected coding agents

CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+### Added
+
+- Added `kitaru setup`, which installs the agent skills from `zenml-io/kitaru-skills` into `~/.agents/skills` (plus `~/.claude/skills` and `~/.codex/skills` when those CLIs are present) and registers `kitaru-mcp` with every detected coding agent: Claude Code and Codex through their own `mcp add` commands, Cursor and Windsurf through their JSON configuration files. Inside a project it launches the server through `uv run --directory <project>` and uses Claude Code's project scope; a tool install points at the absolute `kitaru-mcp` path. Re-running replaces the previous entry, so it is safe to run again after installing a new editor. `--mode` and the global `--server` select the MCP capability mode and target; `--no-skills` and `--no-mcp` skip either half. The one-line installer now runs it instead of carrying its own client detection.
+
 ## [0.25.0] - 2026-09-03
 
 ### Added

README.md

@@ -44,7 +44,7 @@ Kitaru turns that history into something you can test:
 
 ## ⚡ Get started
 
-**1. Install.** Open a terminal in your agent's repository and run one line. It adds Kitaru to that project's environment with `uv` (the worker that replays your agent has to live next to its dependencies), installs the coding-agent skills, and registers the MCP server with Claude Code and Codex. It ends by printing the two ways to get a server: `kitaru login --local` (Docker, free) or `kitaru login` for the managed cloud (14-day trial, no credit card required).
+**1. Install.** Open a terminal in your agent's repository and run one line. It adds Kitaru to that project's environment with `uv` (the worker that replays your agent has to live next to its dependencies), installs the coding-agent skills, and registers the MCP server with Claude Code, Codex, Cursor, and Windsurf (that part is `kitaru setup`, re-run it after installing a new editor). It ends by printing the two ways to get a server: `kitaru login --local` (Docker, free) or `kitaru login` for the managed cloud (14-day trial, no credit card required).
 
 ```bash
 curl -fsSL https://kitaru.ai/install | bash

docs/book/agent-native/setup.md

@@ -13,7 +13,9 @@ Kitaru observes your production agents; your coding assistant is how you talk to
 Skills and MCP work together: the skills say how to work, and the server bounds what can be touched.
 
 {% hint style="success" %}
-Used the [one-line installer](../getting-started/installation.md)? It already installed the MCP server, registered it with Claude Code (in your repo's `.mcp.json` when run inside a repository, user scope otherwise) and Codex, pointed at `http://localhost:8000` in `standard` mode, and installed the skills. Skip to [Capability modes and tools](#capability-modes-and-tools) unless you use another assistant or a different server URL.
+Used the [one-line installer](../getting-started/installation.md)? It ran `kitaru setup`, which installed the skills and registered the MCP server with every coding agent it found: Claude Code (in your repo's `.mcp.json` when run inside a repository, user scope otherwise), Codex, Cursor, and Windsurf, pointed at `http://localhost:8000` in `standard` mode. Skip to [Capability modes and tools](#capability-modes-and-tools) unless you use another assistant or a different server URL.
+
+Installed a new coding agent since, or changed servers? Run `kitaru setup` again (`uv run kitaru setup` inside a project). It replaces the previous `kitaru` entry rather than adding a second one; `--mode read-only` and the global `--server URL` change the mode and target, and `--no-skills` / `--no-mcp` limit it to one half.
 {% endhint %}
 
 ## Install the MCP server

docs/book/getting-started/installation.md

@@ -14,8 +14,8 @@ curl -fsSL https://kitaru.ai/install | bash
 That one command:
 
 1. Adds `kitaru[cli,mcp,worker]` to the project's environment with `uv add`. The worker that replays your agent has to live next to your agent's dependencies, so this is the environment that matters. uv is installed first if you do not have it; no system Python and no `sudo` are needed.
-2. Installs the [agent skills](../agent-native/setup.md) into `~/.agents/skills`, plus `~/.claude/skills` and `~/.codex/skills` when Claude Code or Codex is installed.
-3. Registers the MCP server with Claude Code (in the repo's `.mcp.json`) and Codex, as `uv run --directory <repo> kitaru-mcp`.
+2. Runs `kitaru setup`, which installs the [agent skills](../agent-native/setup.md) into `~/.agents/skills`, plus `~/.claude/skills` and `~/.codex/skills` when Claude Code or Codex is installed.
+3. The same `kitaru setup` registers the MCP server with every coding agent it finds: Claude Code (in the repo's `.mcp.json`), Codex, Cursor (`.cursor/mcp.json` in the repo), and Windsurf, as `uv run --directory <repo> kitaru-mcp`. Anything else gets the JSON to paste.
 4. Prints the two ways to get a server, and stops:
 
 ```
@@ -25,7 +25,7 @@ uv run kitaru login            managed cloud. 14-day trial, no credit card requi
 
 (Inside a project Kitaru is not on your PATH, hence `uv run`. The isolated install uses plain `kitaru`.)
 
-Works on macOS, Linux, WSL, and Git Bash on Windows. Running it again upgrades.
+Works on macOS, Linux, WSL, and Git Bash on Windows. Running it again upgrades. Installed a new coding agent later? Run `uv run kitaru setup` (or `kitaru setup`) and it wires that one up too; `--mode` and the global `--server` pick the MCP capability mode and target server.
 
 {% hint style="info" %}
 **Not in a repository?** Run it anywhere and it installs an isolated `kitaru` CLI on your PATH instead (a `uv tool` environment under `~/.local/share/uv/tools/kitaru`). That is enough to log in, import traces, run evaluators, and serve MCP, but replays need Kitaru inside the agent's own project, so re-run the installer there when you have one. `--project` and `--global` force either mode.
@@ -37,7 +37,7 @@ Works on macOS, Linux, WSL, and Git Bash on Windows. Running it again upgrades.
 | `--with kitaru-pydantic-ai` | Also install a package into the same environment (repeatable) |
 | `--server https://your-team.kitaru.ai` | Point the MCP server at a team server instead of `http://localhost:8000` |
 | `--project` / `--global` | Force the in-project or the isolated install |
-| `--no-skills`, `--no-mcp` | Skip those steps |
+| `--no-skills`, `--no-mcp` | Skip those steps (`kitaru setup` takes the same flags later) |
 | `--no-modify-path` | Leave your shell rc files alone (global mode) |
 
 `curl -fsSL https://kitaru.ai/install | bash -s -- --help` lists everything, with environment-variable equivalents.
@@ -46,13 +46,13 @@ Works on macOS, Linux, WSL, and Git Bash on Windows. Running it again upgrades.
 
 ```bash
 uv add "kitaru[cli,mcp,worker]" kitaru-pydantic-ai    # into this project; pick your adapter
-npx skills add zenml-io/kitaru-skills                  # the coding-agent skills
-uv run kitaru login                             # managed cloud; 14-day trial, no credit card required
-uv run kitaru login --local                     # local server in Docker
-# or: uv run kitaru login <team-url>            # an existing managed or self-hosted workspace
+uv run kitaru setup                                   # skills + MCP server for every coding agent found
+uv run kitaru login                                   # managed cloud; 14-day trial, no credit card required
+uv run kitaru login --local                           # local server in Docker
+# or: uv run kitaru login <team-url>                  # an existing managed or self-hosted workspace
 ```
 
-plus registering `uv run kitaru-mcp --server http://localhost:8000 --mode standard` with your assistant, as described in [Set up your coding agent](../agent-native/setup.md).
+`kitaru setup` is what the installer runs for steps 2 and 3; [Set up your coding agent](../agent-native/setup.md) describes what it writes and how to do it by hand.
 
 **Already inside Claude Code, Codex, or Cursor?** Open your agent's repository there, paste this, and it runs the same installer for you:
 
@@ -66,7 +66,7 @@ Set up Kitaru in this repository by following https://kitaru.ai/install.md. Use
 kitaru doctor
 ```
 
-It checks the CLI, the server connection, authentication, and whether the skills are installed. Server connection and authentication fail until you have run `kitaru login --local` (needs [Docker](https://docs.docker.com/get-started/get-docker/)) or `kitaru login` for the managed cloud; the sections below cover both.
+It checks the CLI, the server connection, authentication, and whether the skills are installed (`kitaru setup` installs them if not). Server connection and authentication fail until you have run `kitaru login --local` (needs [Docker](https://docs.docker.com/get-started/get-docker/)) or `kitaru login` for the managed cloud; the sections below cover both.
 
 Then read the [Quickstart](quickstart.md). It is written as prompts for your coding agent, and everything it needs is now in place.
 

install.sh

@@ -14,12 +14,14 @@
 #          `kitaru` and `kitaru-mcp` on PATH (~/.local/bin). Good for the CLI,
 #          MCP server, imports and evaluators; replays need the project form.
 #      --project / --global force either.
-#   3. Installs the Kitaru agent skills (zenml-io/kitaru-skills) from the
-#      repository tarball into ~/.agents/skills, plus ~/.claude/skills and
-#      ~/.codex/skills when those CLIs are installed. No Node needed.
-#   4. Registers the Kitaru MCP server with Claude Code and Codex if their
-#      CLIs are installed; prints the JSON for everything else.
-#   5. Stops there and prints the two ways to get a server: local in Docker
+#   3. Runs `kitaru setup`, which installs the Kitaru agent skills
+#      (zenml-io/kitaru-skills) into ~/.agents/skills plus ~/.claude/skills
+#      and ~/.codex/skills when those CLIs are installed, and registers the
+#      Kitaru MCP server with Claude Code, Codex, Cursor, and Windsurf when
+#      found (printing the JSON for everything else). Re-run `kitaru setup`
+#      after installing a new coding agent. Kitaru releases before `setup`
+#      existed get the same steps done by this script instead.
+#   4. Stops there and prints the two ways to get a server: local in Docker
 #      (`kitaru login --local`) or the managed cloud (`kitaru login`). Login
 #      is a decision, so the script does not make it for you.
 #
@@ -306,7 +308,33 @@ else
 fi
 
 # ---------------------------------------------------------------------------
-# 3. Coding-agent skills
+# 3. Skills and MCP registration, via `kitaru setup`
+# ---------------------------------------------------------------------------
+# The CLI owns client detection so it can be re-run after installing a new
+# coding agent. `schema setup` is offline and only succeeds on versions that
+# have the command; older ones fall through to the bash implementation below.
+SETUP_DONE=0
+if [ "$KITARU_SKIP_SKILLS" = "1" ] && [ "$KITARU_SKIP_MCP" = "1" ]; then
+  note "Skipping skills and MCP registration (--no-skills --no-mcp)"
+  SETUP_DONE=1
+elif "$KITARU_BIN" schema setup >/dev/null 2>&1; then
+  step "Running kitaru setup (skills and MCP registration)"
+  SETUP_ARGS=(--mode "$KITARU_MCP_MODE")
+  [ "$KITARU_SKIP_SKILLS" = "1" ] && SETUP_ARGS+=(--no-skills)
+  [ "$KITARU_SKIP_MCP" = "1" ] && SETUP_ARGS+=(--no-mcp)
+  SETUP_SERVER_ARGS=()
+  [ -n "$KITARU_SERVER" ] && SETUP_SERVER_ARGS=(--server "$KITARU_SERVER")
+  if [ "$KITARU_QUIET" = "1" ]; then
+    quiet "$KITARU_BIN" "${SETUP_SERVER_ARGS[@]}" setup "${SETUP_ARGS[@]}" || warn "kitaru setup failed; run it again later: $KITARU_BIN setup"
+  else
+    "$KITARU_BIN" "${SETUP_SERVER_ARGS[@]}" setup "${SETUP_ARGS[@]}" </dev/null || warn "kitaru setup failed; run it again later: $KITARU_BIN setup"
+  fi
+  SETUP_DONE=1
+fi
+
+if [ "$SETUP_DONE" = "0" ]; then
+# ---------------------------------------------------------------------------
+# 3a. Coding-agent skills (Kitaru releases without `kitaru setup`)
 # ---------------------------------------------------------------------------
 # Destinations: ~/.agents/skills is the cross-agent location; ~/.claude and
 # ~/.codex get their own copy when that CLI is installed or the dir exists.
@@ -370,7 +398,7 @@ else
 fi
 
 # ---------------------------------------------------------------------------
-# 4. MCP server registration
+# 3b. MCP server registration (Kitaru releases without `kitaru setup`)
 # ---------------------------------------------------------------------------
 MCP_SERVER_URL="${KITARU_SERVER:-$KITARU_LOCAL_URL}"
 MCP_ARGS=(--server "$MCP_SERVER_URL" --mode "$KITARU_MCP_MODE")
@@ -417,6 +445,8 @@ else
   fi
 fi
 
+fi  # SETUP_DONE
+
 # ---------------------------------------------------------------------------
 # Done
 # ---------------------------------------------------------------------------
@@ -453,6 +483,7 @@ if [ "$KITARU_SCOPE" = "global" ]; then
 fi
 say ""
 say "  No agent yet?  ${C_BOLD}Use kitaru-guided-tour to show me Kitaru on the example agent.${C_RESET}"
+say "  New editor?    $K setup   (wires skills and MCP into it)"
 say "  Check setup:   $K doctor"
 say "  Docs:          https://docs.zenml.io/kitaru"
 say ""

src/kitaru/cli/app.py

@@ -54,6 +54,7 @@
     workers,
 )
 from kitaru.cli import auth as auth_commands
+from kitaru.cli import setup as setup_commands
 from kitaru.cli.config import (
     CONFIG_KEYS,
     ResolvedTarget,
@@ -919,6 +920,64 @@ async def doctor() -> CommandResult:
     )
 
 
+@_register(
+    app,
+    _spec(
+        ("setup",),
+        "Install the agent skills and register the MCP server with every "
+        "detected coding agent. Re-run after installing a new one. The global "
+        "--server picks the server the MCP server targets.",
+        parameters=(
+            ParameterSpec(
+                "--mode",
+                "string",
+                "option",
+                False,
+                "MCP capability mode: read-only, standard (default), or destructive.",
+            ),
+            ParameterSpec(
+                "--no-skills", "boolean", "option", False, "Skip installing the skills."
+            ),
+            ParameterSpec(
+                "--no-mcp",
+                "boolean",
+                "option",
+                False,
+                "Skip registering the MCP server.",
+            ),
+        ),
+        read_only=False,
+        side_effects=("writes_local_file", "executes_local_code"),
+        idempotency="idempotent",
+        errors=(
+            "invalid_arguments",
+            "invalid_configuration",
+            "network_error",
+            "internal_error",
+        ),
+    ),
+)
+async def setup(
+    *,
+    mode: Annotated[str, Parameter(name="--mode")] = "standard",
+    no_skills: Annotated[bool, Parameter(name="--no-skills")] = False,
+    no_mcp: Annotated[bool, Parameter(name="--no-mcp")] = False,
+) -> CommandResult:
+    """Wire skills and the MCP server into installed coding agents."""
+    invocation = _invocation()
+    if mode not in setup_commands.MCP_MODES:
+        raise CLIError(
+            "invalid_arguments",
+            f"--mode must be one of {', '.join(setup_commands.MCP_MODES)}.",
+        )
+    return await setup_commands.setup(
+        server=invocation.server,
+        mode=mode,  # type: ignore[arg-type]
+        install_skills=not no_skills,
+        register_mcp=not no_mcp,
+    )
+
+
 @_register(
     app,
     _spec(

src/kitaru/cli/output.py

@@ -447,6 +447,9 @@ def _emit_human_detail(
     if view.renderer == "doctor":
         _emit_doctor(console, value)
         return
+    if view.renderer == "setup":
+        _emit_setup(console, value)
+        return
     if not view.sections:
         fields = tuple(
             field for field in view.fields if field.min_console_width <= console.width
@@ -509,6 +512,42 @@ def _emit_doctor(console: Console, value: dict[str, Any]) -> None:
     console.print(table)
 
 
+def _emit_setup(console: Console, value: dict[str, Any]) -> None:
+    """Render setup steps as a checklist plus the manual MCP snippet."""
+    install = _display_value(value.get("install"))
+    console.print(
+        f"Kitaru MCP server: [bold]{_display_value(value.get('server_url'))}[/bold] "
+        f"in [bold]{_display_value(value.get('mode'))}[/bold] mode "
+        f"({install} install)."
+    )
+    steps = value.get("steps")
+    if isinstance(steps, list) and steps:
+        table = Table(title="Steps", title_justify="left")
+        table.add_column("Step")
+        table.add_column("Target")
+        table.add_column("Status")
+        table.add_column("Detail")
+        for step in steps:
+            if not isinstance(step, dict):
+                continue
+            status = _display_value(step.get("status"))
+            table.add_row(
+                Text(_display_value(step.get("kind"))),
+                Text(_display_value(step.get("target"))),
+                Text(status, style=_SETUP_STATUS_STYLES.get(status, "")),
+                Text(_display_value(step.get("detail"))),
+            )
+        console.print(table)
+    if isinstance(steps, list) and any(
+        isinstance(step, dict) and step.get("target") == "manual" for step in steps
+    ):
+        console.print("For any other MCP client, add:")
+        console.print(json.dumps(value.get("mcp_snippet"), indent=2))
+
+
+_SETUP_STATUS_STYLES = {"done": "green", "skipped": "yellow", "failed": "red"}
+
+
 def _emit_human_section(
     console: Console,
     title: str,

src/kitaru/cli/presentation.py

@@ -47,7 +47,7 @@ class HumanView:
     fields: tuple[HumanField, ...]
     sections: tuple[HumanSection, ...] = ()
     empty_message: str = "No results found."
-    renderer: Literal["default", "doctor", "root"] = "default"
+    renderer: Literal["default", "doctor", "root", "setup"] = "default"
 
 
 def _format_count(value: Any) -> str:
@@ -284,6 +284,11 @@ def _build_view(
         fields=(),
         renderer="doctor",
     ),
+    "setup": HumanView(
+        title="Setup",
+        fields=(),
+        renderer="setup",
+    ),
     "agent.list": _build_view("Agents", _ASSET_FIELDS, _ASSET_SECTIONS),
     "agent.get": _build_view("Agent", _ASSET_FIELDS, _ASSET_SECTIONS),
     "agent.register": _build_view("Agent", (), _REGISTRATION_SECTIONS),