# Connect Mixroadie to this AI app

These are instructions for an AI assistant with access to a terminal: Claude
Code, Codex (in the ChatGPT desktop app, the Codex CLI or an editor) or a
similar agent. The user asked you to connect Mixroadie, a mixing assistant for
REAPER, so they can ask you about their songs. Follow the steps below on their
computer. The human version of this guide is at
https://mixroadie.com/blog/mixroadie-with-claude-and-chatgpt/.

What this sets up: Mixroadie's MCP server, a local program your app starts
over stdio. Nothing listens on the network. It measures songs and proposes
plans. It never changes a project.

## Rules

- Only change what these steps name: Mixroadie's own environment and the
  `mixroadie` entry in each AI app's config. Keep every other entry and
  setting in those config files exactly as it is.
- If a config file exists but can't be parsed, don't rewrite it. Tell the user
  which file and stop for that app.
- Don't open, edit or render any REAPER project.
- Explain each command in one plain sentence before you run it. The user may
  not be technical.
- The steps need write access outside the current folder (the user's home
  folder) and, for step 2, internet access.
- If your permission system or sandbox blocks a command, don't look for another
  way to do the same thing. Stop, show the user the exact command, and tell
  them to run it themselves: in Claude Code by typing `!` followed by the
  command, otherwise by pasting it into Terminal (macOS) or PowerShell
  (Windows). Then continue with step 4 once they have.

## Step 1: find Mixroadie

Mixroadie installs into a fixed place:

| System  | The `roadie` program |
|---------|----------------------|
| macOS   | `~/.mixroadie/venv-audio/bin/roadie` |
| Windows | `%USERPROFILE%\.mixroadie\venv-audio\Scripts\roadie.exe` |

Check that it exists. If it doesn't, Mixroadie isn't installed: tell the user
to install it first (https://mixroadie.com) and stop.

In every command and config below, use the full path with the user's real
home folder written out (for example `/Users/anna/.mixroadie/venv-audio/bin/roadie`).
AI apps don't expand `~` or `%USERPROFILE%` in their config files.

## Step 2: run `roadie connect`

```sh
~/.mixroadie/venv-audio/bin/roadie connect
```

Windows (PowerShell):

```powershell
& "$env:USERPROFILE\.mixroadie\venv-audio\Scripts\roadie.exe" connect
```

It installs the MCP server if needed and adds Mixroadie to every supported AI
app it finds: Claude Desktop, Claude Code and Codex. It prints one line per
app. It is safe to run again.

If it worked, go to step 4. If it says `No such command 'connect'`, the
installed Mixroadie is older than this command: do step 3 instead.

## Step 3: older Mixroadie only, set it up by hand

### 3a. Install the MCP server

macOS:

```sh
~/.mixroadie/venv-audio/bin/python -m pip install "mcp>=1.2,<2"
```

Windows (PowerShell):

```powershell
& "$env:USERPROFILE\.mixroadie\venv-audio\Scripts\python.exe" -m pip install "mcp>=1.2,<2"
```

### 3b. Add it to each AI app that is installed

Skip any app that isn't installed. Below, `ROADIE` stands for the full path
from step 1.

**Claude Code** (if the `claude` command exists):

```sh
claude mcp remove --scope user mixroadie   # fine if it says there is none
claude mcp add --scope user mixroadie -- ROADIE mcp-server
```

**Codex / ChatGPT app** (if `~/.codex/` exists, or `$CODEX_HOME` is set): in
`~/.codex/config.toml` (or `$CODEX_HOME/config.toml`), add this table, or
replace an existing `[mcp_servers.mixroadie]` table with it. The timeout
matters: Codex's default of 60 seconds is too short for mastering.

```toml
[mcp_servers.mixroadie]
command = "ROADIE"
args = ["mcp-server"]
tool_timeout_sec = 600
```

On Windows, double every backslash in `ROADIE` inside the quotes.

**Claude Desktop** (if it is installed): its config file is

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`, and for the
  Microsoft Store version also
  `%LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude\claude_desktop_config.json`

Create the file if it is missing. Add a `mixroadie` entry under
`mcpServers`, next to any servers already there:

```json
{
  "mcpServers": {
    "mixroadie": {
      "command": "ROADIE",
      "args": ["mcp-server"]
    }
  }
}
```

On Windows, double every backslash in `ROADIE`.

## Step 4: check and tell the user what's next

1. Check the result: for Claude Code, `claude mcp list` should show
   `mixroadie`. For the config files, read them back and check they still
   parse and still have the user's other entries.
2. Tell the user, in plain words, which apps are now connected, and that each
   one needs a restart before Mixroadie shows up in it:
   - **Claude Desktop:** quit it completely (not just close the window) and
     open it again.
   - **Claude Code / Codex:** start a new session.
3. Tell them to restart REAPER once, so Mixroadie's connection to it starts.
4. Tell them how to use it: open the song in REAPER and ask you about it, with
   the song's full path, for example "Run a health check on
   /Users/anna/Music/Song/Song.rpp" or "Mix this song for me". You make the
   decisions Mixroadie asks for and apply the moves they choose. No AI model
   needs to be set up in Mixroadie, and the Mixroadie panel doesn't need to be
   open.

## If something goes wrong

| Problem | What to do |
|---|---|
| pip can't reach the internet | Ask the user to allow network access, or to run the step 2 command themselves in Terminal / PowerShell. |
| "Is the Mixroadie panel open…?" when using a tool later | The song must be open in REAPER, and REAPER restarted once since setup (or the panel opened once). |
| Claude Desktop doesn't show Mixroadie after a restart | Its log is `~/Library/Logs/Claude/mcp-server-mixroadie.log` (macOS) or in `%APPDATA%\Claude\logs\` (Windows). A wrong path in the config is the usual cause. |