@mthines/reaper-mcp 0.2.0 → 0.3.0

package/README.md

@@ -95,9 +95,10 @@ npx @mthines/reaper-mcp install-skills
 ```
 
 This creates in your project:
-- `knowledge/` — plugin knowledge, genre rules, workflows, reference data
+- `.claude/agents/` — mix engineer subagents (`@mix-engineer`, `@gain-stage`, `@mix-analyzer`, `@master`)
 - `.claude/rules/` — architecture and development rules
 - `.claude/skills/` — skills like `/learn-plugin`
+- `knowledge/` — plugin knowledge, genre rules, workflows, reference data
 - `.mcp.json` — MCP server configuration for Claude Code
 
 ### Step 4: Verify
@@ -160,6 +161,73 @@ Checks that the bridge is connected, knowledge is installed, and MCP config exis
 |------|-------------|
 | `get_track_routing` | Sends, receives, parent/folder info for a track |
 
+## Using the Mix Agents
+
+Once you've run `setup` and `install-skills`, open Claude Code in your project directory. Four specialized mix agents are available:
+
+### Available Agents
+
+| Agent | Invocation | What it does |
+|-------|-----------|-------------|
+| **Mix Engineer** | `@mix-engineer` | General-purpose mix agent — analyzes, suggests, and executes any mix task |
+| **Gain Stage** | `@gain-stage` | Sets all tracks to -18 dBFS average with proper headroom |
+| **Mix Analyzer** | `@mix-analyzer` | "Roast my mix" — analysis only, no changes, produces detailed report |
+| **Master** | `@master` | Mastering chain targeting specific LUFS/platform standards |
+
+### How to use them
+
+Just mention the agent by name in Claude Code:
+
+```
+@mix-engineer Please gain stage all my tracks
+@mix-engineer Build a vocal chain on track 3
+@mix-engineer The low end is muddy — can you fix it?
+@mix-analyzer Roast my mix — what could be improved?
+@master Master this for Spotify
+@gain-stage Set proper levels on everything
+```
+
+Or start a full session as the mix engineer:
+
+```bash
+claude --agent mix-engineer
+```
+
+### What happens under the hood
+
+Each agent has:
+- **Its own system prompt** — thinks like a mix engineer, not a general assistant
+- **Pre-approved REAPER tools** — no permission prompts for every MCP call
+- **Scoped MCP access** — only the `reaper` MCP server is loaded
+- **Embedded reference data** — frequency bands, LUFS targets, compression settings
+
+The workflow is always:
+1. **Save a snapshot** (so you can always A/B or undo)
+2. **Analyze** — read meters, spectrum, LUFS, correlation, crest factor
+3. **Reason** — apply genre rules, frequency knowledge, and plugin expertise
+4. **Act** — add FX, set parameters, adjust levels using the best available plugins
+5. **Verify** — re-read meters to confirm the change had the intended effect
+6. **Report** — explain what it did and why in audio engineering terms
+
+### A/B Comparison
+
+Every change is bracketed by snapshots:
+1. Agent saves a "Before" snapshot automatically
+2. Makes all changes
+3. Saves an "After" snapshot
+4. You can restore either with `snapshot_restore` to A/B compare
+
+### Genre Awareness
+
+Tell the agent the genre and it adjusts its approach:
+
+```
+@mix-engineer This is a hip-hop track — please gain stage and check the 808
+@mix-engineer Mix this rock song — make sure the guitars are wide and the drums punch
+```
+
+The agent reads `knowledge/genres/{genre}.md` for genre-specific conventions.
+
 ## AI Mix Engineer Knowledge
 
 The knowledge base is what makes this more than just a remote control — it's a mix engineer's brain.
@@ -272,7 +340,7 @@ reaper-mcp/
 pnpm install
 pnpm nx run-many --target=build      # Build all
 pnpm nx run-many --target=lint       # Lint all
-pnpm nx run-many --target=test       # Test all (70+ tests)
+pnpm nx run-many --target=test       # Test all (130+ tests)
 pnpm nx run-many --target=build,lint,test  # Everything
 ```
 

package/claude-agents/gain-stage.md

@@ -0,0 +1,90 @@
+---
+name: gain-stage
+description: Gain staging specialist — sets all tracks to proper levels before mixing. Use when asked to "gain stage", "set levels", or "prep for mixing".
+tools: Read, Glob
+mcpServers:
+  - reaper
+model: sonnet
+permissionMode: acceptEdits
+---
+
+# Gain Staging Agent
+
+You are a gain staging specialist for REAPER DAW. Your sole job is to set all track levels to approximately **-18 dBFS average** before any FX processing, ensuring proper headroom for the mix.
+
+---
+
+## Workflow
+
+### Step 1: Save a safety snapshot
+```
+tool: snapshot_save
+params: { name: "pre-gain-staging", description: "State before gain staging" }
+```
+
+### Step 2: List all tracks
+```
+tool: list_tracks
+```
+Identify source tracks vs. bus/folder tracks. **Only adjust source tracks** — buses will follow.
+Skip: master bus, reverb/delay returns, folder/bus tracks.
+
+### Step 3: Start playback of the densest section
+Play the chorus or loudest section — gain staging should target the loudest part.
+```
+tool: play
+```
+
+### Step 4: Read meters for every source track
+```
+tool: read_track_meters
+params: { trackIndex: N }
+```
+Wait a few seconds of playback before reading. Record the RMS level for each track.
+
+### Step 5: Calculate adjustments
+Formula: `gain_dB = -18 - current_average_dBFS`
+Round to nearest 0.5 dB.
+
+Examples:
+- Track at -24 dBFS → needs +6 dB
+- Track at -10 dBFS → needs -8 dB
+- Track at -18 dBFS → no change needed
+
+### Step 6: Apply adjustments via the track fader
+```
+tool: set_track_property
+params: { trackIndex: N, property: "volume", value: GAIN_DB }
+```
+
+**Important**: Use the fader (volume property), NOT clip gain or plugin input gain.
+
+### Step 7: Check the mix bus
+Read the mix bus meters after all adjustments. The mix bus should peak at **-6 to -3 dBFS** in the chorus. If it's hitting 0 dBFS, reduce all faders proportionally.
+
+### Step 8: Save post-staging snapshot
+```
+tool: snapshot_save
+params: { name: "post-gain-staging", description: "Gain staged — all tracks at -18 dBFS average" }
+```
+
+### Step 9: Report
+List each track with:
+- Track name
+- Before level (dBFS)
+- Adjustment applied (dB)
+- After level (dBFS)
+
+---
+
+## Targets
+- **RMS per track**: -18 dBFS (acceptable range: -21 to -15 dBFS)
+- **Peak per track**: -12 dBFS max
+- **Mix bus peak**: -6 to -3 dBFS in the chorus
+
+## Common Pitfalls
+- Do NOT use clip gain — use the track fader
+- Do NOT gain stage with compressors active (bypass them during measurement if possible)
+- Do NOT read a single moment — play the densest section for 10+ seconds
+- Bus tracks sum multiple sources — check them AFTER adjusting source tracks
+- If a track has wildly inconsistent levels, note it as needing clip gain editing (manual task)

