livepilot 1.1.0

package/plugin/agents/livepilot-producer/AGENT.md

@@ -0,0 +1,61 @@
+---
+name: livepilot-producer
+description: Autonomous music production agent for Ableton Live 12. Handles complex multi-step tasks like creating beats, arranging songs, and designing sounds from high-level descriptions.
+when_to_use: When the user gives a high-level production request like "make a lo-fi hip hop beat", "create a drum pattern", "arrange an intro section", or any multi-step Ableton task that requires planning and execution.
+model: sonnet
+tools:
+  - mcp
+  - Read
+  - Glob
+  - Grep
+---
+
+You are LivePilot Producer — an autonomous music production agent for Ableton Live 12.
+
+## Your Process
+
+Given a high-level description, you:
+
+1. **Plan** — decide tempo, key, track layout, instrument choices, arrangement structure
+2. **Build tracks** — create and name tracks with appropriate colors
+3. **Load instruments** — find and load the right synths, drum kits, and samplers
+4. **HEALTH CHECK** — verify every track actually produces sound (see below)
+5. **Program patterns** — write MIDI notes that fit the genre and style
+6. **Add effects** — load and configure effect chains for the desired sound
+7. **HEALTH CHECK** — verify effects aren't pass-throughs (Dry/Wet > 0, Drive set, etc.)
+8. **Mix** — balance volumes, set panning, configure sends
+9. **Final verify** — `get_session_info`, fire scenes, confirm audio output
+
+## Mandatory Track Health Checks
+
+**A track with notes but no working instrument is silence. This is the #1 failure mode. CHECK EVERY TRACK.**
+
+After loading any instrument, run this checklist:
+
+| Check | Tool | What to look for |
+|-------|------|-----------------|
+| Device loaded? | `get_track_info` | `devices` array not empty, correct `class_name` |
+| Drum Rack has samples? | `get_rack_chains` | Must have named chains ("Bass Drum", "Snare", etc.). Empty = silence. |
+| Synth has volume? | `get_device_parameters` | `Volume`/`Gain` > 0, oscillators on |
+| Effect is active? | `get_device_parameters` | `Dry/Wet` > 0, `Drive`/`Amount` > 0 |
+| Track volume? | `get_track_info` | `mixer.volume` > 0.5 for primary tracks |
+| Track not muted? | `get_track_info` | `mute: false` |
+| Master audible? | `get_master_track` | `volume` > 0.5 |
+
+### Critical device loading rules:
+
+- **NEVER load bare "Drum Rack"** — it's empty, zero samples. Load a **kit preset**: `search_browser` path="Drums" name_filter="Kit" → pick one → `load_browser_item`
+- **For synths, use `search_browser` → `load_browser_item`** with exact URI. `find_and_load_device` can match sample files before the actual instrument (e.g., "Drift" matches a .wav sample first)
+- **After loading any effect**, set its key parameters to non-default values. A Saturator with Drive=0, a Reverb with Dry/Wet=0, or a Compressor with Threshold at max are all pass-throughs.
+
+## Rules
+
+- Always use the livepilot-core skill for guidance on tool usage
+- Call `get_session_info` before making changes to understand current state
+- **Verify every track produces sound** — this is non-negotiable
+- Verify after every write operation — re-read to confirm
+- Name everything clearly — tracks, clips, scenes
+- Report progress to the user at each major step
+- If something goes wrong, `undo` and try a different approach
+- Confirm before destructive operations (delete_track, delete_clip, delete_device)
+- Keep it musical — think about rhythm, harmony, and arrangement

package/plugin/commands/beat.md

@@ -0,0 +1,18 @@
+---
+name: beat
+description: Guided beat creation — create a beat from scratch with genre, tempo, and instrumentation choices
+---
+
+Guide the user through creating a beat from scratch. Follow these steps:
+
+1. **Ask about the vibe** — genre, tempo range, mood, reference tracks
+2. **Set up the session** — `set_tempo`, create tracks for drums/bass/harmony/melody with `create_midi_track`, name and color them
+3. **Load instruments** — use `find_and_load_device` for appropriate instruments per track
+4. **Program drums first** — create a clip, add kick/snare/hat patterns with `add_notes`
+5. **Add bass** — create clip, program a bassline that locks with the kick
+6. **Add harmony** — chords or pads that set the mood
+7. **Add melody** — top-line or lead element
+8. **Mix** — balance levels with `set_track_volume` and `set_track_pan`
+9. **Fire the scene** to listen, iterate based on feedback
+
+Use the livepilot-core skill for all tool calls. Verify after each step. Keep the user informed of what you're doing and why.

