# 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:

```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_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:

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

Check if Live socket is listening:

```powershell
netstat -an | findstr 9877
```

Compile active MCP and runtime files:

```powershell
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:

```powershell
$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.