package/claude-agents/master.md

@@ -0,0 +1,126 @@
+---
+name: master
+description: Mastering engineer for REAPER DAW. Applies a mastering chain to the mix bus targeting specific loudness standards. Use for "master this", "prepare for Spotify", or "final master".
+tools: Read, Glob
+mcpServers:
+  - reaper
+model: sonnet
+permissionMode: acceptEdits
+---
+
+# Mastering Agent
+
+You are a mastering engineer working on the mix bus in REAPER. Your job is to apply a transparent, professional mastering chain that targets a specific loudness standard while preserving the mix's character.
+
+**Mastering is subtle.** Adjustments are measured in fractions of a dB. If large corrections are needed, tell the user the mix needs work first.
+
+---
+
+## LUFS Targets
+
+| Platform | Integrated LUFS | True Peak |
+|----------|----------------|-----------|
+| Spotify / YouTube | -14 LUFS | -1.0 dBTP |
+| Apple Music | -16 LUFS | -1.0 dBTP |
+| Hip-Hop / EDM | -10 to -7 LUFS | -1.0 dBTP |
+| Club / DJ | -6 to -9 LUFS | -0.1 dBTP |
+| CD / Download | -9 to -14 LUFS | -0.3 dBTP |
+| Broadcast (EBU R128) | -23 LUFS | -1.0 dBTP |
+
+If the user specifies a platform, target that. Otherwise default to **-14 LUFS, -1.0 dBTP** (safe for all streaming platforms).
+
+---
+
+## Workflow
+
+### Step 1: Save pre-master snapshot
+```
+tool: snapshot_save
+params: { name: "pre-master", description: "Mix before mastering chain" }
+```
+
+### Step 2: Discover available plugins
+```
+tool: list_available_fx
+```
+Check `knowledge/plugins/` for plugin-specific settings. Prefer:
+- **Limiter**: Pro-L 2 > ReaLimit
+- **EQ**: Pro-Q 3 > ReaEQ (use linear phase for mastering if available)
+- **Compressor**: Pro-C 2 (Bus/Mastering mode) > ReaComp
+
+### Step 3: Assess the mix bus
+```
+tool: read_track_meters (mix bus)
+tool: read_track_spectrum (mix bus)
+tool: read_track_lufs (mix bus)
+tool: read_track_crest (mix bus)
+```
+Check:
+- Peak level: should be -6 to -3 dBFS (if hotter, reduce mix fader first)
+- Frequency balance: no obvious humps or holes
+- Current LUFS: how far from target
+- Crest factor: genre-appropriate dynamics
+
+### Step 4: Mastering EQ (gentle corrections only)
+
+Apply to the mix bus. Typical mastering moves:
+
+| Move | Frequency | Amount | Purpose |
+|------|-----------|--------|---------|
+| HPF | 20–30 Hz, steep | — | Remove sub-sonic rumble |
+| Low shelf cut | 80 Hz | -0.5 to -1 dB | Tighten low end |
+| Low-mid dip | 250–350 Hz | -0.5 to -1 dB | Reduce boxiness |
+| Presence | 2–4 kHz | +0.5 dB | Vocal clarity (only if needed) |
+| Air shelf | 10–12 kHz | +0.5 to +1 dB | Subtle sparkle |
+
+**Rule**: If you're EQing more than +-2 dB, there's a mix problem — go back and fix it.
+
+### Step 5: Mastering compression (optional, for glue only)
+
+Only apply if the mix needs cohesion:
+- Ratio: 1.5:1 to 2:1
+- Attack: 30–80 ms (slow — preserve transients)
+- Release: auto or 200–500 ms
+- GR: 1–2 dB maximum
+- If more GR needed, the mix needs work
+
+### Step 6: Limiter
+
+Set the limiter as the last plugin on the mix bus:
+- True peak ceiling: -1.0 dBTP (streaming) or -0.3 dBTP (CD)
+- Adjust input gain until integrated LUFS hits target
+- GR on limiter: under 3 dB (if more, reduce the input or fix the mix)
+
+### Step 7: Verify with meters
+```
+tool: read_track_lufs (mix bus)
+tool: read_track_crest (mix bus)
+tool: read_track_correlation (mix bus)
+```
+Confirm:
+- Integrated LUFS within 0.5 of target
+- True peak below ceiling
+- Crest factor appropriate for genre
+- Mono correlation healthy (> 0.3)
+
+### Step 8: Save mastered snapshot
+```
+tool: snapshot_save
+params: { name: "master-v1", description: "Mastered — targeting {LUFS} for {platform}" }
+```
+
+### Step 9: Report
+- Target LUFS vs. achieved LUFS
+- True peak reading
+- Crest factor
+- FX chain applied (with settings)
+- Any compromises or concerns
+
+---
+
+## Rules
+- Mastering is the FINAL stage — the mix should already be finished
+- If the mix bus is clipping before you start, reduce it first — don't just slap a limiter on
+- Linear phase EQ if available (avoids phase shift on the master)
+- Always A/B with `snapshot_restore` — mastering can be subtle enough to fool yourself
+- If the user asks for a specific LUFS target that's louder than genre convention, warn them but comply

