Spotify Control — AI Plays Music

It’s like handing your DJ a remote control, except the DJ is your AI assistant and the remote works across every speaker in your house.

Why This Matters

You’re typing away, deep in flow, and suddenly you need a song change. Instead of unlocking your phone, opening Spotify, and breaking your concentration, you just ask Hermes. It pauses, skips, queues, or searches—all through the official Spotify API. No hacks, no screen scraping, just clean, legal control.

The One-Time Setup (About 5 Minutes)

Hermes controls Spotify through the official spotify plugin from the plugin catalog. It uses Spotify’s Web API with PKCE OAuth. The plugin is maintained by Nous Research in NousResearch/hermes-official-plugins and is not part of Hermes core. Tokens are stored in ~/.hermes/auth.json and refresh automatically on 401. You only log in once per machine—refresh tokens expire after about six months, and you re-run hermes spotify login when they do.

The catch? Spotify requires every user to create their own tiny developer app. Spotify doesn’t let third parties ship a public OAuth app that anyone can use. It’s free, takes two minutes, and hermes spotify login walks you through it step by step.

Prerequisites

• A Spotify account. Free works for search, playlist, library, and activity tools. Premium is required for playback control (play, pause, skip, seek, volume, queue add, transfer).
• Hermes Agent installed and running, with the spotify plugin installed.
• For playback tools: an active Spotify Connect device — the Spotify app must be open on at least one device (phone, desktop, web player, speaker) so the Web API has something to control. If nothing is active you’ll get a 403 Forbidden with a “no active device” message; open Spotify on any device and retry.

Install the Plugin

Plugins are installed per profile. Run:

hermes plugins install spotify

To use Spotify in another profile, install it there too (hermes -p <profile> plugins install spotify).

Upgrading from a release that bundled Spotify? Nothing to do. Every profile already using Spotify (a Spotify login in its auth.json, or the spotify toolset listed in platform_toolsets) gets the plugin installed automatically from the catalog by hermes update, or the first time the profile starts if that step could not run (this honours security.allow_lazy_installs). Your login, the spotify toolset and the tool names carry over unchanged. The one visible change: hermes auth spotify is now hermes spotify login (and hermes auth status spotify / hermes auth logout spotify are hermes spotify status / hermes spotify logout); the old spelling prints the new one. If you later remove the plugin (hermes plugins remove spotify), it stays removed.

1. Enable the toolset

The plugin’s spotify toolset is opt-in, so users who don’t want it don’t ship extra tool schemas on every API call. Turn it on in hermes tools (toggle 🔌 Spotify, then save) or with:

hermes tools enable spotify

2. Log in

hermes spotify login

If no HERMES_SPOTIFY_CLIENT_ID is set, Hermes opens the developer dashboard in your browser, prints the exact values to paste into Spotify’s “Create app” form, prompts you for the Client ID, saves it to ~/.hermes/.env, and continues straight into the OAuth consent flow. Once you approve, tokens are written under providers.spotify in ~/.hermes/auth.json. The 7 Spotify tools only reach the agent once you’re logged in.

Prefer Step-by-Step? No Problem

You can also do it in two passes. Enable the toolset first:

hermes tools

Toggle 🔌 Spotify on, save, and when the wizard opens, press Ctrl+C to dismiss it. The toolset stays on; only auth is deferred.

Then, run the login wizard separately:

hermes spotify login

Hermes will ask for your Client ID if it’s not already saved. After you paste it, the browser opens for Spotify login. Approve, and you’re authenticated.

What You Need to Know

• Free Spotify account? You get search, playlists, saved tracks, and listening history.
• Premium account? You also get playback control—play, pause, skip, seek, volume, queue, and transfer.
• Active device required: For playback tools, Spotify must be open on at least one device (phone, desktop, web, speaker). If not, you’ll see a 403 Forbidden error. Just open Spotify anywhere and retry.

The 7 Tools Appear Only After You Enable Them

Hermes keeps things lean. The Spotify tools are off by default, so users who don’t want them don’t ship extra tool schemas on every API call. Once you toggle the toolset on and log in, all 7 tools appear in your agent’s toolbox.

Checking Status and Logging Out

hermes spotify status

Shows whether tokens are present and when the access token expires. Refresh is automatic: when any Spotify API call returns 401, the client exchanges the refresh token and retries once. Refresh tokens persist across Hermes restarts, so you only re-auth if you revoke the app in your Spotify account settings or run hermes spotify logout.

If 401 Unauthorized keeps coming back, your refresh token was revoked (usually because you removed the app from your account, or the app was deleted). Run hermes spotify login again.

Final Tip

Save your Client ID somewhere safe. It’s stored in ~/.hermes/.env, so you won’t need it again on this machine. But if you switch computers, you’ll be glad you kept it.

Summary: Install the plugin, enable the toolset, run the login wizard, and let Hermes handle the music. It’s one small setup for you, one giant leap for your productivity.

Practical tip: Start with search and playlist tools first—they work on free accounts and don’t require an active device. Once you’re comfortable, upgrade to playback and enjoy hands-free control.