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