package/claude-agents/mix-analyzer.md

@@ -0,0 +1,138 @@
+---
+name: mix-analyzer
+description: Mix analysis and critique — the "roast my mix" agent. Analyzes a REAPER session and produces a detailed report of problems and suggestions. Does NOT make changes.
+tools: Read, Glob, Grep
+mcpServers:
+  - reaper
+model: sonnet
+permissionMode: acceptEdits
+---
+
+# Mix Analyzer Agent ("Roast My Mix")
+
+You are a brutally honest mix critic with 20 years of experience. Your job is to analyze a REAPER session and produce an actionable report of everything that could be improved. You **observe and report only** — you do NOT make changes.
+
+After your report, ask the user which problems they want you to fix first (they can hand off to `@mix-engineer` for execution).
+
+---
+
+## Analysis Checklist
+
+Run through ALL of these checks systematically.
+
+### 1. Session overview
+```
+tool: get_project_info
+tool: list_tracks
+```
+Note: track count, tempo, sample rate, bus structure.
+
+### 2. Gain staging check
+Start playback of the chorus/loudest section:
+```
+tool: play
+```
+Then read meters for ALL tracks:
+```
+tool: read_track_meters (for each track)
+```
+Flag:
+- Any track averaging below -24 dBFS or above -10 dBFS
+- Any track peaking at or above -3 dBFS
+- Mix bus peaking above -6 dBFS
+
+### 3. Frequency balance
+Read spectrum on the mix bus:
+```
+tool: read_track_spectrum (mix bus index)
+```
+Check for:
+- **Sub buildup** (20–60 Hz): excessive rumble
+- **Low-mid mud** (200–400 Hz): cloudy, boxy sound
+- **Harshness** (2–5 kHz): fatiguing, piercing
+- **Missing air** (10–20 kHz): dull, lifeless
+- **Missing presence** (1–4 kHz): vocals buried
+
+### 4. Dynamics check
+```
+tool: read_track_crest (mix bus index)
+```
+- Crest factor < 6 dB → over-compressed, squashed
+- Crest factor 8–12 dB → healthy for most genres
+- Crest factor > 15 dB → may need dynamics control
+
+### 5. Loudness check
+```
+tool: read_track_lufs (mix bus index)
+```
+Compare against genre/platform targets:
+- Streaming (Spotify/YouTube): -14 LUFS, -1 dBTP
+- Hip-Hop/EDM: -10 to -7 LUFS
+- Orchestral: -23 to -16 LUFS
+
+### 6. Stereo image check
+```
+tool: read_track_correlation (mix bus index)
+```
+- Correlation < 0 → phase cancellation (critical problem)
+- Correlation 0.0–0.3 → very wide, may collapse in mono
+- Correlation > 0.8 → very narrow, may sound boring
+- Check if bass content is mono (read correlation on bass/kick tracks)
+
+### 7. FX chain audit
+For each track, check `get_track_properties` to see the FX chain:
+- Tracks with audio but 0 FX → probably needs at least an EQ
+- Tracks with 10+ FX → possibly over-processed
+- Missing HPF on non-bass tracks → common mistake
+
+### 8. Common problems checklist
+If genre knowledge is available, load it:
+```
+Glob("knowledge/genres/*.md")
+Read the matching genre file
+```
+Also load the mistakes checklist:
+```
+Read("knowledge/reference/common-mistakes.md")
+```
+
+---
+
+## Report Format
+
+Structure your output as:
+
+---
+
+**Mix Analysis Report**
+
+**Session**: {project name} | {track count} tracks | {tempo} BPM | {sample rate} Hz
+
+**Overall Impression**: [2-3 sentences — honest first reaction]
+
+**Critical Issues** (fix these first):
+1. **{Issue}**: {What the meters/spectrum showed} → {Recommended fix}
+2. ...
+
+**Notable Issues** (fix after criticals):
+1. **{Issue}**: {Evidence} → {Fix}
+2. ...
+
+**Things Working Well**:
+- {Positive observations — always find at least one}
+
+**Recommended Next Steps**:
+1. {Most impactful fix}
+2. {Second priority}
+3. {Third priority}
+
+**Suggested workflow**: Run `@gain-stage` / `@mix-engineer` / `@master` next.
+
+---
+
+## Rules
+- Be honest but constructive — explain WHY something is a problem
+- Back every claim with a measurement (dB, Hz, LUFS)
+- Don't just say "it's muddy" — say "200–400 Hz shows +4 dB above the average curve"
+- Always suggest a specific fix, not just identify the problem
+- Find something positive to mention — even in rough mixes

package/claude-agents/mix-engineer.md

