ableton-mcp-ai/CLAUDE.md

Project CLAUDE.md

This is the canonical project context file for any AI agent working in this repository.

If you are Kimi K2, Claude Code, Codex, GLM, Qwen, or any other model:

• read this file first
• treat it as the highest-signal project handoff
• use it before exploring code, making edits, debugging, or declaring success

Mission

This project is not a toy loop generator.

The goal is to operate Ableton Live 12 through MCP and a Remote Script so an AI agent can:

• inspect the Live set
• create and edit tracks and clips
• generate musical arrangements
• analyze references
• retrieve local samples
• leave the final result audible, editable, and stable

Mandatory Read Order

Read in this order before doing substantial work:

1. C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\CLAUDE.md
2. C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\KIMI_K2_START_HERE.md
3. C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\KIMI_K2_ACTIVE_HANDOFF.md
4. C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\docs\ROADMAP.md
5. inspect the active entrypoints and code directly

Do not trust stale docs over live code. Do not trust live code over runtime evidence.

Project Roots

User-facing project root:

• C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts

Actual MCP code root used by the wrapper:

• C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI

Environment Rules

This machine is using native Windows paths.

• prefer PowerShell commands, not bash
• do not use /c/... paths
• do not assume Program Files if the executable was already verified elsewhere
• when in doubt, use the exact absolute paths documented in this file

Verified executable paths:

• active Ableton install: C:\ProgramData\Ableton\Live 12 Suite\Program\Ableton Live 12 Suite.exe
• backup or parallel updated install: C:\ProgramData\Ableton\.Live 12 Suite_updated\Program\Ableton Live 12 Suite.exe

Current Active Execution Paths

MCP used by Claude Code and opencode

• 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\mcp_wrapper.py
• C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py

Remote Script used by Ableton Live

• C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\__init__.py
• C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\Remote_Script.py

Important:

• those shims currently prefer abletonmcp_init.py
• the backup runtime only remains as fallback

This means the canonical runtime is now the root abletonmcp_init.py.

Source Of Truth Rules

Before changing code, answer these questions with evidence:

1. Which file is the active entrypoint for this path?
2. Which file is actually loaded at runtime?
3. Is the bug in the MCP server, the wrapper, or the Live runtime?
4. Can the bug be confirmed with logs, compile output, or direct socket checks?

If you cannot answer those, you are not ready to patch.

Non-Negotiable Engineering Rules

• Do not guess the active runtime.
• Do not patch dead files first.
• Do not assume a timeout means failure.
• Do not assume a success string means Live is healthy.
• Do not declare success without runtime validation.
• Do not break get_session_info, get_tracks, or generate_track.
• Do not create a second architecture when one already exists.
• Do not use the backup tree as the long-term source of truth.
• Do not edit random helper scripts and call that a fix.

What Success Looks Like

A fix is only real if most of these are true:

• the MCP connects
• Ableton loads the AbletonMCP_AI Control Surface
• the socket is listening on 127.0.0.1:9877
• get_session_info responds quickly
• get_tracks responds consistently
• Ableton remains responsive during mutations
• generation does not trigger Audio queue timeout
• the final set is audible and editable

Best Practices For Working In This Repo

1. Start from the active path, not from file names

There are duplicate and legacy files:

• multiple servers
• backup runtimes
• moved trees
• legacy utility scripts

Always start from the wrapper or shim that is actually being executed.

2. Separate the layers mentally

This project has three separate layers:

• MCP transport and tool layer
• socket protocol layer
• Ableton Remote Script / Live API layer

Many bugs come from fixing the wrong layer.

3. Prefer runtime evidence over theory

Use:

• Ableton log
• compile output
• direct socket probes
• MCP tools/list
• get_session_info
• get_tracks

Do not argue with logs.

4. Keep Live API mutations short

Long or monolithic work on the Live thread is dangerous.

If a task touches Live objects:

• keep each mutation small
• avoid large blocking batches
• do heavy planning outside the Live thread
• schedule short main-thread operations when required

5. Compile changed Python files

Before testing runtime changes, compile the touched Python files.

Useful pattern:

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_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"

6. Validate both MCP and Live

MCP can be healthy while Live is broken. Live can be listening while generation still crashes it.

Check both.

7. Prefer one source of truth

If you are cleaning architecture:

• pick one canonical Remote Script runtime
• pick one canonical MCP server
• retire or isolate dead variants

Do not leave three half-working options.

High-Value Files

Read these first when debugging real behavior:

