---
name: renoise-setup
description: >
  Set up, update, or diagnose Renoise on any agent host. Use when the user asks to install,
  upgrade, configure, connect, log in, check dependencies, connect the Renoise tools, enable
  the Renoise CLI, or fix missing RENOISE_API_KEY, ffmpeg, jq, yt-dlp, ImageMagick, or agent-browser.
metadata:
  author: renoise
  version: 1.0.2
  category: setup
  tags: [setup, install, authentication, dependencies, renoise]
---

# Renoise Setup — Cross-Harness

This is the host-neutral setup flow. Do not assume Claude Code, Codex, OpenClaw, or a specific config directory. Resolve `<PLUGIN_ROOT>` as two directories above this skill's directory.

Another Renoise workflow may invoke this setup automatically when its preflight fails. Diagnose and preview immediately, then return to the original request after readiness is restored; do not make the user manually select **Setup / Account**.

Never ask the user to paste an API key into chat. Never install software, move binaries, edit `PATH`, or change host configuration without explicit confirmation.

## 0. Plugin copy freshness

Before fixing the CLI, check whether **this installed plugin** is behind the latest public release:

```text
node "<PLUGIN_ROOT>/skills/renoise-setup/scripts/check-plugin.mjs"
```

- exit `0` — current (or newer than latest); continue
- exit `2` — print the script's host-specific upgrade commands and **stop** until the user updates/reinstalls the plugin and restarts the host; do not claim new plugin behavior is already active
- exit `1` — network/API failure; warn once and continue setup

Plugin installs are owned by each host marketplace. This check only guides the user; it cannot replace the plugin in place.

## 1. Connect the Renoise Tools

Every Renoise operation in a conversation (models, estimates, generation, uploads, analysis, results) goes through the Renoise MCP server at `https://renoise.ai/api/public/mcp`. Connecting it is the only step generation needs. The user signs in once in the browser (OAuth); never ask for an API key.

| Host | How it connects |
|---|---|
| Claude Code | The plugin declares the `renoise` server. If it shows "Needs authentication", ask the user to run `/mcp`, choose `plugin:renoise:renoise`, and authenticate in the browser. |
| Codex | The plugin declares the `renoise` server; authorize it when Codex asks, or run `codex mcp login renoise`. |
| Claude Desktop / claude.ai | Add the Renoise connector (Settings → Connectors, URL above). |
| OpenClaw | Add an MCP server named `renoise` with that URL, `transport: "streamable-http"` and `auth: "oauth"` (ask before editing host configuration), then run `openclaw mcp login renoise`. |

Verify by calling the `get_account` tool. When it answers, generation is ready; the CLI below is optional.

## 2. Optional: the Native CLI

The CLI is needed only for the annotation board, the local helpers in `renoise-cli`, and the user's own scripts. Skip this section otherwise.

### Detect, Install, or Update

Detect without changing the host:

| Host | Detection |
|---|---|
| macOS / Linux shell | `command -v node; command -v renoise; uname -s; uname -m` |
| Windows PowerShell | `Get-Command node, renoise -ErrorAction SilentlyContinue; [System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture` |

Node.js is required by the plugin's local helpers and cross-platform installer scripts; Bun is optional.

If `renoise` exists, verify the plugin contract rather than trusting a static version number:

```text
renoise version
renoise help task create
renoise help task cost
renoise help task wait
renoise help analyze
renoise help auth exec
renoise help auth login
```

The outputs must contain the exact usage paths `renoise task create`, `renoise task cost`, `renoise task wait`, `renoise analyze`, and `renoise auth exec`; the create flag `--prompt-file`; the cost flag `--edit`; the analyze flag `--mode`; plus the `auth login` flag `--web`. Older Cobra builds may show parent help and still exit successfully.

`--ensure` keeps the **managed** CLI current. It reads `https://download.renoise.ai/cli/latest.json` and installs/replaces only the managed target when missing, incompatible, or older than the latest public release — no prompt:

```text
node "<PLUGIN_ROOT>/skills/renoise-setup/scripts/install-cli.mjs" --ensure
```

| Host | Managed target |
|---|---|
| macOS / Linux | `~/.local/bin/renoise` |
| Windows | `%LOCALAPPDATA%\Renoise\bin\renoise.exe` |

After `--ensure`, prefer that managed binary for the session (`export PATH="$HOME/.local/bin:$PATH"` on Unix, or prepend `%LOCALAPPDATA%\Renoise\bin` on Windows). `--ensure` never edits shell profiles or the Windows user environment.