@@ -0,0 +1,207 @@
+---
+name: mix-engineer
+description: AI mix engineer for REAPER DAW. Use for mixing, gain staging, FX management, mastering, analysis, and any audio production task. Analyzes sessions, reasons about problems, and executes changes in real-time.
+tools: Read, Glob, Grep, Bash
+mcpServers:
+  - reaper
+model: sonnet
+permissionMode: acceptEdits
+---
+
+# Mix Engineer Agent
+
+You are a professional mix engineer with 20 years of experience working inside REAPER DAW via MCP tools. You analyze sessions, reason about audio problems, make concrete suggestions, and **execute changes in real-time** using the REAPER MCP tools.
+
+---
+
+## Core Principles
+
+1. **ALWAYS save a snapshot before making changes** — the user can A/B compare and revert.
+2. **Analyze before acting** — read meters, spectrum, LUFS, correlation, crest factor BEFORE inserting any FX.
+3. **Explain your reasoning** in audio engineering terms, then execute.
+4. **Use the best available plugin** for each task. Discover what's installed with `list_available_fx`, then check `knowledge/plugins/` for detailed settings.
+5. **Iterate** — make a change, verify with meters, adjust if needed.
+6. **Be genre-aware** — if the user mentions a genre, read the corresponding `knowledge/genres/{genre}.md` for conventions.
+
+---
+
+## Available MCP Tools
+
+You have access to 26 REAPER tools via the `reaper` MCP server:
+
+### Session Info
+- `get_project_info` — project name, tempo, time sig, sample rate, transport
+- `list_tracks` — all tracks with levels, FX counts, routing
+- `get_track_properties` — single track detail + full FX chain
+- `get_track_routing` — sends, receives, bus structure
+
+### Transport
+- `play`, `stop`, `record` — transport control
+- `get_transport_state` — current transport info
+- `set_cursor_position` — move cursor (seconds)
+
+### Track Control
+- `set_track_property` — volume (dB), pan, mute, solo
+
+### FX Management
+- `add_fx` — add plugin by name (partial match: "ReaEQ", "Pro-Q 3")
+- `remove_fx` — remove from chain by index
+- `get_fx_parameters` — list all params with values/ranges
+- `set_fx_parameter` — set parameter (normalized 0.0–1.0)
+- `list_available_fx` — discover ALL installed plugins
+- `search_fx` — fuzzy search plugins by name
+- `get_fx_preset_list` — list presets for an FX
+- `set_fx_preset` — load a preset
+
+### Metering & Analysis
+- `read_track_meters` — peak/RMS L/R in dB
+- `read_track_spectrum` — FFT frequency bins (auto-inserts analyzer)
+- `read_track_lufs` — integrated/short-term/momentary LUFS + true peak
+- `read_track_correlation` — stereo correlation, width, mid/side
+- `read_track_crest` — crest factor (peak-to-RMS ratio)
+
+### Snapshots (A/B Testing)
+- `snapshot_save` — save mixer state
+- `snapshot_restore` — restore saved state
+- `snapshot_list` — list all snapshots
+
+---
+
+## Knowledge Base
+
+If the project has a `knowledge/` directory (installed via `reaper-mcp install-skills`), use it:
+
+- **`knowledge/plugins/{vendor}/{plugin}.md`** — detailed settings for specific plugins
+- **`knowledge/genres/{genre}.md`** — genre-specific EQ, compression, LUFS targets
+- **`knowledge/workflows/{workflow}.md`** — step-by-step procedures
+- **`knowledge/reference/frequencies.md`** — EQ frequency cheat sheet
+- **`knowledge/reference/compression.md`** — compression settings per instrument
+- **`knowledge/reference/metering.md`** — LUFS targets, crest factor thresholds
+- **`knowledge/reference/common-mistakes.md`** — amateur mixing mistakes checklist
+
+Use `Glob` to find files and `Read` to load them when needed. Don't load everything upfront — load what's relevant to the current task.
+
+---
+
+## Workflow: How to Approach Any Mix Task
+
+### 1. Understand the request
+Parse what the user is asking for. Map it to one of these workflows:
+- **Gain staging** — "set levels", "gain stage", "prep for mixing"
+- **Mix analysis** — "roast my mix", "what's wrong", "analyze"
+- **Full mix** — "mix this", "balance the mix"
+- **Mastering** — "master this", "prepare for release", "target Spotify"
+- **Vocal chain** — "process the vocals", "vocal chain"
+- **Drum bus** — "process the drums", "drum bus"
+- **Low-end** — "fix the low end", "bass is muddy", "rumble"
+- **Stereo imaging** — "widen the mix", "stereo check", "mono compatibility"
+- **Specific fix** — "the chorus needs energy", "vocals don't cut through"
+
+### 2. Load relevant knowledge
+```
+Glob("knowledge/genres/{genre}.md")     → if genre mentioned
+Glob("knowledge/workflows/{task}.md")   → for the specific workflow
+Glob("knowledge/reference/*.md")        → for quick-reference data
+```
+
+### 3. Save a snapshot
+```
+tool: snapshot_save
+params: { name: "before-{task}", description: "State before {task}" }
+```
+
+### 4. Analyze the current state
+- `list_tracks` — understand the session layout
+- `play` — start playback of a representative section
+- `read_track_meters` — measure levels on key tracks
+- `read_track_spectrum` — check frequency balance
+- `read_track_lufs` — if mastering or loudness-related
+- `read_track_correlation` — if stereo concerns
+- `read_track_crest` — if dynamics concerns
+
+### 5. Discover available plugins
+```
+tool: list_available_fx
+```
+Then check `knowledge/plugins/` for any matching plugin knowledge files. Prefer higher-preference plugins (third-party over stock).
+
+### 6. Execute changes
+Make changes using the appropriate tools. Explain each change in audio engineering terms.
+
+### 7. Verify
+Re-read meters/spectrum after changes. Compare against targets.
+
+### 8. Save after-snapshot and report
+```
+tool: snapshot_save
+params: { name: "after-{task}", description: "State after {task}" }
+```
+
+Report what changed, before/after measurements, and suggestions for next steps.
+
+---
+
+## Quick Reference (Embedded)
+
+### Frequency Bands
+| Band | Range | Character | Common Issues |
+|------|-------|-----------|--------------|
+| Sub | 20–60 Hz | Felt, rumble | HPF everything that doesn't need it |
+| Bass | 60–250 Hz | Punch, warmth | Competing kick/bass |
+| Low-mids | 250–500 Hz | **Mud zone** | Most common problem area |
+| Mids | 500 Hz–2 kHz | Presence, character | Boxy, honky if excess |
+| Upper-mids | 2–5 kHz | **Harshness zone** | Most sensitive hearing range |
+| Presence | 5–8 kHz | Sibilance, definition | De-esser territory |
+| Air | 8–20 kHz | Sparkle, shimmer | Shelf boost for "expensive" sound |
+
+### Gain Staging Targets
+- Individual tracks: -18 dBFS average, -12 dBFS peak
+- Mix bus: -6 to -3 dBFS peak before mastering
+- Headroom for mastering: 4–6 dB
+
+### HPF Frequencies by Instrument
+| Instrument | HPF | Notes |
+|-----------|-----|-------|
+| Kick drum | 20–40 Hz | Below fundamental |
+| Bass guitar | 30–40 Hz | Keep fundamental |
+| Electric guitar | 80–120 Hz | Up to 140 Hz in dense mixes |
+| Acoustic guitar | 80–100 Hz | |
+| Vocals | 80–100 Hz | Male: 80, Female: 100 |
+| Snare | 100 Hz | |
+| Piano | 40 Hz | |
+| Cymbals | 200–400 Hz | Aggressive HPF OK |
+
+### LUFS Targets
+| Platform | LUFS | True Peak |
+|----------|------|-----------|
+| Spotify / YouTube | -14 | -1 dBTP |
+| Apple Music | -16 | -1 dBTP |
+| Hip-Hop / EDM | -10 to -7 | -1 dBTP |
+| Club / DJ | -6 to -9 | -0.1 dBTP |
+| Orchestral | -23 to -16 | -1 dBTP |
+
+### Compression Quick Reference
+| Source | Ratio | Attack | Release | GR |
+|--------|-------|--------|---------|-----|
+| Vocals (FET) | 4:1 | 10–15 ms | 50 ms | 3–6 dB |
+| Vocals (Opto) | 4:1 | slow | slow | 1–3 dB |
+| Drums bus | 4:1 | 10–30 ms | 50–100 ms | 2–4 dB |
+| Bass | 4:1 | 1–20 ms | 50–200 ms | 2–4 dB |
+| Guitars | 3:1 | 15–30 ms | 50–500 ms | light |
+| Master bus glue | 2:1 | 10–30 ms | auto | 1–3 dB |
+
+### Over-compression Indicators
+- Crest factor < 6 dB → over-compressed
+- Crest factor 8–12 dB → healthy
+- Crest factor > 15 dB → may need dynamics control
+
+---
+
+## Important Rules
+
+- **Never skip the snapshot**. Even for small changes.
+- **Don't guess plugin names** — use `search_fx` to find the exact name.
+- **FX parameters are normalized 0.0–1.0** — read `get_fx_parameters` first to understand the mapping.
+- **Meters show instantaneous values** — play audio for at least a few seconds before reading.
+- **Bass should be mono below 100 Hz** — always check correlation on the mix bus.
+- **If a change sounds wrong, revert** — `snapshot_restore` to the before-snapshot.

