AbletonBuddy

February 14, 2026

Tools

Claude CodeTypeScriptNode.jsMax for LivetonalVitestWebSocketZod

What worked

7 full phases shipped in ~1.5 hours of AI collaboration (70+ commits): ALS parser, M4L devices + WebSocket bridge, MIDI generation, audio analysis, phrase-level probes. Claude Code handled the undocumented ALS XML format, kept preserveOrder round-trips lossless, and produced reference lookup tables (625 lines) as structured data instead of essays.

What broke

The M4L JavaScript threading model (low-priority thread) caused intermittent data loss under CPU load — a platform constraint no amount of prompting fixes. essentia.js was a stale dependency (last published 4 years ago) whose Node 22 compatibility needed manual verification. Non-unique Pointee IDs in ALS files crashed early versions; the fix required understanding an undocumented format.

Roles

I set the architectural direction (file-mediated IPC instead of API calls because Claude MAX has no API key, WebSocket over OSC for structured data, three-layer ALS system). Claude Code wrote the parsers, generators, and bridge server; I reviewed and chose tonal over hand-rolled music theory. The coaching mode taxonomy and Push3 workflow references were my editorial calls, executed by Claude.

AbletonBuddy (AI Songwriting Companion)

Overview

AbletonBuddy is a Claude-powered AI songwriting companion embedded in Ableton Live via Max for Live devices and a Claude Code CLI skill. It bridges the critical gap between having individual musical clips and finishing complete arranged songs — the "clip graveyard" problem.

Core value: Get from "I have a musical idea" to "I'm recording in a structured Ableton project" as fast as possible.

Target users: Music producers using Ableton Live Suite (with Max for Live) and Claude MAX subscription.

Key Features

Session-aware coaching — References actual tracks, clips, devices, keys from user's live session or saved ALS files
Four coaching modes: Coaching (what to do next), Framework (song structure templates), Constraint (creative limitations), Techniques (Ableton/Push3 workflow)
MIDI generation — Chord progressions, bass lines, melodies using tonal library for music theory
Arrangement analysis — How to organize clips into verse/chorus/bridge structures
Production intelligence — Signal-grounded mixing advice from audio analysis probes (RMS, peak, spectral centroid, dynamics)
ALS file handling — Read/write/modify Ableton Live Set files safely with backup protection
Phrase-level analysis — Transport-synced audio capture tied to arrangement sections

Architecture

Tech Stack

Layer	Technology
Core	TypeScript 5.9 (strict mode), Node.js 22 LTS
CLI	Claude Code skills system
Music Theory	tonal 6.4.3
XML Parsing	fast-xml-parser 5.3.6 (preserveOrder for lossless ALS round-tripping)
WebSocket	ws 8.19.0 (M4L <-> Node.js bridge)
Validation	Zod 4.3.6
M4L Devices	Max 9 v8/node.script objects
Testing	Vitest 4.0.18

Data Flow

ABLETON LIVE (M4L Devices)
  ├─ Session Awareness (master track)
  ├─ Track Intent (per track)
  └─ Probe (per track, optional)
         │ WebSocket (ws://127.0.0.1:9876)
         v
   BRIDGE SERVER (Node.js)
     ├─ SessionAggregator (in-memory state)
     ├─ BuddyWriter (atomic JSON to .buddy/)
     └─ CommandDispatcher (Claude -> Ableton)
         │ .buddy/ directory (file-mediated IPC)
         v
   CLAUDE CODE (Interactive CLI)
     ├─ Session Reader
     ├─ ALS Generator
     ├─ MIDI Generator
     └─ Production Analyzer

Key Design Decisions

File-mediated architecture instead of API calls — MAX subscription lacks API key support
WebSocket over OSC — Bidirectional, JSON-native, better for structured data
Custom ALS parser — No existing library supports both read+write; preserveOrder mode for lossless round-trips
Three-layer ALS system: Low-level parser -> High-level reader -> Writer/modifier
Atomic writes (.tmp -> rename) — Prevent Claude reading partial files

Structure

livebuddy/
├── src/
│   ├── als/          # ALS file parsing/writing (parser, builder, reader, writer, modifier)
│   ├── midi/         # MIDI generation engine (generator, patterns, xml-helpers)
│   ├── bridge/       # WebSocket bridge server (session aggregator, commands)
│   ├── cli/          # CLI interface (context-reader, actions, bridge-status)
│   └── ...           # midi-analysis, production-intelligence, summary
├── devices/          # Max for Live device patchers
│   ├── session-awareness/
│   ├── track-intent/
│   ├── probe/
│   └── shared/
├── .claude/skills/buddy/  # Claude Code skill definition + 6 reference lookup tables
└── tests/

Development History

7 phases executed in ~1.5 hours of AI collaboration, 70+ commits:

Phase	Focus	Duration
1	ALS Parser Foundation (safe read/write without corruption)	16 min
2	M4L Devices + WebSocket Bridge	17 min
3	CLI Skill + 4 Coaching Modes	6 min
4	MIDI Generation (chord progressions, bass lines)	14 min
5	Audio Analysis (production intelligence rules engine)	11 min
6	Phrase-Level Analysis (transport-synced bar statistics)	6 min
7	Technique Reference (Ableton/Push3 workflow guidance)	13 min

Strengths

Robust ALS handling — Comprehensive error handling for undocumented format; backup before every modification
Lossless XML — preserveOrder + ID management prevents data loss on round-trips
Music theory grounding — tonal library eliminates hand-rolled chord logic
Graceful degradation — Works without bridge (ALS-only mode), without probes (intent/session mode)
User-first UX — Always suggests, never executes; batch interactions, M4L devices are set-and-forget
Reference files as lookup tables — 625 lines of structured reference (not essays)

Weaknesses & Risks

ALS format fragility — Undocumented format, changes between versions; non-unique Pointee IDs cause crashes
essentia.js stale dependency — Last published 4 years ago; Node 22 compatibility unverified
M4L JavaScript threading — Low-priority thread can cause data loss/reordering under CPU load
No undo integration — Generated clips don't hook into Ableton's undo system
No Live 11 validation — Only tested against Live 12 ALS schema

Connection to Other Projects

Etyde — Both deal with music learning/creation; AbletonBuddy for production, Etyde for practice
Roughneck — Could potentially route AI analysis through Roughneck's Ollama queue

andrewlb notes