spotify

The spotify mod puts Spotify’s playback controls above the Claude Code prompt, so you can skip a song without leaving the terminal. The buttons drive the Spotify desktop app on your Mac directly and need no login. A sidebar adds search, your playlists and Liked Songs through Spotify’s Web API, once you connect a Spotify app of your own.

What it does

• The band. /spotify opens three rows above the prompt: icon buttons for previous, play or pause, next and mute, the track, artist and album, and a progress bar that moves once a second. ⌄ folds it into one line. Unmute restores the volume you muted from. If Spotify is closed, an open Spotify button replaces the controls. The band sits beside other mods above the prompt instead of hiding them.
• The sidebar. ◫ opens a pane with what is playing, a search box and your playlists, Liked Songs first. A playlist plays track by track, in order or shuffled. In search results a song plays on press, while an album, an artist or a playlist of yours opens to its contents. Esc closes the pane.
• Album covers appear beside the band and at the top of the sidebar in terminals with kitty graphics, such as Ghostty and kitty. Elsewhere you get the text alone.
• Commands. /spotify stop closes the band. /spotify config <client-id> saves your Spotify Client ID, and /spotify config alone shows it. /spotify logout drops the sidebar’s login.

If you listen in Apple Music instead, player is a similar remote above the prompt, also macOS only.

Install

Needs Claude Code 2.1.287 or later, macOS and the Spotify desktop app, not the web player. Search and playlists also need Spotify Premium and a Spotify app of your own, set up below.

claude plugin marketplace add ambareeshav/claude-spotify-mod
claude plugin install spotify@spotify

It installs as spotify. Run /spotify and the controls appear above the prompt. The first button you press may make macOS ask whether your terminal can control Spotify: allow it once.

The README offers a second route, through the author’s plugin marketplace: claude plugin marketplace add ambareeshav/claude-plugins, then claude plugin install spotify@ambareeshav. Use one or the other.

To turn on the sidebar’s search and playlists:

1. Create an app in the Spotify developer dashboard, set its Redirect URI to exactly http://127.0.0.1:8907/callback and tick Web API. Spotify requires Premium to create one.
2. Copy the app’s Client ID and run /spotify config <client-id>. It persists across sessions. A clientId in the plugin’s settings, if you set one, wins over it.
3. Open the sidebar with ◫, press “connect Spotify” and approve in the browser. The sidebar connects by itself within a couple of seconds.

Spotify limits an app in Development Mode to its owner and five added users, which is why the mod cannot ship a shared one. As the owner, you need nothing under User Management. If the sidebar does not connect (no python3, or port 8907 is taken), the browser shows a “can’t reach this page” error with the code in the address bar: paste that URL into the sidebar’s input and press Enter.

How it works

The band runs AppleScript through osascript against the Spotify app, once a second while it is open, driven by a zero-size Client. It checks with System Events that Spotify is running before querying it, so it never launches Spotify just to look; the transport buttons do launch it. For the cover, it asks Spotify for the artwork URL, downloads the image with curl, converts it to PNG with sips and keeps one file per session in /tmp. That download happens whether or not you connected the sidebar.

The sidebar calls Spotify’s Web API at api.spotify.com for your profile, playlists, Liked Songs, search, album and artist listings, and playback. It logs in with OAuth’s Authorization Code flow with PKCE, so there is no client secret, and asks for six scopes: user-read-playback-state, user-modify-playback-state and user-read-currently-playing for playback, playlist-read-private and playlist-read-collaborative for playlists, and user-library-read for Liked Songs. None of them can edit your playlists or library.

Pressing “connect Spotify” writes a small Python server to /tmp, stops any earlier copy with pkill, starts it with python3 in the background on 127.0.0.1:8907 for up to three minutes, and opens Spotify’s login page in your browser. The server saves the redirect’s code to a JSON file in /tmp. The mod picks it up within a second, deletes the file and the script, checks the state value and exchanges the code for tokens at accounts.spotify.com.

The access and refresh tokens and your Client ID are kept in Claude Code’s plugin store on your machine. The access token renews itself when it expires. /spotify logout deletes the stored tokens but does not revoke the app’s access in your Spotify account; changing the Client ID logs you out too. The mod registers only /spotify and reads no prompts, tool calls or project files.

Limitations

• Terminal only. The band draws only when Claude Code reports the terminal surface, so the Desktop app’s Code tab shows nothing, and the sidebar opens from the band.
• Your own playlists. The sidebar lists Liked Songs and the playlists you created. Since a February 2026 change, Spotify does not let third-party apps read the tracks of followed, collaborative or algorithmic playlists such as Discover Weekly, so the mod leaves them out. You can still find and play them through search.
• Ten results per type in search, Spotify’s current cap.
• An active Spotify Connect device is needed to start playback from the sidebar. If there is none, press play in Spotify once and retry.
• Liked Songs plays at most 500 tracks at a time, in order or shuffled.