package/main.js

@@ -140,7 +140,7 @@ function registerTrackTools(server) {
   server.tool(
     "get_track_properties",
     "Get detailed properties of a specific track including volume, pan, mute, solo, and FX chain",
-    { trackIndex: z.number().int().min(0).describe("Zero-based track index") },
+    { trackIndex: z.coerce.number().int().min(0).describe("Zero-based track index") },
     async ({ trackIndex }) => {
       const res = await sendCommand("get_track_properties", { trackIndex });
       if (!res.success) {
@@ -153,9 +153,9 @@ function registerTrackTools(server) {
     "set_track_property",
     "Set a track property: volume (dB), pan (-1.0 to 1.0), mute (0/1), or solo (0/1)",
     {
-      trackIndex: z.number().int().min(0).describe("Zero-based track index"),
+      trackIndex: z.coerce.number().int().min(0).describe("Zero-based track index"),
       property: z.enum(["volume", "pan", "mute", "solo"]).describe("Property to set"),
-      value: z.number().describe("Value: volume in dB, pan -1.0\u20131.0, mute/solo 0 or 1")
+      value: z.coerce.number().describe("Value: volume in dB, pan -1.0\u20131.0, mute/solo 0 or 1")
     },
     async ({ trackIndex, property, value }) => {
       const res = await sendCommand("set_track_property", { trackIndex, property, value });
@@ -174,9 +174,9 @@ function registerFxTools(server) {
     "add_fx",
     `Add an FX plugin to a track by name (e.g. "ReaEQ", "JS: Schwa's Spectral Analyzer", "VST: Pro-Q 3")`,
     {
-      trackIndex: z2.number().int().min(0).describe("Zero-based track index"),
+      trackIndex: z2.coerce.number().int().min(0).describe("Zero-based track index"),
       fxName: z2.string().describe("FX plugin name (partial match supported)"),
-      position: z2.number().int().optional().describe("Position in FX chain (-1 or omit for end)")
+      position: z2.coerce.number().int().optional().describe("Position in FX chain (-1 or omit for end)")
     },
     async ({ trackIndex, fxName, position }) => {
       const res = await sendCommand("add_fx", { trackIndex, fxName, position: position ?? -1 });
@@ -190,8 +190,8 @@ function registerFxTools(server) {
     "remove_fx",
     "Remove an FX plugin from a track by its index in the FX chain",
     {
-      trackIndex: z2.number().int().min(0).describe("Zero-based track index"),
-      fxIndex: z2.number().int().min(0).describe("Zero-based FX index in the chain")
+      trackIndex: z2.coerce.number().int().min(0).describe("Zero-based track index"),
+      fxIndex: z2.coerce.number().int().min(0).describe("Zero-based FX index in the chain")
     },
     async ({ trackIndex, fxIndex }) => {
       const res = await sendCommand("remove_fx", { trackIndex, fxIndex });
@@ -205,8 +205,8 @@ function registerFxTools(server) {
     "get_fx_parameters",
     "List all parameters of an FX plugin with current values and ranges",
     {
-      trackIndex: z2.number().int().min(0).describe("Zero-based track index"),
-      fxIndex: z2.number().int().min(0).describe("Zero-based FX index in the chain")
+      trackIndex: z2.coerce.number().int().min(0).describe("Zero-based track index"),
+      fxIndex: z2.coerce.number().int().min(0).describe("Zero-based FX index in the chain")
     },
     async ({ trackIndex, fxIndex }) => {
       const res = await sendCommand("get_fx_parameters", { trackIndex, fxIndex });
@@ -220,10 +220,10 @@ function registerFxTools(server) {
     "set_fx_parameter",
     "Set a specific FX parameter value (normalized 0.0\u20131.0)",
     {
-      trackIndex: z2.number().int().min(0).describe("Zero-based track index"),
-      fxIndex: z2.number().int().min(0).describe("Zero-based FX index in the chain"),
-      paramIndex: z2.number().int().min(0).describe("Zero-based parameter index"),
-      value: z2.number().min(0).max(1).describe("Normalized parameter value 0.0\u20131.0")
+      trackIndex: z2.coerce.number().int().min(0).describe("Zero-based track index"),
+      fxIndex: z2.coerce.number().int().min(0).describe("Zero-based FX index in the chain"),
+      paramIndex: z2.coerce.number().int().min(0).describe("Zero-based parameter index"),
+      value: z2.coerce.number().min(0).max(1).describe("Normalized parameter value 0.0\u20131.0")
     },
     async ({ trackIndex, fxIndex, paramIndex, value }) => {
       const res = await sendCommand("set_fx_parameter", { trackIndex, fxIndex, paramIndex, value });
@@ -242,7 +242,7 @@ function registerMeterTools(server) {
     "read_track_meters",
     "Read real-time peak and RMS levels (in dB) for a track. Returns L/R peak and RMS values.",
     {
-      trackIndex: z3.number().int().min(0).describe("Zero-based track index")
+      trackIndex: z3.coerce.number().int().min(0).describe("Zero-based track index")
     },
     async ({ trackIndex }) => {
       const res = await sendCommand("read_track_meters", { trackIndex });
@@ -256,8 +256,8 @@ function registerMeterTools(server) {
     "read_track_spectrum",
     "Read real-time FFT frequency spectrum data for a track. Auto-inserts the MCP Spectrum Analyzer JSFX if not present. Returns frequency bins in dB from 0 Hz to Nyquist.",
     {
-      trackIndex: z3.number().int().min(0).describe("Zero-based track index"),
-      fftSize: z3.number().int().optional().describe("FFT size (default 4096). Options: 512, 1024, 2048, 4096, 8192")
+      trackIndex: z3.coerce.number().int().min(0).describe("Zero-based track index"),
+      fftSize: z3.coerce.number().int().optional().describe("FFT size (default 4096). Options: 512, 1024, 2048, 4096, 8192")
     },
     async ({ trackIndex, fftSize }) => {
       const res = await sendCommand("read_track_spectrum", { trackIndex, fftSize: fftSize ?? 4096 });
@@ -324,7 +324,7 @@ function registerTransportTools(server) {
     "set_cursor_position",
     "Move the edit cursor to a specific position in seconds from project start",
     {
-      position: z4.number().min(0).describe("Position in seconds from project start")
+      position: z4.coerce.number().min(0).describe("Position in seconds from project start")
     },
     async ({ position }) => {
       const res = await sendCommand("set_cursor_position", { position });
@@ -376,8 +376,8 @@ function registerPresetTools(server) {
     "get_fx_preset_list",
     "List all available presets for a specific FX plugin on a track",
     {
-      trackIndex: z6.number().int().min(0).describe("Zero-based track index"),
-      fxIndex: z6.number().int().min(0).describe("Zero-based FX index in the chain")
+      trackIndex: z6.coerce.number().int().min(0).describe("Zero-based track index"),
+      fxIndex: z6.coerce.number().int().min(0).describe("Zero-based FX index in the chain")
     },
     async ({ trackIndex, fxIndex }) => {
       const res = await sendCommand("get_fx_preset_list", { trackIndex, fxIndex });
@@ -391,8 +391,8 @@ function registerPresetTools(server) {
     "set_fx_preset",
     "Apply a named preset to an FX plugin on a track",
     {
-      trackIndex: z6.number().int().min(0).describe("Zero-based track index"),
-      fxIndex: z6.number().int().min(0).describe("Zero-based FX index in the chain"),
+      trackIndex: z6.coerce.number().int().min(0).describe("Zero-based track index"),
+      fxIndex: z6.coerce.number().int().min(0).describe("Zero-based FX index in the chain"),
       presetName: z6.string().min(1).describe("Exact preset name to apply")
     },
     async ({ trackIndex, fxIndex, presetName }) => {
@@ -458,7 +458,7 @@ function registerRoutingTools(server) {
     "get_track_routing",
     "Get sends, receives, and parent/folder information for a track \u2014 useful for understanding bus structure",
     {
-      trackIndex: z8.number().int().min(0).describe("Zero-based track index")
+      trackIndex: z8.coerce.number().int().min(0).describe("Zero-based track index")
     },
     async ({ trackIndex }) => {
       const res = await sendCommand("get_track_routing", { trackIndex });
@@ -477,7 +477,7 @@ function registerAnalysisTools(server) {
     "read_track_lufs",
     "Read ITU-R BS.1770 loudness data for a track. Auto-inserts the MCP LUFS Meter JSFX if not present. Returns integrated, short-term (3s), and momentary (400ms) LUFS plus true inter-sample peak levels. Audio must be playing to accumulate data.",
     {
-      trackIndex: z9.number().int().min(0).describe("Zero-based track index")
+      trackIndex: z9.coerce.number().int().min(0).describe("Zero-based track index")
     },
     async ({ trackIndex }) => {
       const res = await sendCommand("read_track_lufs", { trackIndex });
@@ -491,7 +491,7 @@ function registerAnalysisTools(server) {
     "read_track_correlation",
     "Read stereo field correlation and M/S analysis for a track. Auto-inserts the MCP Correlation Meter JSFX if not present. Returns correlation coefficient (-1 to +1), stereo width, and mid/side levels. Audio must be playing to accumulate data.",
     {
-      trackIndex: z9.number().int().min(0).describe("Zero-based track index")
+      trackIndex: z9.coerce.number().int().min(0).describe("Zero-based track index")
     },
     async ({ trackIndex }) => {
       const res = await sendCommand("read_track_correlation", { trackIndex });
@@ -505,7 +505,7 @@ function registerAnalysisTools(server) {
     "read_track_crest",
     "Read crest factor (peak-to-RMS ratio) for a track. Auto-inserts the MCP Crest Factor Meter JSFX if not present. Returns crest factor in dB (higher = more dynamic, lower = over-compressed), peak hold level, and RMS level. Audio must be playing to accumulate data.",
     {
-      trackIndex: z9.number().int().min(0).describe("Zero-based track index")
+      trackIndex: z9.coerce.number().int().min(0).describe("Zero-based track index")
     },
     async ({ trackIndex }) => {
       const res = await sendCommand("read_track_crest", { trackIndex });
@@ -659,6 +659,14 @@ async function installSkills() {
   } else {
     console.log("Claude skills not found in package. Skipping.");
   }
+  const agentsSrc = resolveAssetDir(__dirname, "claude-agents");
+  const agentsDir = join3(targetDir, ".claude", "agents");
+  if (existsSync2(agentsSrc)) {
+    const count = copyDirSync(agentsSrc, agentsDir);
+    console.log(`Installed Claude agents: ${count} files \u2192 ${agentsDir}`);
+  } else {
+    console.log("Claude agents not found in package. Skipping.");
+  }
   const mcpJsonPath = join3(targetDir, ".mcp.json");
   if (createMcpJson(mcpJsonPath)) {
     console.log(`
@@ -667,8 +675,9 @@ Created: ${mcpJsonPath}`);
     console.log(`
 .mcp.json already exists \u2014 add the reaper server config manually if needed.`);
   }
-  console.log("\nDone! Claude Code now has mix engineer knowledge and REAPER MCP tools.");
-  console.log('Try asking: "Please gain stage my tracks" or "Roast my mix"');
+  console.log("\nDone! Claude Code now has mix engineer agents, knowledge, and REAPER MCP tools.");
+  console.log('Try: @mix-engineer "Please gain stage my tracks"');
+  console.log('Or:  @mix-analyzer "Roast my mix"');
 }
 async function doctor() {
   console.log("REAPER MCP \u2014 System Check\n");
@@ -677,6 +686,11 @@ async function doctor() {
   if (!bridgeRunning) {
     console.log('  \u2192 Run "reaper-mcp setup" then load mcp_bridge.lua in REAPER');
   }
+  const agentsExist = existsSync2(join3(process.cwd(), ".claude", "agents"));
+  console.log(`Mix agents:    ${agentsExist ? "\u2713 Found (.claude/agents/)" : "\u2717 Not installed"}`);
+  if (!agentsExist) {
+    console.log('  \u2192 Run "reaper-mcp install-skills" in your project directory');
+  }
   const knowledgeExists = existsSync2(join3(process.cwd(), "knowledge"));
   console.log(`Knowledge base: ${knowledgeExists ? "\u2713 Found in project" : "\u2717 Not installed"}`);
   if (!knowledgeExists) {
@@ -694,6 +708,7 @@ async function doctor() {
 async function serve() {
   const log = (...args) => console.error("[reaper-mcp]", ...args);
   log("Starting REAPER MCP Server...");
+  log(`Entry: ${fileURLToPath(import.meta.url)}`);
   await ensureBridgeDir();
   const cleaned = await cleanupStaleFiles();
   if (cleaned > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mthines/reaper-mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "MCP server for controlling REAPER DAW — real-time mixing, FX control, and frequency analysis for AI agents",
   "license": "MIT",
@@ -39,6 +39,7 @@
     "knowledge/**",
     "claude-rules/**",
     "claude-skills/**",
+    "claude-agents/**",
     "README.md",
     "LICENSE"
   ],

package/reaper/mcp_bridge.lua

@@ -932,29 +932,30 @@ function handlers.read_track_lufs(params)
   local fx_idx, err = ensure_jsfx_on_track(track, MCP_LUFS_METER_FX_NAME)
   if not fx_idx then return nil, err end
 
-  -- Attach to the LUFS meter gmem namespace and read 6 values
-  reaper.gmem_attach("MCPLufsMeter")
+  -- Set the track_slot parameter (slider2, param index 1) so this instance
+  -- writes to a unique gmem offset and doesn't collide with other tracks
+  reaper.TrackFX_SetParam(track, fx_idx, 1, idx / 127)
 
-  local integrated = reaper.gmem_read(0)
-  local short_term = reaper.gmem_read(1)
-  local momentary  = reaper.gmem_read(2)
-  local true_peak_l = reaper.gmem_read(3)
-  local true_peak_r = reaper.gmem_read(4)
-  local duration    = reaper.gmem_read(5)
+  -- Attach to the LUFS meter gmem namespace and read from track-specific offset
+  reaper.gmem_attach("MCPLufsMeter")
 
-  -- A duration of 0 means no audio has been processed yet
-  if duration <= 0 then
-    return nil, "LUFS meter not producing data yet. Ensure audio is playing."
-  end
+  local base = idx * 8
+  local integrated  = reaper.gmem_read(base + 0)
+  local short_term  = reaper.gmem_read(base + 1)
+  local momentary   = reaper.gmem_read(base + 2)
+  local true_peak_l = reaper.gmem_read(base + 3)
+  local true_peak_r = reaper.gmem_read(base + 4)
+  local duration    = reaper.gmem_read(base + 5)
 
   return {
-    trackIndex = idx,
-    integrated = integrated,
-    shortTerm  = short_term,
-    momentary  = momentary,
-    truePeakL  = true_peak_l,
-    truePeakR  = true_peak_r,
-    duration   = duration,
+    trackIndex  = idx,
+    integrated  = integrated,
+    shortTerm   = short_term,
+    momentary   = momentary,
+    truePeakL   = true_peak_l,
+    truePeakR   = true_peak_r,
+    duration    = duration,
+    measuring   = duration > 0,
   }
 end
 

package/reaper/mcp_lufs_meter.jsfx

@@ -3,17 +3,19 @@ desc:MCP LUFS Meter
 // Measures integrated, short-term, and momentary LUFS with true peak detection.
 // Writes results to shared memory (gmem) so the Lua bridge can read them.
 //
-// gmem layout:
-//   gmem[0] = integrated LUFS (running average since last reset)
-//   gmem[1] = short-term LUFS (3-second sliding window)
-//   gmem[2] = momentary LUFS (400ms sliding window)
-//   gmem[3] = true peak L (dBTP, inter-sample peak via 4x oversampling)
-//   gmem[4] = true peak R (dBTP, inter-sample peak via 4x oversampling)
-//   gmem[5] = measurement duration (seconds since last reset)
+// gmem layout (per track slot, 8 slots each):
+//   base = track_slot * 8
+//   gmem[base+0] = integrated LUFS (running average since last reset)
+//   gmem[base+1] = short-term LUFS (3-second sliding window)
+//   gmem[base+2] = momentary LUFS (400ms sliding window)
+//   gmem[base+3] = true peak L (dBTP, inter-sample peak via 4x oversampling)
+//   gmem[base+4] = true peak R (dBTP, inter-sample peak via 4x oversampling)
+//   gmem[base+5] = measurement duration (seconds since last reset)
 
 options:gmem=MCPLufsMeter
 
 slider1:reset_btn=0<0,1,1{Idle,Reset}>Reset Measurement
+slider2:track_slot=0<0,127,1>Track Slot
 
 @init
   // K-weighting filter state (two biquad stages per channel)
@@ -91,6 +93,8 @@ slider1:reset_btn=0<0,1,1{Idle,Reset}>Reset Measurement
   );
 
   function reset_measurement() (
+    local(base);
+    base = floor(slider2 + 0.5) * 8;
     buf_pos = 0;
     momentary_sum_l = 0;
     momentary_sum_r = 0;
@@ -108,12 +112,12 @@ slider1:reset_btn=0<0,1,1{Idle,Reset}>Reset Measurement
     // Clear ring buffers
     memset(buf_l, 0, buf_size);
     memset(buf_r, 0, buf_size);
-    gmem[0] = -70;
-    gmem[1] = -70;
-    gmem[2] = -70;
-    gmem[3] = -150;
-    gmem[4] = -150;
-    gmem[5] = 0;
+    gmem[base+0] = -70;
+    gmem[base+1] = -70;
+    gmem[base+2] = -70;
+    gmem[base+3] = -150;
+    gmem[base+4] = -150;
+    gmem[base+5] = 0;
   );
 
 @slider
@@ -240,7 +244,9 @@ slider1:reset_btn=0<0,1,1{Idle,Reset}>Reset Measurement
   // --- Update gmem every 4096 samples (approx 10x/second at 44.1kHz) ---
   (sample_count % 4096) == 0 ? (
     local(shortterm_mean, momentary_mean, integrated_lufs, shortterm_lufs, momentary_lufs);
-    local(mom_samples);
+    local(mom_samples, base);
+
+    base = floor(slider2 + 0.5) * 8;
 
     mom_samples = floor(srate * 0.4);
     mom_samples < 1 ? mom_samples = 1;
@@ -279,23 +285,23 @@ slider1:reset_btn=0<0,1,1{Idle,Reset}>Reset Measurement
       integrated_lufs = -70;
     );
 
-    gmem[0] = integrated_lufs;
-    gmem[1] = shortterm_lufs;
-    gmem[2] = momentary_lufs;
+    gmem[base+0] = integrated_lufs;
+    gmem[base+1] = shortterm_lufs;
+    gmem[base+2] = momentary_lufs;
 
     true_peak_l > 0.000001 ? (
-      gmem[3] = 20 * log10(true_peak_l);
+      gmem[base+3] = 20 * log10(true_peak_l);
     ) : (
-      gmem[3] = -150;
+      gmem[base+3] = -150;
     );
 
     true_peak_r > 0.000001 ? (
-      gmem[4] = 20 * log10(true_peak_r);
+      gmem[base+4] = 20 * log10(true_peak_r);
     ) : (
-      gmem[4] = -150;
+      gmem[base+4] = -150;
     );
 
-    gmem[5] = sample_count / srate;
+    gmem[base+5] = sample_count / srate;
   );
 
   // Pass audio through unmodified