setup-warp-cursor-theme

# Set up Warp with the Cursor Dark look

Bring this machine's Warp terminal and Claude Code to the user's standard look. It works on Windows, macOS and Linux, and on a machine that already has Warp as well as one that does not. Work through the steps in order. Before each one, check what is already in place and change only what is missing or different. Finish with the report described at the end.

The finished state:

- Warp is installed, has three custom themes available (Cursor Dark, Claude Dark, Claude Light), and Cursor Dark is the active one.
- Claude Code runs in its fullscreen renderer with a custom theme called "Cursor Dark".
- The Flightdeck plugin is installed, so its dashboard docks as a sidebar on the right.

The theme files ship with this skill, in the same folder as this file (`${CLAUDE_SKILL_DIR}`):

- `warp-themes/cursor_dark.yaml`
- `warp-themes/claude_dark.yaml`
- `warp-themes/claude_light.yaml`
- `claude-theme/cursor-dark.json`

Copy them as they are, without retyping or reformatting. Where a file of the same name already exists with different contents, keep the old one by adding `.bak` to its name, then copy, and put that in the report.

Four rules apply to every step:

- When a step says to put something in the report, add it to a running list so nothing is lost by the end.
- When an install command fails or is not available, do not work around it. Add it to the report and carry on with the remaining steps.
- Never type or ask for a password. Before any `sudo` command, run `sudo -n true`. If that fails, do not run the command: put the exact command in the report for the user to run.
- Before editing a settings file, keep its original text so the final check can compare against it.

## Where things live