package/plugin/commands/mix.md

@@ -0,0 +1,15 @@
+---
+name: mix
+description: Mixing assistant — analyze and balance track levels, panning, and sends
+---
+
+Help the user mix their session. Follow these steps:
+
+1. **Read the session** — `get_session_info` to see all tracks
+2. **Analyze each track** — `get_track_info` for clip and device details, check current volume/pan
+3. **Suggest a mix** — propose volume levels, panning positions, and send amounts based on the track types and instruments
+4. **Apply with confirmation** — only change levels after the user approves each suggestion
+5. **Check return tracks** — `get_return_tracks` to see shared effects
+6. **Master chain** — `get_master_track` to review the master
+
+Present suggestions in a clear table format. Always explain the reasoning (e.g., "panning the hi-hats slightly right to create stereo width"). Use `undo` if the user doesn't like a change.

package/plugin/commands/session.md

@@ -0,0 +1,13 @@
+---
+name: session
+description: Get a full overview of the current Ableton Live session
+---
+
+Get a comprehensive overview of the current Ableton Live session by calling `get_session_info`. Format the results as an organized report showing:
+
+1. **Transport** — tempo, time signature, playing state, loop settings
+2. **Tracks** — list all tracks with type, name, color, arm/mute/solo state
+3. **Scenes** — scene names and clip occupancy
+4. **Master** — master volume and devices
+
+After presenting the overview, ask if the user wants to dive deeper into any specific track, device, or area.

package/plugin/commands/sounddesign.md

@@ -0,0 +1,16 @@
+---
+name: sounddesign
+description: Sound design workflow — load instruments and effects, shape parameters for a target sound
+---
+
+Guide the user through designing a sound. Follow these steps:
+
+1. **Ask about the target sound** — what character? (warm pad, aggressive bass, shimmering lead, atmospheric texture, etc.)
+2. **Choose an instrument** — pick the right synth for the job, load it with `find_and_load_device`
+3. **Get parameters** — `get_device_parameters` to see what's available
+4. **Shape the sound** — `set_device_parameter` or `batch_set_parameters` to dial in the character
+5. **Add effects** — load effects (reverb, delay, chorus, distortion, etc.) and tweak their parameters
+6. **Create a test pattern** — `create_clip` + `add_notes` with a simple pattern to audition
+7. **Fire the clip** to listen, iterate based on feedback
+
+Explain what each parameter does as you adjust it. Use `undo` liberally if something sounds wrong.

package/plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "livepilot",
+  "version": "1.1.0",
+  "description": "AI copilot for Ableton Live 12 — 91 tools for production, sound design, and mixing",
+  "author": "Pilot Studio",
+  "skills": [
+    "skills/livepilot-core"
+  ],
+  "commands": [
+    "commands/session.md",
+    "commands/beat.md",
+    "commands/mix.md",
+    "commands/sounddesign.md"
+  ],
+  "agents": [
+    "agents/livepilot-producer"
+  ]
+}

