@mthines/reaper-mcp 0.7.0 → 0.9.0

package/knowledge/workflows/stem-prep.md

@@ -0,0 +1,175 @@
+---
+name: Stem Preparation
+id: stem-prep
+description: Verify bus structure and routing for stem export readiness
+---
+
+# Stem Preparation
+
+## When to Use
+
+After mastering is complete and before final delivery. Stem preparation ensures the session's bus structure, routing, and naming conventions are correct so that exported stems will sum to match the full mix exactly.
+
+Use this workflow when:
+- The mix is complete and mastered, ready for stem export
+- Stems are needed for sync licensing, remix, or immersive audio
+- A mastering engineer has requested stems instead of a stereo mix
+- The session needs routing verification before export
+
+## Prerequisites
+
+- Mix is complete (all mixing and mastering decisions are finalized)
+- Bus structure exists (drum bus, vocal bus, instrument bus, etc.)
+- Session is playing back correctly (no muted tracks that should be active)
+- Genre and delivery specs are known
+
+## Step-by-Step
+
+### Step 1: Save a safety snapshot
+
+```
+tool: snapshot_save
+params:
+  name: "pre-stem-prep"
+  description: "State before stem preparation"
+```
+
+### Step 2: Document the current bus structure
+
+```
+tool: list_tracks
+tool: get_project_info
+```
+
+Map out the full routing hierarchy. For each track:
+
+```
+tool: get_track_routing
+params:
+  trackIndex: [n]
+```
+
+Identify:
+- Which tracks route to which buses
+- Which buses route to the master
+- Any orphan tracks routing directly to master (should go through a bus)
+- Any tracks with sends to multiple destinations
+
+### Step 3: Verify standard stem groups
+
+Typical stem groups for export:
+
+| Stem | Contains | Bus |
+|------|----------|-----|
+| Drums | Kick, Snare, Toms, OH, Room | Drum Bus |
+| Bass | Bass DI, Bass Amp | Bass Bus |
+| Guitars | All guitar tracks | Guitar Bus |
+| Keys/Synths | Piano, Organ, Pads, Leads | Keys Bus |
+| Vocals | Lead, BVs, Harmonies | Vocal Bus |
+| Effects | Reverbs, Delays (printed) | Effects Bus |
+
+Verify each group routes correctly:
+
+```
+tool: get_track_properties
+params:
+  trackIndex: [bus track index]
+```
+
+### Step 4: Check for routing problems
+
+Common issues to flag:
+
+1. **Orphan tracks**: Source tracks routing directly to master instead of through a bus
+2. **Double-routing**: A track routing to both a bus AND the master (will be in the stem AND the full mix twice)
+3. **Missing tracks**: Tracks that are muted or have no output
+4. **Send-only tracks**: Reverb returns that should be captured in a stem but are going to master instead of a bus
+5. **Master bus processing**: Note which FX are on the master bus — stems are typically exported pre-master-bus-processing
+
+For each bus, check that all expected source tracks are present:
+
+```
+tool: get_track_routing
+params:
+  trackIndex: [bus index]
+```
+
+### Step 5: Verify naming conventions
+
+Stems need clear, consistent names for delivery. Verify bus names follow a convention:
+
+```
+[Song Title]_[Stem Name]_[Bit Depth]-[Sample Rate]
+```
+
+Examples:
+- `MySong_Drums_24-48.wav`
+- `MySong_Vocals_24-48.wav`
+- `MySong_Bass_24-48.wav`
+
+Check that bus track names are clean and descriptive:
+
+```
+tool: get_track_properties
+params:
+  trackIndex: [bus index]
+```
+
+Rename if needed:
+```
+tool: set_track_property
+params:
+  trackIndex: [bus index]
+  property: "name"
+  value: "Drum Bus"
+```
+
+### Step 6: Verify technical specs
+
+```
+tool: get_project_info
+```
+
+Confirm:
+- **Sample rate**: Matches delivery requirements (typically 44.1 kHz or 48 kHz)
+- **Bit depth**: 24-bit or 32-bit float for stems
+- **All stems have same duration**: Check that all bus tracks span the full song (from before first note to after last decay)
+
+### Step 7: Document the stem map
+
+Create a clear report of:
+- Each stem name and what tracks it contains
+- Routing chain for each stem
+- Any processing on stem buses (baked into the stem)
+- Master bus processing that will NOT be in individual stems
+- Total stem count
+- Technical specs (sample rate, bit depth)
+
+### Step 8: Save post-prep snapshot
+
+```
+tool: snapshot_save
+params:
+  name: "post-stem-prep"
+  description: "Stems verified — routing correct, naming consistent, ready for export"
+```
+
+## Verification
+
+After completing stem preparation:
+
+1. Every source track routes to exactly one bus (no orphans, no double-routing)
+2. All buses route to the master
+3. Bus names are clear and follow a consistent convention
+4. No tracks are accidentally muted or disabled
+5. Stem groups make musical sense (all drums together, all vocals together, etc.)
+6. Technical specs are documented (sample rate, bit depth, duration)
+7. The user knows which master bus processing will NOT be included in individual stems
+
+## Common Pitfalls
+
+- **Forgetting reverb/delay returns**: Shared effects (reverb bus, delay bus) need to be assigned to a stem or exported as their own stem. If they route to master only, they'll be in the full mix but not in any stem.
+- **Double-counting sends**: If a track sends to both a bus and a reverb return, the dry signal is in one stem and the wet signal might be in another. This is usually correct, but document it.
+- **Master bus processing**: If the master bus has EQ/compression/limiting, individual stems will sound different than the full mix. This is normal — stems are typically pre-master-bus.
+- **Mismatched levels**: All stems should sum to equal the full mix at the master bus. If they don't, there's a routing or level issue.
+- **Not checking mute states**: A muted track won't export. Verify all intended tracks are unmuted and active.

