Spotify History & Recommendations

---

name: spotify-history

description: Access Spotify listening history, top artists/tracks, and get personalized recommendations via the Spotify Web API. Use when fetching a user's recent plays, analyzing music taste, or generating recommendations. Requires one-time OAuth setup.

---

# Spotify History & Recommendations

Access Spotify listening history and get personalized recommendations.

Setup (One-Time)

Quick Setup (Recommended)

Run the setup wizard:

bash skills/spotify-history/scripts/setup.sh

This guides you through:

1. Creating a Spotify Developer App

2. Saving credentials securely

3. Authorizing access

Manual Setup

1. **Create Spotify Developer App**

- Go to [developer.spotify.com/dashboard](https://developer.spotify.com/dashboard)

- Click **Create App**

- Fill in:

- **App name:** `Clawd` (or any name)

- **App description:** `Personal assistant integration`

- **Redirect URI:** `http://127.0.0.1:8888/callback` ⚠️ Use exact URL!

- Save and copy **Client ID** and **Client Secret**

2. **Store Credentials**

**Option A: Credentials file (recommended)**

```bash

mkdir -p credentials

cat > credentials/spotify.json <<EOF

{

"client_id": "your_client_id",

"client_secret": "your_client_secret"

}

EOF

chmod 600 credentials/spotify.json

```

**Option B: Environment variables**

```bash

# Add to ~/.zshrc or ~/.bashrc

export SPOTIFY_CLIENT_ID="your_client_id"

export SPOTIFY_CLIENT_SECRET="your_client_secret"

```

3. **Authenticate**

**With browser (local machine):**

```bash

python3 scripts/spotify-auth.py

```

**Headless (no browser):**

```bash

python3 scripts/spotify-auth.py --headless

```

Follow the prompts to authorize via URL and paste the callback.

Tokens are saved to `~/.config/spotify-clawd/token.json` and auto-refresh when expired.

Usage

Command Line

# Recent listening history
python3 scripts/spotify-api.py recent

# Top artists (time_range: short_term, medium_term, long_term)
python3 scripts/spotify-api.py top-artists medium_term

# Top tracks
python3 scripts/spotify-api.py top-tracks medium_term

# Get recommendations based on your top artists
python3 scripts/spotify-api.py recommend

# Raw API call (any endpoint)
python3 scripts/spotify-api.py json /me
python3 scripts/spotify-api.py json /me/player/recently-played

Time Ranges

Example Output

Top Artists (medium_term):
  1. Hans Zimmer [soundtrack, score]
  2. John Williams [soundtrack, score]
  3. Michael Giacchino [soundtrack, score]
  4. Max Richter [ambient, modern classical]
  5. Ludovico Einaudi [italian contemporary classical]

Agent Usage

When user asks about music:

For recommendations, combine API data with music knowledge to suggest similar artists not in their library.

Troubleshooting

"Spotify credentials not found!"

"Not authenticated. Run spotify-auth.py first."

"HTTP Error 400: Bad Request" during token refresh

"HTTP Error 401: Unauthorized"

```bash

rm ~/.config/spotify-clawd/token.json

python3 scripts/spotify-auth.py

```

Headless / No Browser

Security Notes

Required Scopes