Trakt.tv Integration

Trakt.tv Integration for OpenClaw

Integrate with Trakt.tv to track watch history and provide personalized show/movie recommendations.

📚 Trakt API Documentation:

First-Time Setup Required

Before using this skill, run the interactive setup:

Automated Setup (Recommended)

python3 scripts/setup.py

This will guide you through: 1. Installing dependencies 2. Creating a Trakt application 3. Configuring credentials 4. Authenticating with PIN 5. Testing the integration

Manual Setup

Interactive Setup for OpenClaw

Features

Prerequisites

1. Python dependencies:

   # Install via pip (with --break-system-packages if needed)
   pip3 install requests
   
   # OR use a virtual environment (recommended)
   python3 -m venv ~/.openclaw-venv
   source ~/.openclaw-venv/bin/activate
   pip install requests
   

   brew install python-requests
   

2. Trakt.tv account with Pro subscription (required for automatic watch tracking)

3. Trakt API application - Create at

4. Configuration file: ~/.openclaw/trakt_config.json (see setup below)

Setup

1. Create Trakt Application

1. Visit 2. Click "New Application" 3. Fill in the form: - Name: "OpenClaw Assistant" - Description: "Personal AI assistant integration" - Redirect URI: urn:ietf:wg:oauth:2.0:oob (for PIN auth) - Permissions: Check all that apply 4. Save and note your Client ID and Client Secret

2. Create Configuration File

Create ~/.openclaw/trakt_config.json with your credentials:

{
  "client_id": "YOUR_CLIENT_ID_HERE",
  "client_secret": "YOUR_CLIENT_SECRET_HERE",
  "access_token": "",
  "refresh_token": ""
}

Replace YOUR_CLIENT_ID_HERE and YOUR_CLIENT_SECRET_HERE with your actual values from step 1.

Note: Leave access_token and refresh_token empty - they'll be filled automatically after authentication.

3. Authenticate

Run the authentication script:

python3 scripts/trakt_client.py auth

This will output a PIN URL. Visit it, authorize the app, and run:

python3 scripts/trakt_client.py auth 

Authentication tokens are saved to ~/.openclaw/trakt_config.json

Usage

Get Recommendations

When a user asks for show/movie recommendations:

python3 scripts/trakt_client.py recommend

This returns personalized recommendations based on the user's watch history and ratings.

Check Watch History

python3 scripts/trakt_client.py history

Returns the user's recent watch history.

View Watchlist

python3 scripts/trakt_client.py watchlist

Shows content the user has saved to watch later.

Search

python3 scripts/trakt_client.py search "Breaking Bad"

Search for specific shows or movies.

Trending Content

python3 scripts/trakt_client.py trending

Get currently trending shows and movies.

Recommendation Workflow

When a user asks "What should I watch?" or similar:

1. Get personalized recommendations:

   python3 scripts/trakt_client.py recommend
   

2. Parse the results and present them naturally: - Show title, year, rating - Brief description/genre - Why it's recommended (if available)

3. Optionally check watchlist to avoid suggesting shows they already plan to watch

4. Consider recent history to avoid re-suggesting recently watched content

API Reference

See references/api.md for detailed Trakt API endpoint documentation.

Common Use Cases

"What should I watch tonight?"

"Add [show] to my watchlist"

"What have I been watching lately?"

"Is [show] trending?"

Limitations

Troubleshooting

"Authentication failed"

"No recommendations returned"

"API request failed"

Get Recommendations

When a user asks for show/movie recommendations:

python3 scripts/trakt_client.py recommend

This returns personalized recommendations based on the user's watch history and ratings.

Check Watch History

python3 scripts/trakt_client.py history

Returns the user's recent watch history.

View Watchlist

python3 scripts/trakt_client.py watchlist

Shows content the user has saved to watch later.

Search

python3 scripts/trakt_client.py search "Breaking Bad"

Search for specific shows or movies.

Trending Content

python3 scripts/trakt_client.py trending

Get currently trending shows and movies.

1. Create Trakt Application

1. Visit 2. Click "New Application" 3. Fill in the form: - Name: "OpenClaw Assistant" - Description: "Personal AI assistant integration" - Redirect URI: urn:ietf:wg:oauth:2.0:oob (for PIN auth) - Permissions: Check all that apply 4. Save and note your Client ID and Client Secret

2. Create Configuration File

Create ~/.openclaw/trakt_config.json with your credentials:

{
  "client_id": "YOUR_CLIENT_ID_HERE",
  "client_secret": "YOUR_CLIENT_SECRET_HERE",
  "access_token": "",
  "refresh_token": ""
}

Replace YOUR_CLIENT_ID_HERE and YOUR_CLIENT_SECRET_HERE with your actual values from step 1.

Note: Leave access_token and refresh_token empty - they'll be filled automatically after authentication.

3. Authenticate

Run the authentication script:

python3 scripts/trakt_client.py auth

This will output a PIN URL. Visit it, authorize the app, and run:

python3 scripts/trakt_client.py auth 

Authentication tokens are saved to ~/.openclaw/trakt_config.json

"Authentication failed"

"No recommendations returned"

"API request failed"