claude-music

Live AI background music for Claude Code, scored in real time by Claude itself. You type /music, music starts playing, and as Claude works it silently steers the soundtrack to match — calm and ambient while reading, driving and intense while grinding through a hard problem, a victory lap when the tests go green.

Powered by Google's Magenta RealTime 2 (mrt2_small, 230M params) running locally on Apple Silicon.

Install

npm install -g claude-music   # or: pnpm add -g claude-music
claude-music install

claude-music install downloads the prebuilt audio daemon and a model, registers the MCP server with Claude Code, and installs the /music command. In a terminal it prompts for which model to use; pass --model small|base to choose without a prompt:

claude-music install --model small   # ~0.5 GB, realtime on any Apple Silicon (default)
claude-music install --model base    # ~2.8 GB, higher quality, realtime on M2 Pro+

Small is the default — smallest download and realtime on any Apple Silicon, so it's the safe pick for older Macs. Base sounds better and runs in realtime on M2 Pro and above (and usually on M1 too). The ~1.4 GB of shared resources download once and are reused by both, so switching models only re-downloads the model itself. Restart Claude Code after installing so it loads the MCP server, then:

/music          # start — Claude picks an opening vibe
/music stop     # stop
/music status   # what's currently playing

Once running you don't need to do anything — Claude re-vibes on its own as the work changes, and music stops when you end the session.

Requirements

• Apple-Silicon Mac (M-series) — required by MLX/Metal.
• Node ≥ 18 and the claude CLI (Claude Code).
• ~1.7 GB of disk for the model + resources, downloaded on first install.

No Xcode, CMake, or Python needed — the daemon ships as a prebuilt binary. (If a prebuilt binary can't be fetched, install falls back to building from source, which does require Xcode CLT + CMake.)

How it works

Claude Code ──set_music_vibe(prompt)──▶ mrt2-mcp (the `claude-music mcp` server)
  ──JSON over ~/.mrt2d.sock──▶ mrt2d (C++ daemon, links magentart::core) ──CoreAudio──▶ ♪

• mrt2d — a C++ daemon wrapping magentart::core::RealtimeRunner, streaming audio to CoreAudio and taking prompt commands over a Unix socket. Cached at ~/.claude-music/bin/mrt2d. Source lives in daemon/.
• MCP server (src/server.ts, run via claude-music mcp) — exposes set_music_vibe / stop_music. The vibe tool auto-spawns the daemon, so starting music is a single silent tool call.
• templates/music.md — the /music slash command, installed to ~/.claude/commands/music.md.
• The model + resources download to ~/Documents/Magenta/magenta-rt-v2/.

CLI

claude-music install        download daemon + model, register MCP, install /music
claude-music uninstall      remove MCP registration + /music  (--purge: also delete cache + model)
claude-music doctor         check that everything is installed
claude-music start|stop|status
claude-music mcp            run the MCP server (used internally by Claude Code)

Override the daemon binary with MRT2D_BIN, or its download URL with CLAUDE_MUSIC_BINARY_URL.

Maintainers — cutting a release

The prebuilt daemon is produced by scripts/build-release.sh, which builds mrt2d against a fresh magenta-realtime checkout, bundles its non-system dylibs with @loader_path rewrites, and emits dist-release/mrt2d-darwin-arm64.tar.gz:

bash scripts/build-release.sh
# test the artifact end-to-end before publishing:
CLAUDE_MUSIC_BINARY_URL="file://$PWD/dist-release/mrt2d-darwin-arm64.tar.gz" claude-music install
# publish to a public GitHub release:
gh release upload vX.Y.Z dist-release/mrt2d-darwin-arm64.tar.gz --repo <owner>/claude-music