For a dry run (no downloads), or when the user explicitly asks to inspect/install outside generation:

```text
node "<PLUGIN_ROOT>/skills/renoise-setup/scripts/install-cli.mjs" --check
```

The installer supports macOS, Windows, and Linux on x64 or ARM64. It selects `.tar.gz` on macOS/Linux or `.zip` on Windows and verifies the archive against the release's `checksums.txt`.

Show the installed and latest versions, detected release archive, whether the target will replace an existing file, and target path. For **manual** `--install`, **ask for explicit confirmation** first, then run:

```text
node "<PLUGIN_ROOT>/skills/renoise-setup/scripts/install-cli.mjs" --install
```

If the managed target directory is absent from `PATH` or another `renoise` binary wins PATH resolution, explain the platform-specific change and ask separately before editing shell profiles or the Windows user environment. Restart Codex/ChatGPT Desktop or Claude Desktop after a PATH change. Linux has no official Codex Desktop app, but the same CLI and skills work in Codex CLI and Claude Code.

For manual installation, read the public release manifest at `https://download.renoise.ai/cli/latest.json`, download the matching archive and `checksums.txt` from its version directory, verify SHA-256, then extract the binary. Downloading, moving, or replacing files still requires confirmation.

Before replacing an existing binary, the installer checks all five command contracts. After installation, rerun the checks above. If agent-safe `task create --prompt-file`, `task wait`, `analyze --mode`, `auth exec`, or browser login is unavailable, the release is incompatible; stop and ask the user to upgrade rather than recreating the command in the plugin.

### Authenticate the CLI

First run `renoise auth status --json`. If it is not authenticated, the Agent—not the user—must run:

```bash
renoise auth login --web --json
```

Keep the command running while it opens the Renoise authorization page. The user only signs in and selects **Allow and connect** in the browser; never ask them to open a terminal, copy an API key, or paste a secret into chat. The CLI receives the credential through a one-time localhost callback, validates it, and saves it in the OS user config directory with restricted permissions. After the command returns, continue setup automatically.

`RENOISE_API_KEY` remains the CLI credential override for CI and containers.

Verify through the native CLI:

```bash
renoise account status --json
renoise model --json
```

If browser authentication fails, rerun `renoise auth login --web --json`. Only direct the user to account settings when the browser reports an account or permission error; do not fall back to secret entry in chat.

## 3. Check Workflow Readiness

Detection only on macOS/Linux:

```bash
for tool in jq ffmpeg ffprobe yt-dlp magick agent-browser; do
  if command -v "$tool" >/dev/null 2>&1; then printf 'OK      %s\n' "$tool"; else printf 'MISSING %s\n' "$tool"; fi
done
```

Windows PowerShell equivalent:

```powershell
'jq','ffmpeg','ffprobe','yt-dlp','magick','agent-browser' | ForEach-Object {
  if (Get-Command $_ -ErrorAction SilentlyContinue) { "OK      $_" } else { "MISSING $_" }
}
```

| Tool | Enables |
|------|---------|
| `jq` | Director batch generation |
| `ffmpeg` + `ffprobe` | Assembly, tail frames, QC, audio mix, video inspection |
| `yt-dlp` | Video downloads |
| ImageMagick `magick` | Storyboard-grid splitting; optional QC fallback |
| `agent-browser` | Optional Douyin/TikTok download fallback |

Offer only relevant missing tools, and install only after confirmation:

- macOS/Homebrew: `brew install jq ffmpeg yt-dlp imagemagick`
- Debian/Ubuntu: `sudo apt install jq ffmpeg imagemagick`; current yt-dlp: `pipx install yt-dlp`
- Windows/winget: `winget install jqlang.jq Gyan.FFmpeg yt-dlp.yt-dlp ImageMagick.ImageMagick`
- Optional browser fallback: `npm install -g agent-browser && agent-browser install`

Missing optional tools do not block generation or media analysis, which run through the Renoise tools.

## 4. Report

Return a short readiness summary:

```text
Renoise tools (MCP): connected / action needed
Generation + media analysis: ready / action needed
Renoise CLI (board, helpers, scripts): ready / not installed
Director/QC: ready / limited by ...
Downloads: ready / limited by ...
Optional browser fallback: ready / not installed
```

Apply host-specific extras only when that host exposes them. For example, the Claude Code `/renoise:setup` wrapper may additionally configure its statusLine; that is not part of this universal flow.