Cursor Setup

cursor-setup

One-shot, per-environment setup for the cursor 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)

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.
   • 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 skill (/cursor review …, /cursor fanout …, etc.).