CLAUDE.md

# PluginBridge — Claude Code Context

## What This Is
A JUCE-based VST3/AU plugin that:
1. Hosts any third-party VST3/AU plugin with full GUI embedded in Ableton's window
2. Crash-isolates unsafe plugins by loading them in a separate Helper process (audio-only mode)
3. Exposes ALL hosted plugin parameters via a local MCP server (port 16620)
4. Audio routes through shared memory (zero added latency)
5. Any AI that speaks MCP (Claude Code, Codex CLI, Gemini CLI) can control any plugin

## Current Status (v0.6.0 — 2026-05-17)

- ✅ In-process GUI hosting (full GUI for safe plugins)
- ✅ Safety scanning system (Helper-based pre-test, results cached in safety_db.json)
- ✅ Audio-only mode for unsafe plugins (iZotope, etc.)
- ✅ Ableton-style plugin picker (manufacturer TreeView, search, safety badges)
- ✅ MCP server (port 16620, HTTP JSON-RPC 2.0)
- ✅ Live spectrum analyzer (LUFS / FFT bands / stereo width / centroid / true peak)
- ✅ Multi-instance support + channel dropdown (any PluginBridge track addressable by name)
- ✅ Verified working: Pro-Q 4, God Particle, Little MicroShift, LIMITER
- ⚠️ Sprint 7 in progress — MCP param ops route through Helper (not in-process) → EQ changes invisible in GUI

## Architecture: HYBRID SAFETY-SCAN

```
┌─ Ableton Process ──────────────────────────────────────────────┐
│                                                                  │
│  PluginBridge.vst3                                               │
│  ├── PluginBridgeProcessor                                       │
│  │   ├── getInstalledPluginFiles() — scans VST3+AU dirs         │
│  │   ├── getPluginManufacturer()  — reads Info.plist, cached    │
│  │   ├── PluginSafetyDB          — safe/unsafe/unknown JSON DB  │
│  │   ├── startBackgroundScan()   — pre-tests all unknown plugins │
│  │   ├── loadPlugin()            — orchestrates load flow        │
│  │   └── McpServer               — HTTP MCP port 16620          │
│  │                                                               │
│  ├── PluginBridgeEditor                                          │
│  │   ├── PluginPickerComponent   — manufacturer TreeView + search│
│  │   └── pluginEditor            — hosted plugin's own editor   │
│  │                                                               │
│  └── HelperConnection            — IPC + shared memory to Helper│
│                                                                  │
└──────────────────────────────────────────────────────────────────┘
         │ Unix socket + shared memory
         ▼
┌─ PluginBridgeHelper.app (separate process) ─────────────────────┐
│  Bundled in PluginBridge.vst3/Contents/Resources/               │
│                                                                  │
│  Modes:                                                          │
│  --load <path>    Load plugin, route audio via shared memory     │
│  --scan <path>    Test-load plugin, exit 0=safe / crash=unsafe   │
└──────────────────────────────────────────────────────────────────┘
```

## Plugin Load Flow

```
User selects plugin in picker
         │
         ▼
loadPlugin() checks PluginSafetyDB
         │
    ┌────┴──────────────────┐
    │                       │
 Unknown                 Safe/Unsafe already known
    │                       │
    ▼                       │
Wait for Helper to exit     │
Spawn: Helper --scan        │
    │                       │
 Crashed? → mark Unsafe     │
 Exit 0?  → mark Safe       │
    │                       │
    └────────────┬──────────┘
                 │
         ┌───────┴────────┐
         │                │
       Safe             Unsafe
         │                │
         ▼                ▼
  Helper --load      Helper --load
  (audio routing)    (audio routing)
         │                │
         ▼                ▼
  loadInProcess()   showAudioOnlyUI()
  createEditor()    (MCP still works)
  embed in window
```

**Key constraint:** Only ONE Helper process at a time. Scanner must wait for live Helper to finish before spawning a scan subprocess (same shared memory name → conflict).

## File Structure

```
pluginbridge/
├── CMakeLists.txt
├── JUCE/                         (git submodule)
├── libs/
│   ├── httplib.h                 (MIT, header-only HTTP server)
│   └── json.hpp                  (MIT, header-only JSON)
├── Source/
│   ├── Plugin/                   ← VST3/AU (runs inside Ableton)
│   │   ├── PluginBridgeProcessor.h/.cpp    — main logic
│   │   ├── PluginBridgeEditor.h/.mm        — editor window
│   │   ├── PluginPickerComponent.h/.mm     — plugin browser UI (new v0.5)
│   │   ├── HelperConnection.h/.cpp         — IPC + shared memory
│   │   ├── McpServer.h/.cpp                — HTTP MCP server
│   │   ├── PluginSafetyDB.h                — safe/unsafe JSON DB
│   │   ├── Blocklist.h                     — persistent crash blocklist
│   │   └── PBLog.h                         — timestamped logger
│   ├── Helper/                   ← Standalone exe (separate process)
│   │   ├── main.cpp              — --load and --scan modes
│   │   ├── HelperPluginHost.h/.mm
│   │   └── HelperIPC.h/.cpp
│   └── Shared/
│       ├── SharedAudioBuffer.h   — shared memory layout
│       ├── IPCProtocol.h         — JSON message formats
│       └── Constants.h
├── CLAUDE.md                     ← this file
├── MACHINE-CONTEXT.md            ← system paths, verified APIs, plugin behaviors
├── SYNC.md                       ← what was built/fixed and when
├── FAILED-APPROACHES.md          ← what didn't work and why
└── ROADMAP.md
```