| | Windows | macOS | Linux |
|---|---|---|---|
| Warp themes folder | `%APPDATA%\warp\Warp\data\themes\` | `~/.warp/themes/` | `${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal/themes/` |
| Warp settings file | `%LOCALAPPDATA%\warp\Warp\config\settings.toml` | `~/.warp/settings.toml` | `${XDG_CONFIG_HOME:-$HOME/.config}/warp-terminal/settings.toml` |
| Claude Code folder | `%USERPROFILE%\.claude\` | `~/.claude/` | `~/.claude/` |

The Warp paths are for the stable release, which is what this skill sets up. Warp Preview keeps its own separate folders and is left alone.

## Why each piece exists

Reason from these if this machine differs from what the steps expect.

- Fullscreen mode is what makes Claude Code dock plugin panes on the right. In the classic renderer they show as a strip above the prompt.
- Claude Code paints docked panes with the theme colour `composerSidebarBackground`. The built-in `dark-ansi` theme maps that to ANSI bright black, which the Cursor Dark Warp theme renders as mid grey. `cursor-dark.json` is `dark-ansi` with that one colour overridden to `#141414`, the Cursor Dark background, so the sidebar matches the terminal.
- Flightdeck keeps its default colours and default options, which already place it on the right. Do not edit the plugin's files or add a `pluginConfigs` entry for it.

## 1. Warp

First find out whether Warp is already installed. Any one of these is enough:

- Windows: `C:\Program Files\Warp\warp.exe` or `%LOCALAPPDATA%\Programs\Warp\warp.exe` exists, or `winget list --id Warp.Warp -e` lists it.
- macOS: `/Applications/Warp.app` or `~/Applications/Warp.app` exists, or `brew list --cask warp` succeeds.
- Linux: `command -v warp-terminal` finds it, or the package manager knows the `warp-terminal` package (`dpkg -s`, `rpm -q` or `pacman -Q`).

**If Warp is already installed,** leave the install alone. Do not reinstall, upgrade or repair it. The remaining steps then change a setup the user already relies on, so take the care in steps 2 and 3 literally: add to what is there and replace only the lines named.

On Linux, if none of the checks finds Warp but the folder that holds the Warp settings file exists, Warp may be in use as an AppImage. Do not install a second copy. Say so in the report.

**If Warp is missing,** install it:

- Windows: `winget install --id Warp.Warp -e --accept-source-agreements --accept-package-agreements`. winget can spend a few minutes refreshing its sources, so allow up to 10 minutes.
- macOS: `brew install --cask warp`. If Homebrew is not installed, do not install Homebrew: put "install Warp from https://www.warp.dev/download" in the report.
- Linux: installing needs root, so run `sudo -n true` first.
  - If it succeeds, download the package for this machine's package manager into a temporary folder with `curl -fL -o <file> "<url>"` (or `wget -O <file> "<url>"` when there is no curl), install it, then delete the download.
  - If it fails, download nothing. Put both commands, the download and the install, in the report for the user to run.

  | Package manager | Download URL | Install command |
  |---|---|---|
  | apt | `https://app.warp.dev/download?package=deb` | `sudo apt install -y ./<file>.deb` |
  | dnf | `https://app.warp.dev/download?package=rpm` | `sudo dnf install -y ./<file>.rpm` |
  | pacman | `https://app.warp.dev/download?package=pacman` | `sudo pacman -U --noconfirm ./<file>.pkg.tar.zst` |
  | zypper | `https://app.warp.dev/download?package=rpm` | `sudo zypper --non-interactive install ./<file>.rpm` |

  On an ARM machine (`uname -m` prints `aarch64` or `arm64`), add `_arm64` to the package name in the URL: `deb_arm64`, `rpm_arm64` or `pacman_arm64`. On a distribution with none of these package managers, put "install Warp from https://www.warp.dev/download" in the report.

If Warp could not be installed, carry on anyway. None of steps 2 to 7 needs Warp to be present, and the themes folder can be created before Warp is.

## 2. Warp themes

Copy the three files from `warp-themes/` into the Warp themes folder, creating the folder if it does not exist. Leave every other file in that folder untouched.

## 3. Make Cursor Dark the active Warp theme

The active theme is set in the Warp settings file, under `[appearance.themes]`. The format is the same on every OS, and the path is relative to the themes folder:

```toml
[appearance.themes]
system_theme = false
theme = { custom = { name = "Cursor Dark", path = "cursor_dark.yaml" } }
```

The only test for this step is whether the settings file exists.

**If it exists:**

- Read the current `system_theme` and `theme` values first and put them in the report, so the user can go back to the theme they had. If the file sets neither, say that no theme was set there, which means Warp's default.
- If the file has an `[appearance.themes]` table, make those two lines read as above. Replace the current values (a built-in theme appears as a plain string such as `theme = "phenomenon"`) and add either line if it is absent.
- If the file has no `[appearance.themes]` table, append a blank line and the three lines above to the end of the file.
- Leave everything else in the file alone.

**If it does not exist,** do not create it. Warp treats a missing settings file as the cue to carry the user's older preferences over into a new one, and a file made ahead of time would stop that. The file is missing when Warp has never been opened, is still on its default settings, or is a version from before the settings file existed. Skip this step and put "pick Cursor Dark in Warp under Settings > Appearance > Themes" in the report.

## 4. Claude Code theme

Copy `claude-theme/cursor-dark.json` into the `themes` folder inside the Claude Code folder, creating it if needed.

## 5. Flightdeck plugin

Run `claude plugin list`. If Flightdeck is already installed and enabled, skip this step. If it is installed but disabled, run `claude plugin enable flightdeck@claude-flightdeck` and skip the rest of this step.

Flightdeck needs Claude Code 2.1.287 or later, so check `claude --version`. If this machine is older, skip this step and put "update Claude Code, then run this skill again" in the report. Otherwise run:

```
claude plugin marketplace add scasella/claude-flightdeck
claude plugin install flightdeck@claude-flightdeck
```

A message that the marketplace is already added is fine; carry on to the second command. The installer may say config options are not set. The defaults are right. If either command fails for another reason, put in the report that the user should run `/plugin marketplace add scasella/claude-flightdeck` and `/plugin install flightdeck@claude-flightdeck` themselves.

Do this before step 6, because these commands write to `settings.json` themselves.

## 6. Claude Code settings

In the user settings file, `settings.json` in the Claude Code folder, set these two top-level keys:

```json
"tui": "fullscreen",
"theme": "custom:cursor-dark"
```

Read the file as it stands after step 5 and change only those two keys. Every other setting, hook and plugin entry must stay exactly as it is. Put the previous `theme` value in the report, so the user can go back to it. If the file does not exist, create it with just these keys. If it exists but does not parse as JSON, leave it alone and put that in the report.

Save it as UTF-8 without a byte-order mark, and confirm afterwards that it still parses, using whichever JSON parser the machine has (`python3 -m json.tool`, `node`, `jq`, or PowerShell's `ConvertFrom-Json`).

## 7. jq, only if needed

Check whether `warp@claude-code-warp` is enabled under `enabledPlugins` in the Claude Code `settings.json`. That plugin's hooks need `jq`. If it is enabled and `jq` is not on PATH, install it:

- Windows: `winget install --id jqlang.jq -e --accept-source-agreements --accept-package-agreements`
- macOS: `brew install jq`
- Linux: `sudo apt-get install -y jq`, `sudo dnf install -y jq`, `sudo pacman -S --noconfirm jq` or `sudo zypper --non-interactive install jq`, whichever matches the machine.

If the plugin is not enabled, skip this step. Installing that plugin is not part of this skill.

## Check, then report

Confirm each of these. If one fails, say so in the report instead of trying another route.

- The three Warp theme files and the Claude Code theme file exist and match the copies in this skill.
- If step 3 was done, the Warp settings file has both lines under `[appearance.themes]`, and those lines are its only difference from the original text.
- The Claude Code `settings.json` parses and has both keys, and those two keys are the only difference from the file as it stood after step 5.
- Flightdeck shows as installed and enabled in `claude plugin list`.

Then tell the user what was done, what was already in place, what could not be done, and what is left for them, including everything on the running list.

Some things only the user can do. Always include these three points instead of attempting them, adapting the wording to what happened (for example when Warp still has to be installed, or step 3 was skipped):

- Open Warp, or if it is already running, quit it fully and reopen it. A restart is the reliable way for Warp to load new theme files and a changed PATH, so there is no need to work out whether it is running. If it does not come up in Cursor Dark, pick it under Settings > Appearance > Themes; Warp's settings sync may bring back an earlier choice.
- Restart Claude Code so the fullscreen renderer and the theme take effect. A theme change does not reach a session that is already running.
- If the Flightdeck sidebar is not showing, run `/flightdeck` once. It opens by itself only in a window at least 144 columns wide. Between 110 and 143 columns it docks on the right once it has been opened by hand, and below 110 it shows as a strip above the prompt.