---
name: cursor-setup
description: Cross-platform readiness setup for the `cursor` delegation skill. Detects the host OS (WSL / Linux / macOS; native Windows is unsupported → WSL), checks every runtime dependency in one pass without spending Cursor tokens, generates the `~/.claude/settings.json` permission allowlist so read-only delegation runs without a prompt, and — once the verdict is READY — interactively scaffolds a minimal `.cursor.json` override at user or project scope so routing tweaks live outside the plugin and survive marketplace updates. Triggers on "/cursor-setup", "cursor setup", "setup cursor", "cursor 環境構築", "cursorのセットアップ", "cursor doctor", or when the cursor skill fails a preflight check (missing agent/jq/timeout/auth).
level: 2
version: 1.0.0
---

# cursor-setup

One-shot, per-environment setup for the [`cursor`](../cursor/SKILL.md) skill.
The skill itself is bash + Unix coreutils; this command makes it run smoothly on
each host by **detecting the OS, checking dependencies, and wiring permissions**.

The heavy lifting lives in one bash engine:

```
bash ${CLAUDE_PLUGIN_ROOT}/skills/cursor/lib/setup.sh \
  [--check | --print-permissions | --apply-permissions | --init-config <user|project> [--force]]
```

`bash ${CLAUDE_PLUGIN_ROOT}/skills/cursor/lib/cursor.sh setup …` (alias `doctor`) routes to
the same script.

## What it checks (no `agent` call — zero token cost)

| Check | Hard dep? | macOS note |
|-------|-----------|------------|
| `bash` version | no (advisory) | stock `/bin/bash` is 3.2 — fully supported; ≥4.3 only speeds `fanout --local-parallel` |
| `agent` (Cursor CLI) | **yes** | `curl https://cursor.com/install -fsS \| bash` |
| `jq` | **yes** | `brew install jq` |
| `timeout` / `gtimeout` | **yes** | `brew install coreutils` provides `gtimeout` |
| GNU vs BSD `date` | no | skill is BSD-tolerant; `gdate` used when present |
| auth (`CURSOR_API_KEY` or `~/.cursor` session) | **yes** | `agent login` |
| `~/.cursor` writable | **yes** | sandbox / read-only fs hint if not |
| permission allowlist present | no (advisory) | generated by this command |

## Platform support

- **WSL Ubuntu** / **native Linux** — first-class. `apt-get install -y jq coreutils`.
- **macOS** — first-class on stock bash 3.2 (no upgrade needed); install `jq` +
  `coreutils` via Homebrew.
- **Windows (native)** — **not supported** (no bash + Unix coreutils). The doctor
  detects MSYS/Cygwin/MinGW and prints WSL bootstrap steps. Git Bash / Cygwin are
  not officially supported; use `wsl --install -d Ubuntu` and run everything
  inside WSL.

## Protocol (how Claude should run this)

1. **Run the doctor**: `bash ${CLAUDE_PLUGIN_ROOT}/skills/cursor/lib/setup.sh`. Read its
   stdout. Relay the **Verdict** (`READY ✓` / `NEEDS SETUP ✗`) and any
   `[MISSING]` / `[WARN]` lines to the user.

2. **If `NEEDS SETUP ✗` (one or more blocking items)** — stop here, do **not**
   proceed to permissions or config generation:
   - Surface the per-OS *Fix-it steps* the doctor printed.
   - Do **not** silently auto-install — these touch the user's system. Offer to
     run a specific command only with explicit confirmation (Windows → recommend
     WSL; do not attempt a native install).
   - Close by telling the user explicitly: **after installing the missing pieces,
     re-run `/cursor-setup`** to re-check. The setup is not complete until the
     verdict is `READY ✓`.

3. **If `READY ✓` (all hard deps present)** — finish the setup in two steps:

   a. **Permissions**: if the doctor warns that no cursor allow rules exist,
      preview them with `--print-permissions`, explain that they auto-approve
      **read-only** delegation only (`review` / `plan` / `investigate` /
      `security` / `status` / `fanout --collect`) while `implement` / `cancel` /
      `resume` still prompt, then **ask before** running `--apply-permissions`
      (it edits the global `~/.claude/settings.json`, backing it up to
      `settings.json.cursor-setup.bak`).

   b. **Scaffold a `.cursor.json` override** so the user's routing tweaks live
      **outside** the plugin. Marketplace updates overwrite the skill default
      (layer 1) but **never** `~/.cursor.json` or `<cwd>/.cursor.json` — that is
      the whole point of writing an override. Use **AskUserQuestion** to ask
      *where* to write it (header e.g. `Config scope`):
      - **User scope** → `~/.cursor.json` (applies to every repo for this user).
      - **Project scope** → `<cwd>/.cursor.json` (applies to this repo only; can
        be committed so the team shares it).
      - **Skip** → keep using the built-in skill default (no file written).

      On a non-skip choice, run:
      ```
      bash ${CLAUDE_PLUGIN_ROOT}/skills/cursor/lib/setup.sh --init-config <user|project>
      ```
      The file is a **minimal override scaffold** (`{"version":1,"defaults":{}}`):
      an empty `defaults` is a no-op on the deep-merge, so the skill default fully
      applies until the user adds a diff — and fields they don't override keep
      receiving skill-default improvements on future updates (a full copy would
      shadow them, which is why it is intentionally minimal).
      - stdout `WROTE\t<path>` → tell the user the path, and that they add **only**
        the fields they want to change (e.g. a task's `model` / `mode` /
        `preamble`); point them at the schema + examples in
        [`configuration.md`](../cursor/references/configuration.md).
      - stdout `EXISTS\t<path>` → the file already exists. Ask via
        **AskUserQuestion** whether to overwrite; only on *yes* re-run with
        `--init-config <scope> --force` (the old file is backed up to
        `<path>.cursor-setup.bak`).

4. **Confirm**: optionally re-run `bash …/setup.sh` and show the verdict is
   `READY ✓`.

## Notes

- `--check` is the default and is purely diagnostic (read-only; never invokes
  `agent`). Exit code: `0` ready, `1` needs setup.
- `--apply-permissions` and `--init-config` are the mutating modes — always
  confirm with the user first (the AskUserQuestion in step 3b covers the config
  scope choice). `--apply-permissions` writes `~/.claude/settings.json`;
  `--init-config <scope>` writes a minimal override scaffold
  (`{"version":1,"defaults":{}}`) to `~/.cursor.json` or `<cwd>/.cursor.json` and
  **never overwrites** an existing file unless `--force` (which backs the old one
  up to `<path>.cursor-setup.bak`). `.cursor.json` must **never** contain a
  `CURSOR_API_KEY` — keep secrets in the environment.
- After setup, drive real work through the [`cursor`](../cursor/SKILL.md) skill
  (`/cursor review …`, `/cursor fanout …`, etc.).