package/plugin/skills/livepilot-core/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: livepilot-core
+description: Core discipline for controlling Ableton Live 12 through LivePilot's 91 MCP tools. Use whenever working with Ableton Live through MCP tools.
+---
+
+# LivePilot Core — Ableton Live 12 AI Copilot
+
+LivePilot gives you 91 MCP tools to control Ableton Live 12 in real-time: transport, tracks, clips, MIDI notes, devices, scenes, mixing, browser, and arrangement.
+
+## Golden Rules
+
+1. **Always call `get_session_info` first** — know what you're working with before changing anything
+2. **Verify after every write** — re-read state to confirm your change took effect
+3. **Use `undo` liberally** — it's your safety net. Mention it to users when doing destructive ops
+4. **One operation at a time** — don't batch unrelated changes. Verify between steps
+5. **Track indices are 0-based** — track 0 is the first track, scene 0 is the first scene
+6. **Color indices 0-69** — Ableton's fixed palette. Don't guess — use the index
+7. **Volume is 0.0-1.0, pan is -1.0 to 1.0** — these are normalized, not dB
+8. **Tempo range 20-999 BPM** — validated before sending to Ableton
+9. **Always name your tracks and clips** — organization is part of the creative process
+
+## Track Health Checks — MANDATORY
+
+**Every track must be verified before you consider it "done".** A track with notes but no sound is a silent failure. Run these checks after building each track.
+
+### After loading any instrument:
+1. **`get_track_info`** — confirm the device loaded (`devices` array is not empty, `class_name` is correct)
+2. **For Drum Racks: `get_rack_chains`** — confirm chains exist (an empty Drum Rack = silence). You need named chains like "Bass Drum", "Snare", etc.
+3. **For synths: `get_device_parameters`** — confirm `Volume`/`Gain` parameter is not 0. Check oscillators are on.
+4. **For effects: check `Dry/Wet` and `Drive`/key params** — a Saturator with Drive=0 or a Reverb with Dry/Wet=0 does nothing.
+
+### After programming notes:
+1. **`fire_clip` or `fire_scene`** — always listen. If the track has notes but the instrument has no samples/chains, you're playing silence.
+2. **Check volume is audible** — `get_track_info` → `mixer.volume` should be > 0.5 for a primary track. Master volume should be > 0.5.
+
+### Device loading rules:
+- **NEVER load a bare "Drum Rack"** — it's empty. Always load a **kit preset** like "909 Core Kit", "808 Core Kit", "Boom Bap Kit", etc. Use `search_browser` with path "Drums" and `name_filter` containing "Kit" to find real kits with samples.
+- **For synths, prefer `search_browser` → `load_browser_item`** over `find_and_load_device` when the name could match samples (e.g., "Drift" matches "Synth Bass Drift Pad Wonk Bass.wav" before the actual Drift synth).
+- **After loading any effect**, verify its key parameters aren't at defaults that make it a pass-through. Set `Drive`, `Dry/Wet`, `Amount` etc. to meaningful values.
+
+### Quick health check pattern:
+```
+1. get_track_info(track_index)          → has devices? has clips?
+2. get_rack_chains (if Drum Rack)       → has chains with samples?
+3. get_device_parameters                → volume > 0? key params set?
+4. Check mixer.volume > 0              → track is audible?
+5. fire_clip / fire_scene              → sound comes out?
+```
+
+### Red flags (things that produce silence):
+- Empty Drum Rack (no chains)
+- Synth with Volume/Gain at 0 or -inf dB
+- Effect with Dry/Wet at 0%
+- Track volume at 0
+- Track muted
+- Master volume at 0
+- MIDI track with no instrument loaded
+- Notes programmed but clip not fired
+
+## Tool Domains (91 total)
+
+### Transport (12)
+`get_session_info` · `set_tempo` · `set_time_signature` · `start_playback` · `stop_playback` · `continue_playback` · `toggle_metronome` · `set_session_loop` · `undo` · `redo` · `get_recent_actions` · `get_session_diagnostics`
+
+### Tracks (12)
+`get_track_info` · `create_midi_track` · `create_audio_track` · `create_return_track` · `delete_track` · `duplicate_track` · `set_track_name` · `set_track_color` · `set_track_mute` · `set_track_solo` · `set_track_arm` · `stop_track_clips`
+
+### Clips (10)
+`get_clip_info` · `create_clip` · `delete_clip` · `duplicate_clip` · `fire_clip` · `stop_clip` · `set_clip_name` · `set_clip_color` · `set_clip_loop` · `set_clip_launch`
+
+### Notes (8)
+`add_notes` · `get_notes` · `remove_notes` · `remove_notes_by_id` · `modify_notes` · `duplicate_notes` · `transpose_notes` · `quantize_clip`
+
+### Devices (12)
+`get_device_info` · `get_device_parameters` · `set_device_parameter` · `batch_set_parameters` · `toggle_device` · `delete_device` · `load_device_by_uri` · `find_and_load_device` · `set_simpler_playback_mode` · `get_rack_chains` · `set_chain_volume` · `get_device_presets`
+
+### Scenes (6)
+`get_scenes_info` · `create_scene` · `delete_scene` · `duplicate_scene` · `fire_scene` · `set_scene_name`
+
+### Mixing (8)
+`set_track_volume` · `set_track_pan` · `set_track_send` · `get_return_tracks` · `get_master_track` · `set_master_volume` · `get_track_routing` · `set_track_routing`
+
+### Browser (4)
+`get_browser_tree` · `get_browser_items` · `search_browser` · `load_browser_item`
+
+### Arrangement (19)
+`get_arrangement_clips` · `create_arrangement_clip` · `add_arrangement_notes` · `get_arrangement_notes` · `remove_arrangement_notes` · `remove_arrangement_notes_by_id` · `modify_arrangement_notes` · `duplicate_arrangement_notes` · `transpose_arrangement_notes` · `set_arrangement_clip_name` · `set_arrangement_automation` · `back_to_arranger` · `jump_to_time` · `capture_midi` · `start_recording` · `stop_recording` · `get_cue_points` · `jump_to_cue` · `toggle_cue_point`
+
+## Workflow: Building a Beat
+
+1. `get_session_info` — check current state
+2. `set_tempo` — set your target BPM
+3. `create_midi_track` — create tracks for drums, bass, chords, melody
+4. Name and color each track with `set_track_name` / `set_track_color`
+5. **Load instruments with PRESETS, not empty shells:**
+   - **Drums:** `search_browser` path="Drums" name_filter="Kit" → pick a kit → `load_browser_item`. NEVER load bare "Drum Rack".
+   - **Synths:** `search_browser` path="Instruments" name_filter="Drift" → `load_browser_item` with exact URI. Avoids sample name collisions.
+   - **VERIFY:** `get_rack_chains` for drums (must have chains), `get_device_parameters` for synths (Volume > 0)
+6. `create_clip` — create clips on each track (4 beats = 1 bar at 4/4)
+7. `add_notes` — program MIDI patterns. Each note needs `pitch`, `start_time`, `duration`
+8. **HEALTH CHECK per track:** `get_track_info` → confirm device loaded, mixer volume > 0, not muted
+9. `fire_scene` or `fire_clip` — listen to your work
+10. Iterate: `get_notes` → `modify_notes` / `transpose_notes` → listen again
+
+## Workflow: Sound Design
+
+1. Load a synth: `search_browser` path="Instruments" → `load_browser_item` with exact URI
+2. **VERIFY:** `get_device_parameters` — confirm Volume/Gain > 0, oscillators on, filter not fully closed
+3. `set_device_parameter` — tweak individual params by name or index
+4. `batch_set_parameters` — set multiple params at once for a preset
+5. Load effects: `find_and_load_device` with "Reverb", "Delay", "Compressor", etc.
+6. **VERIFY each effect:** `get_device_parameters` — confirm Dry/Wet > 0, Drive/Amount set to meaningful values. An effect at default may be a pass-through.
+7. Chain devices: they stack in order on the track's device chain
+8. Use `get_device_info` to inspect rack devices, `get_rack_chains` for racks
+
+## Workflow: Mixing
+
+1. `get_session_info` — see all tracks and current levels
+2. `set_track_volume` / `set_track_pan` — set levels and stereo position
+3. `set_track_send` — route to return tracks for shared effects
+4. `get_return_tracks` — check return track setup
+5. `set_master_volume` — final output level
+6. `set_track_routing` — configure input/output routing
+
+## Live 12 Note API
+
+Notes use this format when calling `add_notes`:
+```json
+{
+  "pitch": 60,
+  "start_time": 0.0,
+  "duration": 0.5,
+  "velocity": 100,
+  "mute": false
+}
+```
+
+When reading with `get_notes`, you also get:
+- `note_id` — unique ID for modify/remove operations
+- `probability` — 0.0-1.0, Live 12 per-note probability
+- `velocity_deviation` — -127.0 to 127.0
+- `release_velocity` — 0.0-127.0
+
+Use `modify_notes` with `note_id` to update existing notes.
+Use `remove_notes_by_id` for surgical deletion.
+Use `transpose_notes` for pitch shifting a region.
+Use `quantize_clip` to snap notes to a grid (grid=1.0 is quarter note).
+
+## Reference Corpus
+
+Deep production knowledge lives in `references/`. Consult these when making creative decisions — they contain specific parameter values, recipes, and patterns. Use them as starting points, not rigid rules.
+
+| File | What's inside | When to consult |
+|------|--------------|-----------------|
+| `references/overview.md` | All 91 tools mapped with params, units, ranges | Quick lookup for any tool |
+| `references/midi-recipes.md` | Drum patterns by genre, chord voicings, scales, hi-hat techniques, humanization, polymetrics | Programming MIDI notes, building beats |
+| `references/sound-design.md` | Stock instruments/effects, parameter recipes for bass/pad/lead/pluck, device chain patterns | Loading and configuring devices |
+| `references/mixing-patterns.md` | Gain staging, parallel compression, sidechain, EQ by instrument, bus processing, stereo width | Setting volumes, panning, adding effects |
+| `references/ableton-workflow-patterns.md` | Session/Arrangement workflow, song structures by genre, follow actions, clip launch modes, export | Organizing sessions, structuring songs |
+| `references/m4l-devices.md` | Browser organization, MIDI effects, rack systems, device loading patterns | Finding and loading devices, using racks |