package/main.js

@@ -134,12 +134,14 @@ function getTimeoutCounter() {
 
 // apps/reaper-mcp-server/src/bridge.ts
 import { randomUUID } from "node:crypto";
-import { readFile, writeFile, readdir, unlink, mkdir, stat } from "node:fs/promises";
+import { appendFile, readFile, writeFile, readdir, unlink, mkdir, stat } from "node:fs/promises";
 import { join as join2 } from "node:path";
 import { homedir, platform } from "node:os";
 import { SpanKind, SpanStatusCode } from "@opentelemetry/api";
-var POLL_INTERVAL_MS = 50;
+var POLL_INTERVAL_MS = 10;
 var DEFAULT_TIMEOUT_MS = 1e4;
+var PROFILE_BRIDGE = process.env["BRIDGE_PROFILE"] === "1";
+var lastTimings = null;
 function getReaperResourcePath() {
   const env = process.env["REAPER_RESOURCE_PATH"];
   if (env) return env;
@@ -164,6 +166,10 @@ async function ensureBridgeDir() {
 async function sendCommand(type, params = {}, timeoutMs = DEFAULT_TIMEOUT_MS) {
   const tracer = getTracer();
   const startMs = Date.now();
+  const t = {};
+  const profiling = PROFILE_BRIDGE;
+  const now = profiling ? () => performance.now() : () => 0;
+  const t0 = now();
   return tracer.startActiveSpan(
     `mcp.bridge ${type}`,
     {
@@ -174,7 +180,10 @@ async function sendCommand(type, params = {}, timeoutMs = DEFAULT_TIMEOUT_MS) {
       }
     },
     async (span) => {
+      if (profiling) t["spanSetup"] = now() - t0;
+      const tDir = now();
       const dir = await ensureBridgeDir();
+      if (profiling) t["ensureDir"] = now() - tDir;
       const id = randomUUID();
       span.setAttribute("mcp.command.id", id);
       const command2 = {
@@ -183,8 +192,13 @@ async function sendCommand(type, params = {}, timeoutMs = DEFAULT_TIMEOUT_MS) {
         params,
         timestamp: Date.now()
       };
+      const tWrite = now();
       const commandPath = join2(dir, `command_${id}.json`);
       await writeFile(commandPath, JSON.stringify(command2, null, 2), "utf-8");
+      const notifyPath = join2(dir, "_notify");
+      await appendFile(notifyPath, id + "\n");
+      if (profiling) t["write"] = now() - tWrite;
+      const tLog = now();
       const traceCtx = getTraceContext();
       console.error(
         JSON.stringify({
@@ -194,13 +208,22 @@ async function sendCommand(type, params = {}, timeoutMs = DEFAULT_TIMEOUT_MS) {
           ...traceCtx
         })
       );
+      if (profiling) t["log"] = now() - tLog;
       const responsePath = join2(dir, `response_${id}.json`);
       const deadline = Date.now() + timeoutMs;
+      const tPoll = now();
+      let pollAttempts = 0;
       while (Date.now() < deadline) {
         try {
+          pollAttempts++;
+          const tRead = now();
           const data = await readFile(responsePath, "utf-8");
           const response = JSON.parse(data);
+          if (profiling) t["readParse"] = now() - tRead;
+          if (profiling) t["pollWait"] = now() - tPoll - (t["readParse"] ?? 0);
+          const tCleanup = now();
           await Promise.allSettled([unlink(commandPath), unlink(responsePath)]);
+          if (profiling) t["cleanup"] = now() - tCleanup;
           const durationMs2 = Date.now() - startMs;
           const succeeded = response.success;
           span.setAttribute("mcp.response.success", succeeded);
@@ -219,8 +242,24 @@ async function sendCommand(type, params = {}, timeoutMs = DEFAULT_TIMEOUT_MS) {
             );
           }
           span.end();
+          const tMetrics = now();
           getCommandDurationHistogram().record(durationMs2, { command_type: type });
           getCommandCounter().add(1, { command_type: type, success: String(succeeded) });
+          if (profiling) t["metrics"] = now() - tMetrics;
+          if (profiling) {
+            lastTimings = {
+              spanSetupMs: Math.round(t["spanSetup"] ?? 0),
+              ensureDirMs: Math.round(t["ensureDir"] ?? 0),
+              writeMs: Math.round(t["write"] ?? 0),
+              logMs: Math.round(t["log"] ?? 0),
+              pollWaitMs: Math.round(t["pollWait"] ?? 0),
+              pollAttempts,
+              readParseMs: Math.round(t["readParse"] ?? 0),
+              cleanupMs: Math.round(t["cleanup"] ?? 0),
+              metricsMs: Math.round(t["metrics"] ?? 0),
+              totalMs: Math.round(now() - t0)
+            };
+          }
           return response;
         } catch {
           await sleep(POLL_INTERVAL_MS);
@@ -1456,6 +1495,109 @@ function registerEnvelopeTools(server) {
       return { content: [{ type: "text", text: `Deleted envelope point ${pointIndex}` }] };
     }
   );
+  server.tool(
+    "create_track_envelope",
+    "Create/show an automation envelope on a track. Use envelopeName for built-in envelopes (Volume, Pan, Mute, Width, Trim Volume) or fxIndex+paramIndex for FX parameter envelopes. The envelope is made visible and active.",
+    {
+      trackIndex: z14.coerce.number().int().min(0).describe("Zero-based track index"),
+      envelopeName: z14.string().optional().describe('Built-in envelope name: "Volume", "Pan", "Mute", "Width", "Trim Volume"'),
+      fxIndex: z14.coerce.number().int().min(0).optional().describe("FX chain index (for FX parameter envelopes)"),
+      paramIndex: z14.coerce.number().int().min(0).optional().describe("FX parameter index (required if fxIndex provided)")
+    },
+    async ({ trackIndex, envelopeName, fxIndex, paramIndex }) => {
+      const res = await sendCommand("create_track_envelope", {
+        trackIndex,
+        envelopeName,
+        fxIndex,
+        paramIndex
+      });
+      if (!res.success) {
+        return { content: [{ type: "text", text: `Error: ${res.error}` }], isError: true };
+      }
+      return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    }
+  );
+  server.tool(
+    "set_envelope_properties",
+    "Set properties (active, visible, armed) on a track envelope. Requires SWS extension for full support.",
+    {
+      trackIndex: z14.coerce.number().int().min(0).describe("Zero-based track index"),
+      envelopeIndex: z14.coerce.number().int().min(0).describe("Zero-based envelope index on the track"),
+      active: z14.boolean().optional().describe("Set envelope active/inactive"),
+      visible: z14.boolean().optional().describe("Set envelope visible/hidden in arrange view"),
+      armed: z14.boolean().optional().describe("Set envelope armed for writing automation")
+    },
+    async ({ trackIndex, envelopeIndex, active, visible, armed }) => {
+      const res = await sendCommand("set_envelope_properties", {
+        trackIndex,
+        envelopeIndex,
+        active,
+        visible,
+        armed
+      });
+      if (!res.success) {
+        return { content: [{ type: "text", text: `Error: ${res.error}` }], isError: true };
+      }
+      return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    }
+  );
+  server.tool(
+    "clear_envelope",
+    "Delete ALL automation points from an envelope, resetting it to its default state",
+    {
+      trackIndex: z14.coerce.number().int().min(0).describe("Zero-based track index"),
+      envelopeIndex: z14.coerce.number().int().min(0).describe("Zero-based envelope index on the track")
+    },
+    async ({ trackIndex, envelopeIndex }) => {
+      const res = await sendCommand("clear_envelope", { trackIndex, envelopeIndex });
+      if (!res.success) {
+        return { content: [{ type: "text", text: `Error: ${res.error}` }], isError: true };
+      }
+      return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    }
+  );
+  server.tool(
+    "remove_envelope_points",
+    "Delete automation points in a time range from a track envelope. Use to surgically remove a section of automation.",
+    {
+      trackIndex: z14.coerce.number().int().min(0).describe("Zero-based track index"),
+      envelopeIndex: z14.coerce.number().int().min(0).describe("Zero-based envelope index on the track"),
+      timeStart: z14.coerce.number().describe("Start of time range in seconds (inclusive)"),
+      timeEnd: z14.coerce.number().describe("End of time range in seconds (exclusive)")
+    },
+    async ({ trackIndex, envelopeIndex, timeStart, timeEnd }) => {
+      const res = await sendCommand("remove_envelope_points", {
+        trackIndex,
+        envelopeIndex,
+        timeStart,
+        timeEnd
+      });
+      if (!res.success) {
+        return { content: [{ type: "text", text: `Error: ${res.error}` }], isError: true };
+      }
+      return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    }
+  );
+  server.tool(
+    "insert_envelope_points",
+    "Batch insert multiple automation points on a track envelope. Much faster than repeated insert_envelope_point calls.",
+    {
+      trackIndex: z14.coerce.number().int().min(0).describe("Zero-based track index"),
+      envelopeIndex: z14.coerce.number().int().min(0).describe("Zero-based envelope index on the track"),
+      points: z14.string().describe("JSON array of point objects: [{time, value, shape?, tension?}, ...]")
+    },
+    async ({ trackIndex, envelopeIndex, points }) => {
+      const res = await sendCommand("insert_envelope_points", {
+        trackIndex,
+        envelopeIndex,
+        points
+      });
+      if (!res.success) {
+        return { content: [{ type: "text", text: `Error: ${res.error}` }], isError: true };
+      }
+      return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    }
+  );
 }
 
 // apps/reaper-mcp-server/src/server.ts
@@ -1669,7 +1811,12 @@ var MCP_TOOL_NAMES = [
   "get_track_envelopes",
   "get_envelope_points",
   "insert_envelope_point",
-  "delete_envelope_point"
+  "insert_envelope_points",
+  "delete_envelope_point",
+  "create_track_envelope",
+  "set_envelope_properties",
+  "clear_envelope",
+  "remove_envelope_points"
 ];
 function ensureClaudeSettings(settingsPath) {
   const allowList = MCP_TOOL_NAMES.map((t) => `mcp__reaper__${t}`);
@@ -1689,6 +1836,11 @@ function ensureClaudeSettings(settingsPath) {
   writeFileSync(settingsPath, JSON.stringify(existing, null, 2) + "\n", "utf-8");
   return "updated";
 }
+function resolveAssetDirWithFallback(baseDir, buildName, sourceName) {
+  const resolved = resolveAssetDir(baseDir, buildName);
+  if (existsSync(resolved)) return resolved;
+  return resolveAssetDir(baseDir, sourceName);
+}
 
 // apps/reaper-mcp-server/src/main.ts
 var __dirname = dirname2(fileURLToPath2(import.meta.url));
@@ -1708,7 +1860,7 @@ async function setup() {
   } else {
     console.log(`  Not found: ${luaSrc}`);
   }
-  const effectsDir = getReaperEffectsPath();
+  const effectsDir = join4(getReaperEffectsPath(), "reaper-mcp");
   mkdirSync2(effectsDir, { recursive: true });
   console.log("\nInstalling JSFX analyzers...");
   for (const jsfx of REAPER_ASSETS) {
@@ -1716,7 +1868,7 @@ async function setup() {
     const src = join4(reaperDir, jsfx);
     const dest = join4(effectsDir, jsfx);
     if (installFile(src, dest)) {
-      console.log(`  Installed: ${jsfx}`);
+      console.log(`  Installed: reaper-mcp/${jsfx}`);
     } else {
       console.log(`  Not found: ${src}`);
     }
@@ -1729,73 +1881,69 @@ async function setup() {
   console.log("  4. Run the script (it will keep running in background via defer loop)");
   console.log("  5. Add reaper-mcp to your Claude Code config (see: npx @mthines/reaper-mcp doctor)");
 }
-async function installSkills() {
-  console.log("REAPER MCP \u2014 Install AI Mix Engineer Skills\n");
-  const targetDir = process.cwd();
-  const globalClaudeDir = join4(homedir2(), ".claude");
+function parseInstallScope(args) {
+  if (args.includes("--project")) return "project";
+  return "global";
+}
+async function installSkills(scope) {
+  console.log(`REAPER MCP \u2014 Install AI Mix Engineer Skills (scope: ${scope})
+`);
+  const isGlobal = scope === "global";
+  const baseDir = isGlobal ? join4(homedir2(), ".claude") : process.cwd();
+  const claudeDir = isGlobal ? baseDir : join4(baseDir, ".claude");
   const knowledgeSrc = resolveAssetDir(__dirname, "knowledge");
-  const knowledgeDest = join4(targetDir, "knowledge");
   if (existsSync2(knowledgeSrc)) {
-    const count = copyDirSync(knowledgeSrc, knowledgeDest);
-    console.log(`Installed knowledge base: ${count} files \u2192 ${knowledgeDest}`);
+    const dest = join4(baseDir, "knowledge");
+    const count = copyDirSync(knowledgeSrc, dest);
+    console.log(`Installed knowledge base: ${count} files \u2192 ${dest}`);
   } else {
     console.log("Knowledge base not found in package. Skipping.");
   }
-  const rulesSrc = resolveAssetDir(__dirname, "claude-rules");
-  const rulesDir = join4(targetDir, ".claude", "rules");
+  const rulesSrc = resolveAssetDirWithFallback(__dirname, "claude-rules", join4(".claude", "rules"));
   if (existsSync2(rulesSrc)) {
-    const count = copyDirSync(rulesSrc, rulesDir);
-    console.log(`Installed Claude rules: ${count} files \u2192 ${rulesDir}`);
+    const dest = join4(claudeDir, "rules");
+    const count = copyDirSync(rulesSrc, dest);
+    console.log(`Installed Claude rules: ${count} files \u2192 ${dest}`);
   } else {
     console.log("Claude rules not found in package. Skipping.");
   }
-  const skillsSrc = resolveAssetDir(__dirname, "claude-skills");
-  const skillsDir = join4(targetDir, ".claude", "skills");
+  const skillsSrc = resolveAssetDirWithFallback(__dirname, "claude-skills", join4(".claude", "skills"));
   if (existsSync2(skillsSrc)) {
-    const count = copyDirSync(skillsSrc, skillsDir);
-    console.log(`Installed Claude skills: ${count} files \u2192 ${skillsDir}`);
+    const dest = join4(claudeDir, "skills");
+    const count = copyDirSync(skillsSrc, dest);
+    console.log(`Installed Claude skills: ${count} files \u2192 ${dest}`);
   } else {
     console.log("Claude skills not found in package. Skipping.");
   }
-  const agentsSrc = resolveAssetDir(__dirname, "claude-agents");
-  const agentsDir = join4(targetDir, ".claude", "agents");
+  const agentsSrc = resolveAssetDirWithFallback(__dirname, "claude-agents", join4(".claude", "agents"));
   if (existsSync2(agentsSrc)) {
-    const count = copyDirSync(agentsSrc, agentsDir);
-    console.log(`Installed Claude agents: ${count} files \u2192 ${agentsDir}`);
+    const dest = join4(claudeDir, "agents");
+    const count = copyDirSync(agentsSrc, dest);
+    console.log(`Installed Claude agents: ${count} files \u2192 ${dest}`);
   } else {
     console.log("Claude agents not found in package. Skipping.");
   }
-  const globalAgentsDir = join4(globalClaudeDir, "agents");
-  if (existsSync2(agentsSrc)) {
-    const count = copyDirSync(agentsSrc, globalAgentsDir);
-    console.log(`Installed Claude agents (global): ${count} files \u2192 ${globalAgentsDir}`);
-  }
-  const localSettingsPath = join4(targetDir, ".claude", "settings.json");
-  const localResult = ensureClaudeSettings(localSettingsPath);
-  if (localResult === "created") {
-    console.log(`Created Claude settings: ${localSettingsPath}`);
-  } else if (localResult === "updated") {
-    console.log(`Updated Claude settings with new REAPER tools: ${localSettingsPath}`);
+  const settingsPath = join4(claudeDir, "settings.json");
+  const result = ensureClaudeSettings(settingsPath);
+  if (result === "created") {
+    console.log(`Created Claude settings: ${settingsPath}`);
+  } else if (result === "updated") {
+    console.log(`Updated Claude settings with new REAPER tools: ${settingsPath}`);
   } else {
-    console.log(`Claude settings already has all REAPER tools: ${localSettingsPath}`);
-  }
-  const globalSettingsPath = join4(globalClaudeDir, "settings.json");
-  const globalResult = ensureClaudeSettings(globalSettingsPath);
-  if (globalResult === "created") {
-    console.log(`Created Claude settings (global): ${globalSettingsPath}`);
-  } else if (globalResult === "updated") {
-    console.log(`Updated Claude settings (global) with new REAPER tools: ${globalSettingsPath}`);
+    console.log(`Claude settings already has all REAPER tools: ${settingsPath}`);
   }
-  const mcpJsonPath = join4(targetDir, ".mcp.json");
-  if (createMcpJson(mcpJsonPath)) {
-    console.log(`
+  if (!isGlobal) {
+    const mcpJsonPath = join4(baseDir, ".mcp.json");
+    if (createMcpJson(mcpJsonPath)) {
+      console.log(`
 Created: ${mcpJsonPath}`);
-  } else {
-    console.log(`
+    } else {
+      console.log(`
 .mcp.json already exists \u2014 add the reaper server config manually if needed.`);
+    }
   }
   console.log("\nDone! Claude Code now has mix engineer agents, knowledge, and REAPER MCP tools.");
-  console.log("All 48 REAPER tools are pre-approved \u2014 agents work autonomously.");
+  console.log(`All ${MCP_TOOL_NAMES.length} REAPER tools are pre-approved \u2014 agents work autonomously.`);
   console.log('\nTry: @mix-engineer "Please gain stage my tracks"');
   console.log('Or:  @mix-analyzer "Roast my mix"');
 }
@@ -1806,20 +1954,27 @@ async function doctor() {
   if (!bridgeRunning) {
     console.log('  \u2192 Run "npx @mthines/reaper-mcp setup" then load mcp_bridge.lua in REAPER');
   }
-  const agentsExist = existsSync2(join4(process.cwd(), ".claude", "agents"));
-  console.log(`Mix agents:    ${agentsExist ? "\u2713 Found (.claude/agents/)" : "\u2717 Not installed"}`);
+  const globalClaudeDir = join4(homedir2(), ".claude");
+  const localAgents = existsSync2(join4(process.cwd(), ".claude", "agents"));
+  const globalAgents = existsSync2(join4(globalClaudeDir, "agents"));
+  const agentsExist = localAgents || globalAgents;
+  const agentsLocation = localAgents ? ".claude/agents/" : globalAgents ? "~/.claude/agents/" : "";
+  console.log(`Mix agents:    ${agentsExist ? `\u2713 Found (${agentsLocation})` : "\u2717 Not installed"}`);
   if (!agentsExist) {
-    console.log('  \u2192 Run "npx @mthines/reaper-mcp install-skills" in your project directory');
+    console.log('  \u2192 Run "npx @mthines/reaper-mcp install-skills"');
   }
-  const knowledgeExists = existsSync2(join4(process.cwd(), "knowledge"));
-  console.log(`Knowledge base: ${knowledgeExists ? "\u2713 Found in project" : "\u2717 Not installed"}`);
+  const localKnowledge = existsSync2(join4(process.cwd(), "knowledge"));
+  const globalKnowledge = existsSync2(join4(globalClaudeDir, "knowledge"));
+  const knowledgeExists = localKnowledge || globalKnowledge;
+  const knowledgeLocation = localKnowledge ? "project" : globalKnowledge ? "~/.claude/" : "";
+  console.log(`Knowledge base: ${knowledgeExists ? `\u2713 Found (${knowledgeLocation})` : "\u2717 Not installed"}`);
   if (!knowledgeExists) {
-    console.log('  \u2192 Run "npx @mthines/reaper-mcp install-skills" in your project directory');
+    console.log('  \u2192 Run "npx @mthines/reaper-mcp install-skills"');
   }
   const mcpJsonExists = existsSync2(join4(process.cwd(), ".mcp.json"));
   console.log(`MCP config:    ${mcpJsonExists ? "\u2713 .mcp.json found" : "\u2717 .mcp.json missing"}`);
   if (!mcpJsonExists) {
-    console.log('  \u2192 Run "npx @mthines/reaper-mcp install-skills" to create .mcp.json');
+    console.log('  \u2192 Run "npx @mthines/reaper-mcp install-skills --project" to create .mcp.json');
   }
   console.log('\nTo check SWS Extensions, start REAPER and use the "list_available_fx" tool.');
   console.log("SWS provides enhanced plugin discovery and snapshot support.\n");
@@ -1884,7 +2039,7 @@ switch (command) {
     });
     break;
   case "install-skills":
-    installSkills().catch((err) => {
+    installSkills(parseInstallScope(process.argv.slice(3))).catch((err) => {
       console.error("Install failed:", err);
       process.exit(1);
     });
@@ -1917,14 +2072,16 @@ Usage:
   npx @mthines/reaper-mcp                  Start MCP server (stdio mode)
   npx @mthines/reaper-mcp serve            Start MCP server (stdio mode)
   npx @mthines/reaper-mcp setup            Install Lua bridge + JSFX analyzers into REAPER
-  npx @mthines/reaper-mcp install-skills   Install AI mix engineer knowledge + agents into your project
+  npx @mthines/reaper-mcp install-skills   Install AI knowledge + agents globally (default)
+  npx @mthines/reaper-mcp install-skills --project  Install into current project directory
+  npx @mthines/reaper-mcp install-skills --global   Install into ~/.claude/ (default)
   npx @mthines/reaper-mcp doctor           Check that everything is configured correctly
   npx @mthines/reaper-mcp status           Check if Lua bridge is running in REAPER
 
 Quick Start:
   1. npx @mthines/reaper-mcp setup            # install REAPER components
   2. Load mcp_bridge.lua in REAPER (Actions > Load ReaScript > Run)
-  3. npx @mthines/reaper-mcp install-skills   # install AI knowledge + agents
+  3. npx @mthines/reaper-mcp install-skills   # install AI knowledge + agents (globally)
   4. Open Claude Code \u2014 REAPER tools + mix engineer agents are ready
 
 Tip: install globally for shorter commands:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mthines/reaper-mcp",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "type": "module",
   "description": "MCP server for controlling REAPER DAW — real-time mixing, FX control, and frequency analysis for AI agents",
   "license": "MIT",

package/reaper/CLAUDE.md

@@ -0,0 +1,60 @@
+# REAPER Scripts
+
+Files installed INTO the REAPER DAW by the `setup` command. These run inside REAPER's scripting environment.
+
+## Files
+
+| File | Language | Purpose |
+|------|----------|---------|
+| `mcp_bridge.lua` | Lua | Persistent bridge: polls for JSON commands, executes ReaScript API, writes responses |
+| `mcp_analyzer.jsfx` | JSFX/EEL2 | Real-time FFT spectrum analyzer, writes to gmem[] |
+| `mcp_lufs_meter.jsfx` | JSFX/EEL2 | LUFS loudness metering |
+| `mcp_correlation_meter.jsfx` | JSFX/EEL2 | Stereo correlation and width analysis |
+| `mcp_crest_factor.jsfx` | JSFX/EEL2 | Crest factor (peak-to-RMS) measurement |
+| `install.sh` | Shell | Manual install helper |
+
+## Lua Bridge (`mcp_bridge.lua`)
+
+### How It Works
+1. Runs as a persistent `reaper.defer()` loop (polls every ~30ms)
+2. Reads `command_{uuid}.json` from bridge directory
+3. Dispatches to handler function in the `handlers` table
+4. Writes `response_{uuid}.json` with results
+5. Writes `heartbeat.json` every 1s for liveness detection
+
+### Adding a Handler
+```lua
+handlers["command_type"] = function(params)
+  local result = reaper.SomeApiCall(params.paramName)
+  return { field = result }
+end
+```
+
+The command type string must exactly match `CommandType` in `libs/protocol/src/commands.ts`.
+
+### Key Constraints
+- REAPER Lua is sandboxed: **no sockets, no HTTP, no stdin/stdout** — file-based IPC only
+- JSON parsing: uses `CF_Json_Parse` if available (REAPER 7+), falls back to custom Lua parser
+- Track indices are 0-based (same as ReaScript)
+- Volume values: bridge converts between dB (MCP protocol) and linear (ReaScript internally)
+- Always wrap file reads in `pcall` for resilience
+
+## JSFX Meters
+
+- Run in REAPER's **audio thread** (not scripting thread)
+- Communicate with Lua via `gmem[]` shared memory
+- Each JSFX uses a unique gmem namespace (e.g., `MCPAnalyzer`, `MCPLufsMeter`)
+- Must pass audio through unmodified (transparent inserts)
+- Auto-inserted by corresponding MCP tools (`read_track_spectrum`, `read_track_lufs`, etc.)
+
+## Testing
+
+- **No automated tests possible** — REAPER's Lua/JSFX environment cannot be unit tested outside REAPER
+- Test manually: install bridge, run MCP Inspector, exercise commands
+- Server-side tests mock `sendCommand()` in `bridge.ts`
+
+## Installation
+
+Files are copied to `{REAPER_RESOURCE_PATH}/Scripts/` by:
+- `node dist/apps/reaper-mcp-server/main.js setup` (programmatic)
+- `install.sh` (manual)