Trakt.tv Integration

Track and recommend TV shows and movies using Trakt.tv. Use when the user asks for show/movie recommendations, wants to track what they're watching, check their watchlist, or get personalized suggestions based on their viewing history. Requires Trakt.tv account with Pro subscription for full functionality.

Security Scan

The skill's code, instructions, and credential usage are consistent with a Trakt.tv integration — it asks for a Trakt app Client ID/Secret, stores tokens locally, and calls the Trakt API; no unrelated credentials, hidden endpoints, or obvious misdirection were found.

Purpose & Capability

The name/description match the actual behavior: the skill implements Trakt API calls (recommendations, history, watchlist, search, trending) and requires a Trakt application (client_id/client_secret). It does not request unrelated credentials or external services beyond Trakt.

Instruction Scope

Runtime instructions and INSTALL.md direct the agent/user to create a Trakt app, run the provided setup script, create ~/.openclaw/trakt_config.json, and run the included trakt_client.py CLI. Those steps are within the skill's purpose, but the setup is interactive and executes subprocesses (opening browser, running Python scripts). The instructions do not ask the agent to read unrelated system files or to exfiltrate data.

Install Mechanism

There is no formal install spec (lowest risk), but the bundled scripts can install Python dependencies using pip (with --break-system-packages) and run subprocesses. No external downloads from untrusted URLs or archive extraction were observed. The lack of an install manifest means executing the provided scripts writes files to disk (config file under the user's home).

Credentials

The skill does not request unrelated environment variables or system credentials. It does require the user-supplied Trakt client_id and client_secret and stores access/refresh tokens in plaintext JSON at ~/.openclaw/trakt_config.json — this is functionally necessary but is a sensitive artifact (no keyring use).

Persistence & Privilege

The skill is not marked always:true and does not request elevated or cross-skill configuration changes. It creates and uses a single per-user config file under ~/.openclaw, which is expected for a user-level integration.

Assessment

This skill appears coherent for a Trakt.tv integration, but before installing consider the following: (1) Inspect the included scripts yourself — they run subprocesses and make network calls only to the Trakt API. (2) Run the setup inside a Python virtual environment rather than allowing global pip installs (the script uses --break-system-packages). (3) The Client Secret and access/refresh tokens are stored in plaintext at ~/.openclaw/trakt_config.json — if you prefer stronger protection, store them in a system keyring and modify the code accordingly. (4) Limit the Trakt application permissions when you create the app (grant least privilege) and be prepared to revoke the client secret if anything looks suspicious. (5) Since source provenance is unknown, prefer running the setup manually (not allowing unattended autonomous invocation) and review network activity if you are cautious.

Trakt.tv Integration for OpenClaw

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

📚 Trakt API Documentation: https://trakt.docs.apiary.io/

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

If automated setup doesn't work, follow the manual steps in the Setup section below.

Interactive Setup for OpenClaw

When a user asks to "install Trakt" or "set up Trakt integration," OpenClaw should:

1. Read INSTALL.md for detailed interactive flow
2. Or run python3 scripts/setup.py and guide user through prompts

---

Features

• Track watch history (automatically synced by Trakt from streaming services)
• Get personalized recommendations based on viewing habits
• Access user watchlists and collections
• Search for shows and movies
• View trending content

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
   

   Alternatively, install via Homebrew if available:

   brew install python-requests
   

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

3. Trakt API application - Create at https://trakt.tv/oauth/applications

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

Setup

1. Create Trakt Application

1. Visit https://trakt.tv/oauth/applications
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 <PIN>

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?"

• Get recommendations, filter by mood/genre if specified
• Check trending if user wants something popular

"Add [show] to my watchlist"

• Search for the show
• Add to Trakt watchlist (requires additional endpoint implementation)

"What have I been watching lately?"

• Get watch history
• Summarize recent shows/movies

"Is [show] trending?"

• Get trending list
• Search for specific show

Limitations

• Trakt Pro subscription required for automatic watch tracking from streaming services
• Recommendations improve over time as watch history grows
• API rate limits apply: 1000 requests per 5 minutes (authenticated)
• Full API documentation: https://trakt.docs.apiary.io/

Troubleshooting

"Authentication failed"

• Verify CLIENT_ID and CLIENT_SECRET are set correctly in ~/.openclaw/trakt_config.json
• Ensure PIN is copied accurately (case-sensitive)
• Check that your Trakt application has proper permissions

"No recommendations returned"

• User may not have enough watch history yet
• Try falling back to trending content
• Ensure user has rated some content on Trakt

"API request failed"

• Check authentication token hasn't expired
• Verify network connectivity
• Check Trakt API status: https://status.trakt.tv