Skip to main content
plugin

claude-music — Claude Code plugin: music in your terminal

Background music inside a Claude session: lofi, jazz, classical, ambient. One install command, no account needed.

MIT ★ 26 updated 2026-04-12

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add anthropics/claude-plugins-community
/plugin install claude-music@claude-community
Open on GitHub

What claude-music does

The plugin adds slash commands to Claude that stream internet radio. /play starts lofi, /play jazz picks a genre or a named station, and /next with /prev cycles stations inside the current genre. Volume, mute, shuffle, station listing and a now-playing check are covered by /volume, /mute, /shuffle, /list and /status.

A resident DJ called Ken handles the choosing. /vibe reads the running session and picks a genre on its own, /mood takes a mood in plain words, and /prefs shows what it has learned about your taste. /focus runs a pomodoro timer — 25 minutes unless you pass another length — and fades the music out with a chime at the end.

Audio goes through an external player that the plugin looks for on your machine: mpv, ffplay or the built-in afplay on macOS, mpv or ffplay on Linux, mpv on Windows. If none is present, it offers to set one up. Genre and volume settings are stored locally and survive a session restart.

What it helps with

  • play background music without leaving the terminal
  • switch stations inside a genre with one command
  • match the genre to the task at hand
  • run a pomodoro timer with music and a closing chime
  • silence the stream without stopping it

Example prompts for the agent

  • Play lofi while I debug this
  • Start ambient with a 45 minute timer
  • What's playing right now?

How to install claude-music

Plugin marketplace

/plugin marketplace add anthropics/claude-plugins-community
/plugin install claude-music@claude-community

Step by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own

Questions about claude-music

How do I install claude-music in Claude Code?

Add the marketplace first: /plugin marketplace add anthropics/claude-plugins-community. Then install the plugin: /plugin install claude-music@claude-community. Start a new session and run /play.

What does claude-music do?

It streams internet radio in the terminal during a Claude session. Commands like /play, /next, /volume and /focus control the station, volume and timer, while /vibe picks a genre from the current session.

Do I need an account or a subscription?

No. The stations are free, ad-free and need no sign-up. Playback requires an audio player on your machine — mpv, ffplay or afplay; the plugin offers to install one if it finds none.

Source text

SKILL.md · MIT
<p align="center">
  <img src="assets/logo-2.png" alt="Claude Music" width="450">
</p>

<p align="center">
  <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT">
  <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows%20%7C%20WSL2-blue" alt="Platform">
  <img src="https://img.shields.io/badge/Claude%20Code-plugin-blueviolet" alt="Claude Code">
</p>

<h2 align="center">Music in your Claude Code Sessions</h2>

Enjoy great music and vibes while Claude Code does the heavy lifting. Lofi, jazz, classical, ambient, and more — streaming live from the internet, right in your coding session.

No setup, no sign ups, no accounts. Just install the plugin and start listening.

<p align="center">
  <img src="docs/demo.gif" alt="claude-music demo" width="600">
</p>

## Quick Start

```
/play                # Start playing (lofi genre by default)
/play jazz           # Play a specific genre or station name
/next                # Skip to a different station (same genre)
/prev                # Go back to the previous station
/stop                # Stop the music
/volume up           # Nudge volume up (or down, or set 0-100)
/mute                # Mute without stopping the stream
/shuffle             # Random genre, random station — surprise me
/status              # See what's playing right now
```

Or let the resident AI DJ Ken pick for you:

```
/vibe                            # DJ reads your session and picks automatically
/mood feeling tired, need energy  # Tell the DJ your mood in your own words
```

Or start a focus session with a timer:

```
/focus              # 25 min pomodoro — music fades out and chimes when done
/focus 45 ambient   # 45 min with ambient music
```

