# Cursor Setup

> 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 seeds a ready-to-use `~/.cursor.json` (a copy of the shipped defaults) 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).

- Skill: `hirofumiko/cursor-setup` (Agent Skill)
- Install (CLI): `npx skillmds@latest add hirofumiko/cursor-setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hirofumiko/cursor-setup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: HiroFumiko (https://skillmd.com/u/hirofumiko)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/hirofumiko/cursor-setup

---


# 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 [--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. **Seed the `~/.cursor.json` config** so the user's routing tweaks live
      **outside** the plugin. Marketplace updates overwrite the skill default
      (layer 1) but **never** `~/.cursor.json` — that is the whole point of
      writing an override. Config is **user-scoped only** (applies to every repo
      for this user); there is no per-project config file. Use **AskUserQuestion**
      to ask whether to seed it (header e.g. `Seed config`):
      - **Yes** → write `~/.cursor.json` (a ready-to-use copy of the defaults).
      - **Skip** → keep using the built-in skill default (no file written).

      On *yes*, run:
      ```
      bash ${CLAUDE_PLUGIN_ROOT}/skills/cursor/lib/setup.sh --init-config
      ```
      The file is a **ready-to-use copy of the shipped defaults** — it already
      holds real values (models, modes, preambles) the user can edit in place,
      not an empty stub that looks configured but does nothing until edited.
      (A full copy pins those values into the override layer, so a field the user
      keeps no longer tracks future skill-default updates; deleting a field
      re-enables default tracking for it.)
      - stdout `WROTE\t<path>` → tell the user the path, and that the file works
        as-is — they edit values in place to customize (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 --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 whether to
  seed the config). `--apply-permissions` writes `~/.claude/settings.json`;
  `--init-config` writes a ready-to-use copy of the shipped defaults to
  `~/.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.).