## Build

```bash
cd "/Volumes/T7 Shield/Users/Aditya/Downloads/AI MUSIC PRODUCTION/pluginbridge/build"
cmake --build . --target PluginBridge_VST3 -- -j4
# Auto-installs to ~/Library/Audio/Plug-Ins/VST3/PluginBridge.vst3
```

**Two targets:**
- `PluginBridge_VST3` — builds + installs both plugin and Helper
- `PluginBridgeHelper` — Helper standalone only

**CMake 3.28 required** (system CMake 4.x incompatible with JUCE 8).

## Key Runtime Data

| File | Purpose |
|---|---|
| `~/Library/PluginBridge/safety_db.json` | Safe/unsafe status per plugin path+mtime |
| `~/Library/PluginBridge/debug.log` | Session-tagged timestamped log |
| `~/Library/PluginBridge/scan.log` | Background scan output |
| `~/Library/PluginBridge/blocklist.txt` | Plugins that crashed Helper during use |

## PluginPickerComponent (v0.5)

`Source/Plugin/PluginPickerComponent.h/.mm`

- `Entry` struct: `{ file, name, manufacturer, blocked, safety }`
- Callbacks: `onPluginSelected`, `onClose`, `onClearBlocklist`, `onClearSafetyCache`
- `static constexpr int kWidth = 420, kHeight = 500`
- Tree: `ManufacturerTreeItem` (folder) → `PluginTreeItem` (leaf, 24px height)
- Safety badges: `Safety::Safe` → `✓` green; `Safety::Unsafe` → `audio only` orange; `blocked` → `⚠` red
- Search: `addChildComponent(searchList)` — NOT `addAndMakeVisible` (see FAILED-APPROACHES)
- Custom `TreeLF` LookAndFeel overrides `drawTreeviewPlusMinusBox` for Ableton-style arrows

## JUCE 8 APIs — Verified

### Working
- `formatManager.addFormat(new juce::VST3PluginFormat())`
- `formatManager.addFormat(new juce::AudioUnitPluginFormat())`
- `plugin->createEditor()` — message thread only
- `plugin->hasEditor()`
- `plugin->getParameters()` → `Array<AudioProcessorParameter*>`
- `juce::MessageManager::callAsync(lambda)` — cross-thread UI updates
- `addChildComponent(comp)` — adds hidden; use instead of `addAndMakeVisible` when starting invisible
- `juce::TreeView` + `juce::TreeViewItem` with custom `LookAndFeel`
- `juce::File::findChildFiles(findDirectories, false, "*.vst3")`

### Broken — Do NOT Use
- ❌ `addDefaultFormats()` — deleted in JUCE 8
- ❌ `juce::Thread::setCurrentThreadPriority()` — removed, use native pthread
- ❌ `getParameter(int)` / `setParameter(int, float)` — deprecated
- ❌ `getStringWidth()` — use `getStringWidthFloat()`
- ❌ `juce::Rectangle<float>::getTransformToFit()` — does not exist
- ❌ `juce::Array<CustomStruct>` initializer list — use `std::vector<CustomStruct>`

## macOS Gotchas

- ❌ `MSG_NOSIGNAL` — Linux only → `signal(SIGPIPE, SIG_IGN)` + `SO_NOSIGPIPE`
- ❌ Two processes with same `shm_open` name → both crash — scanner must wait for Helper
- ❌ `addAndMakeVisible(comp)` after `comp.setVisible(false)` → `addAndMakeVisible` forces visible, invisible comp sits on top intercepting all mouse events → use `addChildComponent(comp)` instead
- ❌ `CAContext` + `CALayerHost` for cross-process GUI → doesn't work in Ableton (see FAILED-APPROACHES #10)
- ✅ `posix_spawn` — safe for spawning from plugin process
- ✅ `shm_open` / `mmap` — reliable cross-process shared memory

## MCP Protocol

- Endpoint: `POST http://127.0.0.1:16620/mcp`
- Health: `GET http://127.0.0.1:16620/health`
- Wire format: JSON-RPC 2.0
- Tools: `list_plugins`, `search_param`, `get_params`, `set_params`, `get_analysis`

## What NOT To Do

- Don't load plugins in-process without safety scan — crash-prone plugins (iZotope, some Waves) call `abort()` and kill Ableton
- Don't use `PluginDirectoryScanner` — triggers plugin code on scan → crash
- Don't spawn Helper --scan while live Helper is running — shared memory conflict → false UNSAFE results
- Don't use `addAndMakeVisible` on a component that should start hidden — use `addChildComponent`
- Don't try CAContext/CALayerHost for cross-process GUI — see FAILED-APPROACHES #10