See the [full command list](#all-commands) for more.

## Installation

### Claude Code (via Plugin Marketplace)

Register the marketplace first:

```bash
/plugin marketplace add kennethleungty/claude-music-marketplace
```

Then install the plugin:

```bash
/plugin install claude-music@claude-music-marketplace
```

### Verify Installation

Start a new session and try `/play` or `/vibe`.

> Don't have an audio player installed? No worries — the plugin detects this and walks you through installing one automatically.

## AI DJ

The plugin includes a resident AI DJ (DJ Ken) that picks the right music for you. Debugging? He switches to lofi. Deep in a code review? Classical kicks in. He learns your preferences over time — the more you use it, the better he gets.

- **`/vibe`** — DJ Ken reads your current session and picks automatically. No input needed.
- **`/mood <feeling>`** — Tell him what you want in your own words: "calm me down", "something retro and fun".
- **`/prefs`** — See what he's learned about your taste over time.

## Genres

| Genre | Vibe | Great for | Stations |
|-------|------|-----------|----------|
| **lofi** | Chill downtempo beats, mellow vibes | Focused coding, debugging, writing tests | 3 |
| **jazz** | Smooth jazz, bossa nova, instrumental | Building features, refactoring | 4 |
| **classical** | Orchestral, chamber music, deep focus | Code review, reading, research | 3 |
| **ambient** | Atmospheric drones, space music | Brainstorming, design, creative work | 6 |
| **electronic** | Electronic, trance, IDM, dubstep, trip-hop | Shipping sprints, high-energy sessions | 6 |
| **synthwave** | Retro-futuristic, 80s-inspired | Late night coding, nostalgic vibes | 3 |
| **lounge** | Cinematic, spy-movie elegance | Demos, presentations, smooth backdrop | 2 |
| **indie** | Indie pop, folk, dream pop | Creative writing, docs, warm sessions | 4 |

Each genre has multiple stations. Use `/next` to cycle through them.

## Works Everywhere

| Platform | How it plays |
|----------|-------------|
| **macOS** | mpv or ffplay (via Homebrew) or built-in afplay |
| **Linux** | mpv or ffplay (via apt, dnf, pacman, etc.) |
| **WSL2** | mpv/ffplay inside WSL (with WSLg audio) or Windows-side mpv.exe |
| **Windows** | mpv (via winget, scoop, or chocolatey) |

The plugin auto-detects your platform and available audio players. If nothing is installed, it offers to set one up for you.

### All Commands

| Command | What it does |
|---------|-------------|
| `/play [genre or station]` | Start playing by genre or station name |
| `/stop` | Stop the music and show session stats |
| `/next` | Switch to a different station (same genre) |
| `/prev` | Go back to the previous station |
| `/pause` | Stop the music (alias for `/stop`) |
| `/mute` | Silence the music without stopping the stream (volume 0) |
| `/vibe` | AI DJ reads your session and picks the best genre |
| `/dj` | Same as `/vibe` |
| `/mood <feeling>` | Tell the DJ how you're feeling and it picks the right music |
| `/focus [min] [genre]` | Pomodoro timer with music (default 25 min) |
| `/pomodoro` | Same as `/focus` |
| `/shuffle` | Pick a completely random genre and station |
| `/volume [0-100 \| up \| down]` | Set volume, nudge up/down by 10, or show current |
| `/status` | See what's playing right now |
| `/list` | List available genres and their stations |
| `/stats` | See current session and lifetime listening stats |
| `/prefs` | See your saved preferences and favorite stations |
| `/reset` | Clear all preferences back to defaults |
| `/sources` | View, add, edit, or remove streams |
| `/feedback` | Report a bug or share feedback on GitHub |
| `/help` | Show help |

<details>
<summary><strong>Focus Timer</strong></summary>

Start a pomodoro session with background music. When the timer ends, the music fades out and a chime plays.

```
/focus              # 25 min, current genre
/focus 45 ambient   # 45 min of ambient
```

</details>

<details>
<summary><strong>Now Playing & Preferences</strong></summary>

The status line at the bottom of your terminal shows what's currently playing — genre, station name, track title, and pomodoro countdown when active. Always visible, never scrolls away.

Your settings are saved automatically and persist locally across sessions:

- **Genre** — your preferred default (lofi by default when fresh start)
- **Volume** — 0 to 100 (changed via `/volume`)

</details>

<details>
<summary><strong>Radio Stations</strong></summary>

All streams are free, ad-free, and require no account. The station library is a mix of curated SomaFM radio streams and 24/7 YouTube livestreams.

- **Lofi** — Lofi Girl, Chillhop Music, Groove Salad
- **Jazz** — Coffee Shop Radio, SomaFM Fluid, Bossa Beyond, WDCB Jazz
- **Classical** — Classical Piano & Fireplace, All Classical Portland, France Musique
- **Ambient** — Relaxing Ambient, SomaFM Drone Zone, Deep Space One, Mission Control, Dark Zone, Stereoscenic Ambient
- **Electronic** — Beat Blender, The Trip, Cliqhop IDM, Dub Step Beyond, Suburbs of Goa, Groove Salad Classic
- **Synthwave** — Synthwave Radio, Nightwave Plaza, SomaFM Synphaera
- **Lounge** — SomaFM Secret Agent, Illinois Street Lounge
- **Indie** — SomaFM Lush, Indie Pop Rocks, Folk Forward, BAGeL Radio

Want to add your own stations? Use `/sources` to manage streams interactively.

</details>

## Contributing

Know a great stream that belongs here? We'd love your help growing the station library. Musicians, DJs, radio nerds, and anyone with good taste — open an issue or PR with your recommendation. Include the stream URL, a short description, and which genre it fits best.

All streams should be free, ad-free, and publicly accessible.

## For Music Producers & Composers

Make music that's perfect for coding? We're always looking for new streams to feature.

This plugin plays background music during Claude Code sessions. If you produce lofi, ambient, jazz, electronic, or anything that pairs well with deep focus, your music could reach developers while they're actually in flow.

**To get featured**, [open an issue](../../issues/new) with:

- A link to your stream (YouTube livestream, Icecast/Shoutcast URL, etc.)
- A short description of your sound
- Which genre category fits best (or suggest a new one)

We'll listen, and if it's a good fit, add it to the station library for everyone.

## Coming Soon

**Spotify Integration** — Connect your Spotify account and play your own playlists directly through the plugin.

© kennethleungty · MIT · kennethleungty/claude-music

Similar plugins

All plugins for Agent setup: memory, context, orchestration →

Project sponsors

Companies that keep this analytics open