200 lines
7.2 KiB
Markdown
200 lines
7.2 KiB
Markdown
# CLAUDE.md
|
|
|
|
Canonical project context for AI agents working in this repository.
|
|
|
|
Read this file after `AGENTS.md` and before doing substantial work.
|
|
|
|
## Mission
|
|
|
|
The repository exists to control Ableton Live 12 through MCP and a Remote Script so an AI agent can:
|
|
|
|
- inspect the current Live set
|
|
- create and edit tracks and clips
|
|
- generate arrangements when needed
|
|
- edit already-open `.als` projects
|
|
- retrieve local samples and references
|
|
- leave the final result audible, editable, and stable
|
|
|
|
This project is judged by runtime truth in Ableton, not by pretty manifests or optimistic reports.
|
|
|
|
## Current Operating Mode
|
|
|
|
The preferred workflow is currently manual:
|
|
|
|
- Codex reviews and fixes
|
|
- Kimi/OpenCode or GLM/OpenCode implement coding tasks
|
|
- tasks are handed off via markdown
|
|
- blind background autopilot is not the default working mode
|
|
|
|
There is automation code under `ralph\`, but do not assume it is the active workflow unless the task explicitly says so.
|
|
|
|
## Current Product Direction
|
|
|
|
The center of gravity has shifted from "generate a whole song from scratch" to:
|
|
|
|
- edit the currently open Live project
|
|
- improve coherence and continuity
|
|
- reduce silent holes and rigid visual symmetry
|
|
- keep harmonic material alive across the arrangement
|
|
- blend library audio with harmonic MIDI when useful
|
|
- avoid automatic vocals
|
|
|
|
Important nuance:
|
|
|
|
- "piano roll" means harmonic MIDI is acceptable and desired
|
|
- it does not mean the arrangement should be forced toward piano timbres
|
|
|
|
## Active Paths
|
|
|
|
User-facing project root:
|
|
|
|
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts`
|
|
|
|
Active code root:
|
|
|
|
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI`
|
|
|
|
Current open-project target:
|
|
|
|
- `C:\Users\ren\Desktop\song Project\song.als`
|
|
|
|
Active MCP and runtime entrypoints:
|
|
|
|
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\mcp_wrapper.py`
|
|
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\.mcp.json`
|
|
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\opencode.json`
|
|
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\abletonmcp_init.py`
|
|
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\abletonmcp_runtime.py`
|
|
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py`
|
|
|
|
## Mandatory Questions Before Patching
|
|
|
|
1. Which file is the active entrypoint?
|
|
2. Which layer owns the bug?
|
|
3. Can the bug be reproduced with logs, MCP calls, tests, or Live inspection?
|
|
4. How will you prove the fix after the patch?
|
|
|
|
If those answers are weak, the patch will likely be weak.
|
|
|
|
## The Three Layers
|
|
|
|
Keep them separate in your head:
|
|
|
|
1. MCP transport and public tool layer
|
|
2. socket protocol or runtime bridge
|
|
3. Ableton Remote Script or Live API layer
|
|
|
|
Many bad fixes happened because someone patched the wrong layer.
|
|
|
|
## Source Of Truth Rules
|
|
|
|
Use this order of trust:
|
|
|
|
1. current Live state
|
|
2. MCP responses and exact tool calls
|
|
3. Ableton log
|
|
4. code
|
|
5. old sprint reports
|
|
|
|
Do not trust a report that says `COMPLETED` if Live still shows an empty or repetitive arrangement.
|
|
|
|
## Working Rules
|
|
|
|
- Use PowerShell, not bash.
|
|
- Use absolute Windows paths in scripts and docs.
|
|
- Compile changed Python files before runtime testing.
|
|
- Keep Live mutations short and explicit.
|
|
- Prefer inspection first, mutation second.
|
|
- Do not turn every issue into a new architecture.
|
|
- Do not patch backup trees first.
|
|
|
|
## Runtime Validation Checklist
|
|
|
|
At minimum, after meaningful runtime changes check:
|
|
|
|
- `get_session_info`
|
|
- `get_tracks`
|
|
- the relevant inspection tool for the edited object
|
|
- Ableton log if anything hangs or times out
|
|
|
|
If the task is about editing the open project:
|
|
|
|
- inspect the edited tracks, clips, and devices after mutation
|
|
- capture before and after evidence
|
|
- do not rely on manifest-only proof
|
|
|
|
## Build / Test Commands
|
|
|
|
Compile common active files:
|
|
|
|
```powershell
|
|
python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\mcp_wrapper.py"
|
|
python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\abletonmcp_init.py"
|
|
python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\abletonmcp_runtime.py"
|
|
python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py"
|
|
python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\song_generator.py"
|
|
python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\reference_listener.py"
|
|
```
|
|
|
|
Run targeted tests:
|
|
|
|
```powershell
|
|
python -m unittest discover "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\tests"
|
|
python -m pytest "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\tests\test_runtime_truth.py"
|
|
python -m unittest "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\tests\test_runtime_truth.py.TestRuntimeTruthHelpers.test_public_set_device_parameter_supports_parameter_name"
|
|
```
|
|
|
|
Useful diagnostics:
|
|
|
|
```powershell
|
|
Get-Content "C:\Users\ren\AppData\Roaming\Ableton\Live 12.0.15\Preferences\Log.txt" -Tail 120
|
|
netstat -an | findstr 9877
|
|
opencode mcp list --print-logs
|
|
```
|
|
|
|
## Known Current Reality
|
|
|
|
- MCP connection can be healthy even when an arrangement edit path is still broken.
|
|
- The repo already contains a lot of tooling for project inspection and partial project editing.
|
|
- Open-project editing is the next quality frontier, not just raw generation.
|
|
- Harmonic MIDI often exists conceptually before it is truly materialized in Arrangement; validate that distinction carefully.
|
|
- The repo has drifted before into overly symmetrical, silent, loopy arrangements; current tasks should fight that.
|
|
|
|
## High-Value Files
|
|
|
|
- `AGENTS.md`
|
|
- `CLAUDE.md`
|
|
- `KIMI_K2_START_HERE.md`
|
|
- `KIMI_K2_ACTIVE_HANDOFF.md`
|
|
- `docs\PROJECT_AUDIT_song_2026-04-03.md`
|
|
- `mcp_wrapper.py`
|
|
- `abletonmcp_init.py`
|
|
- `AbletonMCP_AI\abletonmcp_runtime.py`
|
|
- `AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py`
|
|
- `AbletonMCP_AI\AbletonMCP_AI\MCP_Server\song_generator.py`
|
|
- `AbletonMCP_AI\AbletonMCP_AI\MCP_Server\reference_listener.py`
|
|
|
|
## What Good Looks Like Now
|
|
|
|
A strong result in the current phase looks like this:
|
|
|
|
- the open project remains stable
|
|
- MCP tools can inspect and edit meaningful parts of the set
|
|
- harmonic backbone exists in Arrangement, not only in Session or metadata
|
|
- fewer structural gaps
|
|
- less rigid mirrored repetition
|
|
- sound choices feel coherent but not trapped in 3 identical loops forever
|
|
- the project is easier to continue editing by hand afterward
|
|
|
|
## Anti-Patterns
|
|
|
|
- claiming success from reports alone
|
|
- calling every harmonic MIDI lane "piano" and forcing piano presets
|
|
- overvaluing manifest metrics when Live still sounds wrong
|
|
- using old or backup files as the first patch target
|
|
- treating a timeout as definitive proof of failure without inspecting Live
|
|
|
|
## Practical Reminder
|
|
|
|
If a user says "this doesn't look or sound like a song," that feedback outranks a self-congratulatory validation report.
|