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:

Creating a Spotify Developer App

Saving credentials securely

Authorizing access

Manual Setup

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: ⚠️ Use exact URL! - Save and copy **Client ID** and **Client Secret** 2. **Store Credentials** **Option A: Credentials file (recommended)** __CODE_BLOCK_1__ **Option B: Environment variables** __CODE_BLOCK_2__ 3. **Authenticate** **With browser (local machine):** __CODE_BLOCK_3__ **Headless (no browser):** __CODE_BLOCK_4__ 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 __CODE_BLOCK_5__ ### Time Ranges - short_term — approximately last 4 weeks - medium_term — approximately last 6 months (default) - long_term — all time ### Example Output __CODE_BLOCK_6__ ## 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: __CODE_BLOCK_7__ ### 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 )

• 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