Getting Started

This guide walks through your first working Live Extension using the Patchwright desktop app — the path verified against Ableton Live 12.4.5+.

For the full product contract, see SPEC.md. For private-alpha field trials, see FIRST-USER-BETA-PACKET.md.

New: The User Manual is the producer-facing guide. This Getting Started page is the 15-minute first win. For node lookup, see NODE-REFERENCE.md and the generated NODE-CATALOG.generated.md.

Before you begin

You need:

  1. macOS (aarch64 — Apple Silicon)
  2. Ableton Live 12 Suite 12.4.5 or newer with Extensions enabled
  3. Developer Mode ON: Live → Settings → Extensions → Developer Mode
  4. Patchwright desktop app (DMG or built from source — DEVELOPMENT.md)

If you only have Live 12.4.2 Suite, the Extension Host module is not present and Patchwright cannot run extensions in Live.

Install Patchwright

From DMG (private alpha)

  1. Mount Patchwright_0.1.0_aarch64.dmg (or the current artifact from your distributor).
  2. Drag Patchwright to Applications.
  3. Open Patchwright. macOS may warn the app is unsigned — expected for private alpha.

From source

Prerequisites: Node.js ≥ 22.11.0, Rust toolchain (edition 2021), Swift 6.2+ (for the Apple FM sidecar).

cd app
npm install
npm run tauri:dev

tauri:dev starts both the Vite dev server (port 5173) and the Tauri desktop shell with hot-reload.

First extension (Scale-Aware Chord/Arp)

This is the verified happy path.

1. Open a starter template

Launch Patchwright and choose Scale-aware chord/arp generator from onboarding (or Templates).

2. Confirm Extension Host

If prompted, open Host settings and select your Live 12 Suite Extension Host path, for example:

/Applications/Ableton Live 12 Beta.app/Contents/Helpers/ExtensionHost/ExtensionHostNodeModule.node

Patchwright should show host detection success in the toolbar.

3. Build & Run

  1. Click Build & Run.
  2. Wait for status Connected to Live.
  3. Switch to Ableton Live.

4. Run the command in Live

  1. Create or select a MIDI clip.
  2. Right-click the clip → Extensions → choose the Scale-Aware Chord Arp command.
  3. Confirm MIDI notes appear in the clip.

5. Export `.ablx` (optional)

After Build & Run works, use Build .ablx to export an installable package. Install via Live → Settings → Extensions.

Using the AI assistant

Patchwright routes AI requests through a priority chain: Apple Foundation Models (on-device, no key required, Apple Silicon desktop only) → Anthropic Claude (BYO API key) → OpenAI (BYO API key) → local endpoint (Ollama / LM Studio).

  1. Open the AI panel.
  2. Choose a provider in Settings:
    • Apple Foundation Models — available automatically on Apple Silicon desktop (macOS 26+); no API key required.
    • Anthropic — enter your Claude API key (stored locally in settings.json, never in the graph).
    • OpenAI — enter your OpenAI API key (stored locally in settings.json, never in the graph).
    • Local — point to a running Ollama or LM Studio server.
  3. Describe what you want: "Right-click a MIDI clip and transpose all notes up a fifth."
  4. Review the generated graph, then Build & Run.

The assistant validates graphs by running a full build before you apply changes.

Health & self-heal (Doctor)

The Health section in Settings runs preflight checks against your environment and can auto-fix common problems.

Six named checks run on desktop:

Check What it verifies
node-version Checks system node --version on the PATH (requires major ≥ 22); shown as 'Build tools' / 'build runtime' in the Health UI
sdk-js-vendored Vendored Ableton SDK runtime is present and valid
sdk-dts-vendored SDK TypeScript declarations are bundled
catalog-json Node descriptor catalog is intact
patchwright-detected Checks whether the patchwright CLI binary is on the system PATH or present as a repo-checkout binary; shown as 'Command-line tool' / 'The patchwright command is available on your PATH.' in the Health UI
ableton-live-macos Live 12 Suite 12.4.5+ is installed

Checks marked fixable offer a one-click fix flow: dry-run preview → your consent → apply → re-verify. Guidance-only checks (node-version, ableton-live-macos) show instructions but do not mutate anything.

In the web-only path, filesystem-dependent checks show as not checkable here (not false alarms).

Telemetry

Patchwright includes opt-in flywheel telemetry (PostHog, EU endpoint). It is:

  • Off by default in standard/OSS builds — requires VITE_TELEMETRY_ENABLED=true at build time.
  • Content-free — no graph content, no prompts, no PII; only structural events (e.g., codegen_completed with violation count).
  • Consent-gated — surfaced in the Settings → Privacy section; can be toggled at any time.

Web-only path (no Live bridge)

  1. Open the web studio (Vite dev server or deployed build).
  2. Wire nodes or use AI describe.
  3. Export .ablx and install manually in Live.

You cannot Build & Run from the browser. The Doctor checks that require filesystem access show as not checkable here in the web path.

CLI quick path

For agents and terminal users:

cd cli && npm install
npx tsx src/index.ts detect --json
npx tsx src/index.ts doctor --json

Or if you have the compiled binary on your PATH:

patchwright detect --json
patchwright doctor --json

See SPEC.md § CLI Reference for the full command surface.

Troubleshooting

Symptom Check
Host not found Live 12.4.5+ Suite installed; correct Extension Host path in Settings
Build & Run fails Developer Mode enabled in Live; check Health section for failing checks
No command in context menu Build & Run completed; correct trigger scope (MIDI clip); restart Live if needed
AI describe fails Valid API key set, or local server running (curl localhost:11434/api/tags), or Apple FM available on Apple Silicon desktop
Doctor check fails with no fix offered Guidance-only check — follow the on-screen instructions

Capture diagnostics per FIRST-USER-BETA-PACKET.md § Evidence To Capture.

Next steps