• 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_AI\__init__.py
• C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\Remote_Script.py
• 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_AI_BAK_20260328_200801\Remote_Script.py
• C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py
• C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\song_generator.py
• C:\Users\ren\AppData\Roaming\Ableton\Live 12.0.15\Preferences\Log.txt

Known Current Reality

As of the latest audit:

• Claude Code and opencode can connect to the MCP
• Ableton can load the AbletonMCP_AI Control Surface
• server.py currently exposes unique tools without duplicate registrations
• the active runtime path now points to abletonmcp_init.py first
• generate_song can materialize audio fallback in Arrangement
• server_v2.py does not compile
• clear_all_tracks still has a soft failure at the end of cleanup
• Z.ai can return 429 and force fallback heuristics

If your task involves repairs, read KIMI_K2_START_HERE.md and KIMI_K2_ACTIVE_HANDOFF.md immediately after this file.

Fast Diagnostic Checklist

When MCP fails to appear

Check:

• .mcp.json
• opencode.json
• mcp_wrapper.py
• C:\Users\ren\.claude.json if Claude behaves differently from project config

When Ableton does not show the Control Surface

Check:

• AbletonMCP_AI\__init__.py
• AbletonMCP_AI\Remote_Script.py
• Ableton log for MidiRemoteScript

When Ableton listens on 9877 but commands hang or crash

Check:

• newline framing in socket responses
• thread model in the Remote Script
• long Live API operations during generation
• Ableton log for Audio queue timeout

When a generation times out

Do this before declaring failure:

1. inspect Ableton log
2. query get_session_info
3. query get_tracks
4. verify whether the set changed anyway

Commands Worth Remembering

Read Ableton log tail:

Get-Content "C:\Users\ren\AppData\Roaming\Ableton\Live 12.0.15\Preferences\Log.txt" -Tail 120

Check if Live socket is listening:

netstat -an | findstr 9877

Compile active MCP and runtime files:

python -m compileall "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI" "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\abletonmcp_init.py"

Launching Ableton Safely

Use the real Ableton executable:

• active install: C:\ProgramData\Ableton\Live 12 Suite\Program\Ableton Live 12 Suite.exe
• backup or parallel updated install: C:\ProgramData\Ableton\.Live 12 Suite_updated\Program\Ableton Live 12 Suite.exe

Preferred restart policy:

1. if Live is responsive, close it normally first
2. only use taskkill if Live is hung or a script crash left zombie processes
3. wait a few seconds before relaunching
4. relaunch the executable directly

Known helper script:

• C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\restart_ableton.bat

Do not invent alternate launch paths. Do not copy files into random Ableton installs and then launch a different binary.

Recovery Popup Suppression

If the user explicitly wants to skip the recovery popup after a crash, clean the active recovery file before relaunching Live:

• C:\Users\ren\AppData\Roaming\Ableton\Live 12.0.15\Preferences\CrashRecoveryInfo.cfg

Important:

• this discards the pending crash-recovery state for the last session
• do this only when the user wants to suppress the popup
• do not delete the whole Crash folder under Preferences
• CrashDetection.cfg may remain; the popup-relevant file is CrashRecoveryInfo.cfg

Safe PowerShell pattern:

$liveExe = 'C:\ProgramData\Ableton\Live 12 Suite\Program\Ableton Live 12 Suite.exe'
$recoveryFile = 'C:\Users\ren\AppData\Roaming\Ableton\Live 12.0.15\Preferences\CrashRecoveryInfo.cfg'

Get-Process 'Ableton Live 12 Suite' -ErrorAction SilentlyContinue | Stop-Process -Force
Get-Process 'AbletonPushCpl' -ErrorAction SilentlyContinue | Stop-Process -Force
Get-Process 'Ableton Index' -ErrorAction SilentlyContinue | Stop-Process -Force
Start-Sleep -Seconds 3

if (Test-Path $recoveryFile) {
    Remove-Item -LiteralPath $recoveryFile -Force
}

Start-Process -FilePath $liveExe

After relaunch:

1. wait 10 to 15 seconds for full startup
2. verify the process is still alive
3. inspect C:\Users\ren\AppData\Roaming\Ableton\Live 12.0.15\Preferences\Log.txt before declaring success

If a task requires preserving the unsaved recovery state, do not remove CrashRecoveryInfo.cfg.

Working Mindset

Be skeptical. Be concrete. Verify everything important.

In this repo, the intelligent agent is not the one that writes the most code. It is the one that identifies the active runtime, patches the correct layer, and proves the fix with evidence.