---

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
   • 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)

   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

   # 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):

   python3 scripts/spotify-auth.py
   

   Headless (no browser):

   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

• short_term — approximately last 4 weeks
• medium_term — approximately last 6 months (default)
• long_term — all time

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:

• "What have I been listening to?" → spotify-api.py recent
• "Who are my top artists?" → spotify-api.py top-artists
• "Recommend new music" → spotify-api.py recommend + add your own knowledge

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

Troubleshooting

"Spotify credentials not found!"

• Make sure credentials/spotify.json exists or environment variables are set
• Credential file is checked first, then env vars
• Run bash skills/spotify-history/scripts/setup.sh to create credentials

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

• Tokens don't exist or are invalid
• Run: python3 scripts/spotify-auth.py (or with --headless if no browser)

"HTTP Error 400: Bad Request" during token refresh

• Credentials changed or are invalid
• Re-run setup: bash skills/spotify-history/scripts/setup.sh
• Or update credentials/spotify.json with correct Client ID/Secret

"HTTP Error 401: Unauthorized"

• Token expired and auto-refresh failed
• Delete token and re-authenticate:

  rm ~/.config/spotify-clawd/token.json
  python3 scripts/spotify-auth.py
  

Headless / No Browser

• Use --headless flag: python3 scripts/spotify-auth.py --headless
• Manually open the auth URL on any device
• Copy the callback URL (starts with http://127.0.0.1:8888/callback?code=...)
• Paste it back when prompted

Security Notes

• Tokens stored with 0600 permissions (user-only read/write)
• Client secret should be kept private
• Redirect URI uses 127.0.0.1 (local only) for security

Required Scopes

• user-read-recently-played — recent listening history
• user-top-read — top artists and tracks
• user-read-playback-state — current playback
• user-read-currently-playing — currently playing track