{
  "schemaVersion": "1.0",
  "item": {
    "slug": "clawtv",
    "name": "ClawTV",
    "source": "tencent",
    "type": "skill",
    "category": "AI 智能",
    "sourceUrl": "https://clawhub.ai/akivasolutions/clawtv",
    "canonicalUrl": "https://clawhub.ai/akivasolutions/clawtv",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/clawtv",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=clawtv",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "CONTRIBUTING.md",
      "README.md",
      "clawtv.py",
      "requirements.txt",
      "skill.md"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-23T16:43:11.935Z",
      "expiresAt": "2026-04-30T16:43:11.935Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=4claw-imageboard",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=4claw-imageboard",
        "contentDisposition": "attachment; filename=\"4claw-imageboard-1.0.1.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/clawtv"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/clawtv",
    "agentPageUrl": "https://openagent3.xyz/skills/clawtv/agent",
    "manifestUrl": "https://openagent3.xyz/skills/clawtv/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/clawtv/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "ClawTV",
        "body": "AI-powered Apple TV remote that can see the screen and navigate any app autonomously using vision + remote control."
      },
      {
        "title": "When to use (trigger phrases)",
        "body": "Use this skill immediately when the user asks:\n\n\"play [movie/show] on Apple TV\"\n\"search for [content] on [Netflix/Plex/YouTube/etc]\"\n\"open [app] on the TV\"\n\"turn on subtitles\" / \"go to TV settings\"\n\"what's playing on Apple TV?\"\n\"take a screenshot of the TV\"\nAny Apple TV navigation or control task"
      },
      {
        "title": "Quick start",
        "body": "# AI agent mode — tell it what you want in plain English\npython3 ~/Developer/clawtv/clawtv.py do \"open Plex and play Fight Club\"\npython3 ~/Developer/clawtv/clawtv.py do \"search for Stranger Things on Netflix\"\npython3 ~/Developer/clawtv/clawtv.py do \"go to settings and turn on subtitles\"\n\n# Direct Plex control (instant, no vision loop)\npython3 ~/Developer/clawtv/clawtv.py plex play \"Fight Club\"\npython3 ~/Developer/clawtv/clawtv.py plex play \"Westworld\" -s 2 -e 6\n\n# Manual remote commands\npython3 ~/Developer/clawtv/clawtv.py cmd up down select\npython3 ~/Developer/clawtv/clawtv.py type \"breaking bad\"\npython3 ~/Developer/clawtv/clawtv.py launch com.plexapp.plex\n\n# Screenshot\npython3 ~/Developer/clawtv/clawtv.py screenshot\n\n# Status\npython3 ~/Developer/clawtv/clawtv.py playing"
      },
      {
        "title": "ANTHROPIC_API_KEY (Required for AI/Vision Mode)",
        "body": "The do command (AI agent mode) requires an Anthropic API key to access Claude's vision API for screenshot analysis and navigation decisions.\n\nexport ANTHROPIC_API_KEY=sk-ant-...\n\nOr add to your shell profile (~/.zshrc, ~/.bashrc).\n\nNote: This is only required for the do command. Manual commands (cmd, type, launch) and plex direct control do not use the API."
      },
      {
        "title": "Plex Credentials (Optional)",
        "body": "For instant Plex playback without the vision loop, add these to ~/.clawtv/config.json:\n\n{\n  \"plex_url\": \"http://192.168.1.100:32400\",\n  \"plex_token\": \"your-plex-token\",\n  \"plex_client\": \"Living Room\"\n}\n\nplex_url: Your Plex server address (local or remote)\nplex_token: Authentication token from your Plex account\nplex_client: Name of the Plex client on your Apple TV\n\nGet your Plex token: https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-token/"
      },
      {
        "title": "What Data is Collected and Sent",
        "body": "Screenshots:\n\nClawTV captures screenshots of your Apple TV screen using QuickTime Player or Xcode\nScreenshots are saved locally to ~/.clawtv/screenshots/ with timestamps\nWhen using the do command (AI agent mode), screenshots are sent to Anthropic's Claude API for vision analysis\nScreenshots may contain sensitive on-screen content including:\n\nContent you're watching (movie/show titles, thumbnails)\nSearch queries\nAccount information visible in app UIs\nAny other content displayed on your TV screen\n\nAnthropic API:\n\nOnly the do command sends data to Anthropic\nData sent: screenshots (JPEG compressed) + your goal/instruction + conversation history\nAnthropic's data retention policy: https://support.anthropic.com/en/articles/7996885-how-long-do-you-store-personal-data\nManual commands (cmd, type, launch) and Plex direct control do NOT send any data to external APIs"
      },
      {
        "title": "Credential Storage",
        "body": "Apple TV Pairing Credentials:\n\nStored unencrypted in ~/.clawtv/config.json in your home directory\nContains device identifiers and pairing tokens for remote control\nFile permissions: readable only by your user account (standard Unix permissions)\n\nPlex Tokens (if configured):\n\nStored unencrypted in the same ~/.clawtv/config.json file\nGrants full access to your Plex server and library\nCan be used to play, pause, search, and control any Plex client\n\nAnthropic API Key:\n\nStored in environment variables or your shell profile\nGrants access to your Anthropic account and incurs API usage charges"
      },
      {
        "title": "Recommendations",
        "body": "Use a budget-limited API key: Set spending limits on your Anthropic account to prevent unexpected charges\nReview config file permissions: Ensure ~/.clawtv/config.json is only readable by your user\nBe aware of screenshot content: Screenshots are sent to Anthropic's API and may contain sensitive information\nMonitor API usage: The do command can make multiple API calls per task (5-20 steps typical)\nUse manual commands when possible: cmd, type, and launch have zero API cost and send no data externally"
      },
      {
        "title": "Plaintext Credential Storage",
        "body": "Apple TV pairing credentials and Plex tokens are stored in plaintext in ~/.clawtv/config.json\nThe file is in your user home directory (~/.clawtv/) with standard Unix file permissions\nAny process running as your user can read these credentials\nIf your Mac is compromised, these credentials are accessible\nConsider this when deciding whether to configure Plex integration"
      },
      {
        "title": "Screenshot Privacy",
        "body": "Screenshots may contain sensitive content visible on your TV screen\nScreenshots are saved locally to ~/.clawtv/screenshots/ and persist until manually deleted\nWhen using AI agent mode (do), screenshots are transmitted to Anthropic's servers\nDRM content (Netflix, Disney+, etc.) cannot be captured via QuickTime, but works with Xcode method\nReview screenshot history periodically and delete sensitive captures"
      },
      {
        "title": "API Cost and Autonomous Behavior",
        "body": "The do command runs in a loop (up to 20 steps) and makes Claude API calls automatically\nEach step = 1 API call with screenshot (~$0.01-0.02 per step depending on model)\nA stuck or confused agent could consume all 20 steps before giving up\nCost implications: Complex tasks can cost $0.10-0.20; monitor your Anthropic usage dashboard\nRecommendation: Set spending limits on your Anthropic account"
      },
      {
        "title": "Manual Commands are API-Free",
        "body": "cmd, type, launch, and plex commands do not use the Claude API\nNo screenshots are sent externally when using these commands\nZero cost, zero external data transmission\nUse these for privacy-sensitive operations"
      },
      {
        "title": "Network Exposure",
        "body": "ClawTV communicates with your Apple TV over your local network using the Companion protocol\nPlex integration (if configured) communicates with your Plex server (local or remote)\nNo external network access except:\n\nAnthropic API (when using do command)\nPlex server (if remote URL configured)"
      },
      {
        "title": "1. Install dependencies",
        "body": "cd ~/Developer/clawtv\npip install -r requirements.txt\n\nFor QuickTime screenshot method (recommended):\n\npip install pyobjc-framework-Quartz"
      },
      {
        "title": "2. Pair with Apple TV (remote control)",
        "body": "python3 ~/Developer/clawtv/clawtv.py scan    # Find your Apple TV on network\npython3 ~/Developer/clawtv/clawtv.py pair    # Enter 4-digit PIN shown on TV\n\nPairing credentials are saved to ~/.clawtv/config.json."
      },
      {
        "title": "3. Set up screenshots",
        "body": "QuickTime (recommended):\n\npython3 ~/Developer/clawtv/clawtv.py screenshot --method quicktime\n\nQuickTime Player opens and selects your Apple TV as video source\nAccept the AirPlay pairing on your TV (one-time PIN)\nSubsequent runs reuse the existing mirror instantly (~0.6s per screenshot)\n\nXcode (fallback for DRM apps):\n\nOn Apple TV: Settings > Privacy & Security → enable \"Share with App Devs\"\nThen Settings > Remotes and Devices > Remote App and Devices\nOn Mac: Open Xcode, press Cmd+Shift+2 (Devices)\nClick your Apple TV in sidebar, enter pairing code\nKeep Xcode Devices window open while using ClawTV"
      },
      {
        "title": "4. Set API key",
        "body": "export ANTHROPIC_API_KEY=sk-ant-...\n\nOr add to your shell profile (~/.zshrc, ~/.bashrc)."
      },
      {
        "title": "5. Optional: Plex direct control setup",
        "body": "For instant Plex playback without vision loop, add to ~/.clawtv/config.json:\n\n{\n  \"plex_url\": \"http://192.168.1.100:32400\",\n  \"plex_token\": \"your-plex-token\",\n  \"plex_client\": \"Living Room\"\n}\n\nGet your Plex token: https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-token/"
      },
      {
        "title": "AI Agent Mode (do)",
        "body": "Tell ClawTV what you want and it figures out the rest using vision + reasoning.\n\npython3 ~/Developer/clawtv/clawtv.py do \"<goal>\"\n\nHow it works:\n\nTakes screenshot of Apple TV\nSends to Claude vision API to analyze UI\nDecides what to do (navigate, select, type, launch app)\nSends remote commands\nTakes another screenshot to verify\nRepeats until goal is accomplished (max 20 steps)\n\nExamples:\n\npython3 ~/Developer/clawtv/clawtv.py do \"open Plex and play Fight Club\"\npython3 ~/Developer/clawtv/clawtv.py do \"search for Stranger Things on Netflix\"\npython3 ~/Developer/clawtv/clawtv.py do \"open YouTube and find lo-fi beats\"\npython3 ~/Developer/clawtv/clawtv.py do \"go to settings and turn on subtitles\"\npython3 ~/Developer/clawtv/clawtv.py do \"open Spotify and play my liked songs\"\n\nToken optimizations (automatic):\n\nPlex goals bypass vision entirely via direct API (instant, pennies)\nSliding window: only last 2 screenshots kept in context (~70% token reduction)\nImages compressed to JPEG 800px q50 (~40% fewer image tokens)\nSystem prompt cached via cache_control (90% savings on steps 2+)\nHaiku 4.5 for routine steps, auto-escalates to Sonnet 4.5 when stuck\n\nPlayback pattern: Navigate → start playback → verify playing → skip intro if visible → disconnect → report done"
      },
      {
        "title": "Remote Commands (cmd)",
        "body": "Send direct remote control commands without AI.\n\npython3 ~/Developer/clawtv/clawtv.py cmd <commands...>\n\nAvailable commands:\nup, down, left, right, select, menu, home, play, pause, play_pause, next, previous, volume_up, volume_down, top_menu\n\nExamples:\n\npython3 ~/Developer/clawtv/clawtv.py cmd up\npython3 ~/Developer/clawtv/clawtv.py cmd down down right select\npython3 ~/Developer/clawtv/clawtv.py cmd select sleep:1.5 down    # with timing\n\nTiming: Insert sleep:X between commands to add delays (in seconds)."
      },
      {
        "title": "Type Text (type)",
        "body": "Type text into a focused search/text field on the TV.\n\npython3 ~/Developer/clawtv/clawtv.py type \"<text>\"\n\nExample:\n\npython3 ~/Developer/clawtv/clawtv.py type \"breaking bad\"\n\nNote: The text field must already be focused. Use cmd to navigate to search first, or use do for full automation."
      },
      {
        "title": "Launch App (launch)",
        "body": "Launch an app by bundle ID.\n\npython3 ~/Developer/clawtv/clawtv.py launch <bundle_id>\n\nExample:\n\npython3 ~/Developer/clawtv/clawtv.py launch com.plexapp.plex\n\nCommon bundle IDs:\n\nAppBundle IDPlexcom.plexapp.plexYouTubecom.google.ios.youtubeHBO Maxcom.wbd.streamPrime Videocom.amazon.aiv.AIVAppApple TVcom.apple.TVWatchListSpotifycom.spotify.clientESPNcom.espn.ScoreCenterTwitchtv.twitchPluto TVtv.pluto.iosNFLcom.nfl.gamecenterDisney+com.disney.disneyplusHulucom.hulu.plusNetflixcom.netflix.Netflix\n\nUse python3 ~/Developer/clawtv/clawtv.py apps for the full list on your device."
      },
      {
        "title": "Plex Direct Control (plex)",
        "body": "Bypass the entire vision loop using Plex API directly. Searches your library and tells the Plex client on Apple TV to play. Instant playback, zero vision cost.\n\n# Play a movie\npython3 ~/Developer/clawtv/clawtv.py plex play \"Fight Club\"\n\n# Play a specific episode\npython3 ~/Developer/clawtv/clawtv.py plex play \"Westworld\" -s 2 -e 6\n\n# Search your library\npython3 ~/Developer/clawtv/clawtv.py plex search \"matrix\"\n\n# List Plex clients\npython3 ~/Developer/clawtv/clawtv.py plex clients\n\n# List libraries\npython3 ~/Developer/clawtv/clawtv.py plex libraries\n\nRequirements:\n\nplex_url, plex_token, and plex_client in ~/.clawtv/config.json\nPlex server running and accessible from Mac\nPlex client running on Apple TV\n\nAuto-detection: The do command automatically detects Plex goals (e.g., \"play Fight Club on Plex\") and routes through this path without any vision API calls."
      },
      {
        "title": "Screenshot (screenshot)",
        "body": "Take a screenshot of the Apple TV and save to ~/.clawtv/screenshots/.\n\npython3 ~/Developer/clawtv/clawtv.py screenshot [--method auto|quicktime|lookout|xcode]\n\nScreenshot methods:\n\nMethodSpeedDRM AppsRequiresQuickTime (default)~0.6s❌ Kills mirror (DRM)QuickTime Player, pyobjc-framework-QuartzLookout~0.1s❌ Only captures Lookout appLookout tvOS app running on Apple TVXcode (legacy)~2.5s✅ Works with all appsXcode Devices window open\n\nDRM apps (YouTube, Netflix, Disney+, HBO Max) enforce HDCP and terminate the QuickTime AirPlay mirror entirely. Use Xcode method for these apps, or use Lookout for its own UI.\n\nConfiguration: Set default method in ~/.clawtv/config.json:\n\n{\n  \"screenshot_method\": \"auto\"\n}\n\nValues: auto (tries quicktime → lookout → xcode), quicktime, lookout, xcode"
      },
      {
        "title": "Disconnect QuickTime (disconnect)",
        "body": "Close the QuickTime mirror and auto-resume playback on the TV.\n\npython3 ~/Developer/clawtv/clawtv.py disconnect\n\nWhy: QuickTime mirroring shows a red recording border on the TV and routes audio to the Mac. After starting playback, always disconnect to remove the border and restore audio to the TV.\n\nAuto-resume: Sends play command twice to ensure playback resumes."
      },
      {
        "title": "Status Commands",
        "body": "# What's currently playing\npython3 ~/Developer/clawtv/clawtv.py playing\n\n# Find Apple TVs on network\npython3 ~/Developer/clawtv/clawtv.py scan\n\n# List installed apps with bundle IDs\npython3 ~/Developer/clawtv/clawtv.py apps"
      },
      {
        "title": "DRM Limitations",
        "body": "DRM apps (YouTube, Netflix, Disney+, HBO Max) terminate the QuickTime AirPlay mirror entirely. When this happens:\n\nQuickTime method shows a black screen\nClawTV auto-detects the disconnection in auto mode\nFalls back to Xcode method automatically\nOr manually use: --method xcode\n\nApps that work with QuickTime: Plex (local media), Settings, home screen, Apple TV+, most non-DRM apps."
      },
      {
        "title": "QuickTime Side Effects",
        "body": "When QuickTime mirror is active:\n\nRed recording border appears on TV\nAudio routes to Mac instead of TV speakers\nDRM apps may refuse to play\n\nSolution: Always run disconnect after starting playback. The do command does this automatically."
      },
      {
        "title": "Cost",
        "body": "Vision loop (AI agent mode): Uses Claude API for every see-think-act step. Each step = 1 API call with screenshot.\n\nTypical task: 5-10 steps = few cents\nComplex navigation: up to 20 steps = ~$0.10-0.20\nUses Haiku 4.5 (cheap) with auto-escalation to Sonnet 4.5 when stuck\n\nPlex direct control: 2 API calls total (pennies) — no vision loop.\n\nManual commands (cmd, type, launch): Zero API cost."
      },
      {
        "title": "Config File",
        "body": "~/.clawtv/config.json stores:\n\n{\n  \"devices\": {\n    \"Living Room\": {\n      \"identifier\": \"...\",\n      \"credentials\": \"...\"\n    }\n  },\n  \"screenshot_method\": \"auto\",\n  \"plex_url\": \"http://192.168.1.100:32400\",\n  \"plex_token\": \"your-plex-token\",\n  \"plex_client\": \"Living Room\"\n}"
      },
      {
        "title": "Companion Project",
        "body": "Lookout — tvOS app with built-in HTTP screenshot server at port 8080. Fastest possible screenshot method (~100ms) but only captures Lookout's own UI, not other apps."
      },
      {
        "title": "Requirements",
        "body": "macOS (uses AppleScript for automation)\nApple TV 4K (gen 2 or later, tvOS 16+) on same network as Mac\nPython 3.9+\nAnthropic API key for Claude vision\nQuickTime Player (built-in) or Xcode (free from App Store)"
      },
      {
        "title": "Troubleshooting",
        "body": "\"No Apple TV found\"\n\nRun python3 ~/Developer/clawtv/clawtv.py scan to verify device is on network\nCheck that Apple TV and Mac are on same WiFi/LAN\nVerify Apple TV is awake (not in sleep mode)\n\n\"QuickTime mirror disconnected\"\n\nDRM app killed the mirror — use --method xcode instead\nOr use Plex direct control to bypass vision entirely\n\n\"Screenshot failed\"\n\nQuickTime: Ensure AirPlay pairing is accepted on TV\nXcode: Verify Devices window is open and Apple TV is connected\nTry --method auto to fall back automatically\n\n\"API key not found\"\n\nSet export ANTHROPIC_API_KEY=sk-ant-... in your shell\nOr add to ~/.zshrc or ~/.bashrc\n\n\"Plex not found\"\n\nVerify plex_url, plex_token, and plex_client in config\nRun python3 ~/Developer/clawtv/clawtv.py plex clients to verify client name\nEnsure Plex server is running and accessible"
      },
      {
        "title": "Architecture",
        "body": "clawtv.py            — Single-file CLI: pairing, remote, screenshots, AI agent\n~/.clawtv/\n  config.json        — Device pairing credentials + settings\n  screenshots/       — Screenshot history (timestamped PNGs)\n\nStack:\n\npyatv — Apple TV remote control (Companion protocol)\nQuickTime Player — AirPlay mirror for screenshots (primary)\nXcode — Developer device screenshots (fallback)\nClaude — Vision + reasoning for autonomous navigation\npython-plexapi — Plex direct control"
      },
      {
        "title": "License",
        "body": "MIT — see LICENSE"
      }
    ],
    "body": "ClawTV\n\nAI-powered Apple TV remote that can see the screen and navigate any app autonomously using vision + remote control.\n\nWhen to use (trigger phrases)\n\nUse this skill immediately when the user asks:\n\n\"play [movie/show] on Apple TV\"\n\"search for [content] on [Netflix/Plex/YouTube/etc]\"\n\"open [app] on the TV\"\n\"turn on subtitles\" / \"go to TV settings\"\n\"what's playing on Apple TV?\"\n\"take a screenshot of the TV\"\nAny Apple TV navigation or control task\nQuick start\n# AI agent mode — tell it what you want in plain English\npython3 ~/Developer/clawtv/clawtv.py do \"open Plex and play Fight Club\"\npython3 ~/Developer/clawtv/clawtv.py do \"search for Stranger Things on Netflix\"\npython3 ~/Developer/clawtv/clawtv.py do \"go to settings and turn on subtitles\"\n\n# Direct Plex control (instant, no vision loop)\npython3 ~/Developer/clawtv/clawtv.py plex play \"Fight Club\"\npython3 ~/Developer/clawtv/clawtv.py plex play \"Westworld\" -s 2 -e 6\n\n# Manual remote commands\npython3 ~/Developer/clawtv/clawtv.py cmd up down select\npython3 ~/Developer/clawtv/clawtv.py type \"breaking bad\"\npython3 ~/Developer/clawtv/clawtv.py launch com.plexapp.plex\n\n# Screenshot\npython3 ~/Developer/clawtv/clawtv.py screenshot\n\n# Status\npython3 ~/Developer/clawtv/clawtv.py playing\n\nRequired Credentials\nANTHROPIC_API_KEY (Required for AI/Vision Mode)\n\nThe do command (AI agent mode) requires an Anthropic API key to access Claude's vision API for screenshot analysis and navigation decisions.\n\nexport ANTHROPIC_API_KEY=sk-ant-...\n\n\nOr add to your shell profile (~/.zshrc, ~/.bashrc).\n\nNote: This is only required for the do command. Manual commands (cmd, type, launch) and plex direct control do not use the API.\n\nPlex Credentials (Optional)\n\nFor instant Plex playback without the vision loop, add these to ~/.clawtv/config.json:\n\n{\n  \"plex_url\": \"http://192.168.1.100:32400\",\n  \"plex_token\": \"your-plex-token\",\n  \"plex_client\": \"Living Room\"\n}\n\nplex_url: Your Plex server address (local or remote)\nplex_token: Authentication token from your Plex account\nplex_client: Name of the Plex client on your Apple TV\n\nGet your Plex token: https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-token/\n\nPrivacy & Data\nWhat Data is Collected and Sent\n\nScreenshots:\n\nClawTV captures screenshots of your Apple TV screen using QuickTime Player or Xcode\nScreenshots are saved locally to ~/.clawtv/screenshots/ with timestamps\nWhen using the do command (AI agent mode), screenshots are sent to Anthropic's Claude API for vision analysis\nScreenshots may contain sensitive on-screen content including:\nContent you're watching (movie/show titles, thumbnails)\nSearch queries\nAccount information visible in app UIs\nAny other content displayed on your TV screen\n\nAnthropic API:\n\nOnly the do command sends data to Anthropic\nData sent: screenshots (JPEG compressed) + your goal/instruction + conversation history\nAnthropic's data retention policy: https://support.anthropic.com/en/articles/7996885-how-long-do-you-store-personal-data\nManual commands (cmd, type, launch) and Plex direct control do NOT send any data to external APIs\nCredential Storage\n\nApple TV Pairing Credentials:\n\nStored unencrypted in ~/.clawtv/config.json in your home directory\nContains device identifiers and pairing tokens for remote control\nFile permissions: readable only by your user account (standard Unix permissions)\n\nPlex Tokens (if configured):\n\nStored unencrypted in the same ~/.clawtv/config.json file\nGrants full access to your Plex server and library\nCan be used to play, pause, search, and control any Plex client\n\nAnthropic API Key:\n\nStored in environment variables or your shell profile\nGrants access to your Anthropic account and incurs API usage charges\nRecommendations\nUse a budget-limited API key: Set spending limits on your Anthropic account to prevent unexpected charges\nReview config file permissions: Ensure ~/.clawtv/config.json is only readable by your user\nBe aware of screenshot content: Screenshots are sent to Anthropic's API and may contain sensitive information\nMonitor API usage: The do command can make multiple API calls per task (5-20 steps typical)\nUse manual commands when possible: cmd, type, and launch have zero API cost and send no data externally\nSecurity Considerations\nPlaintext Credential Storage\nApple TV pairing credentials and Plex tokens are stored in plaintext in ~/.clawtv/config.json\nThe file is in your user home directory (~/.clawtv/) with standard Unix file permissions\nAny process running as your user can read these credentials\nIf your Mac is compromised, these credentials are accessible\nConsider this when deciding whether to configure Plex integration\nScreenshot Privacy\nScreenshots may contain sensitive content visible on your TV screen\nScreenshots are saved locally to ~/.clawtv/screenshots/ and persist until manually deleted\nWhen using AI agent mode (do), screenshots are transmitted to Anthropic's servers\nDRM content (Netflix, Disney+, etc.) cannot be captured via QuickTime, but works with Xcode method\nReview screenshot history periodically and delete sensitive captures\nAPI Cost and Autonomous Behavior\nThe do command runs in a loop (up to 20 steps) and makes Claude API calls automatically\nEach step = 1 API call with screenshot (~$0.01-0.02 per step depending on model)\nA stuck or confused agent could consume all 20 steps before giving up\nCost implications: Complex tasks can cost $0.10-0.20; monitor your Anthropic usage dashboard\nRecommendation: Set spending limits on your Anthropic account\nManual Commands are API-Free\ncmd, type, launch, and plex commands do not use the Claude API\nNo screenshots are sent externally when using these commands\nZero cost, zero external data transmission\nUse these for privacy-sensitive operations\nNetwork Exposure\nClawTV communicates with your Apple TV over your local network using the Companion protocol\nPlex integration (if configured) communicates with your Plex server (local or remote)\nNo external network access except:\nAnthropic API (when using do command)\nPlex server (if remote URL configured)\nSetup (first-time only)\n1. Install dependencies\ncd ~/Developer/clawtv\npip install -r requirements.txt\n\n\nFor QuickTime screenshot method (recommended):\n\npip install pyobjc-framework-Quartz\n\n2. Pair with Apple TV (remote control)\npython3 ~/Developer/clawtv/clawtv.py scan    # Find your Apple TV on network\npython3 ~/Developer/clawtv/clawtv.py pair    # Enter 4-digit PIN shown on TV\n\n\nPairing credentials are saved to ~/.clawtv/config.json.\n\n3. Set up screenshots\n\nQuickTime (recommended):\n\npython3 ~/Developer/clawtv/clawtv.py screenshot --method quicktime\n\nQuickTime Player opens and selects your Apple TV as video source\nAccept the AirPlay pairing on your TV (one-time PIN)\nSubsequent runs reuse the existing mirror instantly (~0.6s per screenshot)\n\nXcode (fallback for DRM apps):\n\nOn Apple TV: Settings > Privacy & Security → enable \"Share with App Devs\"\nThen Settings > Remotes and Devices > Remote App and Devices\nOn Mac: Open Xcode, press Cmd+Shift+2 (Devices)\nClick your Apple TV in sidebar, enter pairing code\nKeep Xcode Devices window open while using ClawTV\n4. Set API key\nexport ANTHROPIC_API_KEY=sk-ant-...\n\n\nOr add to your shell profile (~/.zshrc, ~/.bashrc).\n\n5. Optional: Plex direct control setup\n\nFor instant Plex playback without vision loop, add to ~/.clawtv/config.json:\n\n{\n  \"plex_url\": \"http://192.168.1.100:32400\",\n  \"plex_token\": \"your-plex-token\",\n  \"plex_client\": \"Living Room\"\n}\n\n\nGet your Plex token: https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-token/\n\nCommands\nAI Agent Mode (do)\n\nTell ClawTV what you want and it figures out the rest using vision + reasoning.\n\npython3 ~/Developer/clawtv/clawtv.py do \"<goal>\"\n\n\nHow it works:\n\nTakes screenshot of Apple TV\nSends to Claude vision API to analyze UI\nDecides what to do (navigate, select, type, launch app)\nSends remote commands\nTakes another screenshot to verify\nRepeats until goal is accomplished (max 20 steps)\n\nExamples:\n\npython3 ~/Developer/clawtv/clawtv.py do \"open Plex and play Fight Club\"\npython3 ~/Developer/clawtv/clawtv.py do \"search for Stranger Things on Netflix\"\npython3 ~/Developer/clawtv/clawtv.py do \"open YouTube and find lo-fi beats\"\npython3 ~/Developer/clawtv/clawtv.py do \"go to settings and turn on subtitles\"\npython3 ~/Developer/clawtv/clawtv.py do \"open Spotify and play my liked songs\"\n\n\nToken optimizations (automatic):\n\nPlex goals bypass vision entirely via direct API (instant, pennies)\nSliding window: only last 2 screenshots kept in context (~70% token reduction)\nImages compressed to JPEG 800px q50 (~40% fewer image tokens)\nSystem prompt cached via cache_control (90% savings on steps 2+)\nHaiku 4.5 for routine steps, auto-escalates to Sonnet 4.5 when stuck\n\nPlayback pattern: Navigate → start playback → verify playing → skip intro if visible → disconnect → report done\n\nRemote Commands (cmd)\n\nSend direct remote control commands without AI.\n\npython3 ~/Developer/clawtv/clawtv.py cmd <commands...>\n\n\nAvailable commands: up, down, left, right, select, menu, home, play, pause, play_pause, next, previous, volume_up, volume_down, top_menu\n\nExamples:\n\npython3 ~/Developer/clawtv/clawtv.py cmd up\npython3 ~/Developer/clawtv/clawtv.py cmd down down right select\npython3 ~/Developer/clawtv/clawtv.py cmd select sleep:1.5 down    # with timing\n\n\nTiming: Insert sleep:X between commands to add delays (in seconds).\n\nType Text (type)\n\nType text into a focused search/text field on the TV.\n\npython3 ~/Developer/clawtv/clawtv.py type \"<text>\"\n\n\nExample:\n\npython3 ~/Developer/clawtv/clawtv.py type \"breaking bad\"\n\n\nNote: The text field must already be focused. Use cmd to navigate to search first, or use do for full automation.\n\nLaunch App (launch)\n\nLaunch an app by bundle ID.\n\npython3 ~/Developer/clawtv/clawtv.py launch <bundle_id>\n\n\nExample:\n\npython3 ~/Developer/clawtv/clawtv.py launch com.plexapp.plex\n\n\nCommon bundle IDs:\n\nApp\tBundle ID\nPlex\tcom.plexapp.plex\nYouTube\tcom.google.ios.youtube\nHBO Max\tcom.wbd.stream\nPrime Video\tcom.amazon.aiv.AIVApp\nApple TV\tcom.apple.TVWatchList\nSpotify\tcom.spotify.client\nESPN\tcom.espn.ScoreCenter\nTwitch\ttv.twitch\nPluto TV\ttv.pluto.ios\nNFL\tcom.nfl.gamecenter\nDisney+\tcom.disney.disneyplus\nHulu\tcom.hulu.plus\nNetflix\tcom.netflix.Netflix\n\nUse python3 ~/Developer/clawtv/clawtv.py apps for the full list on your device.\n\nPlex Direct Control (plex)\n\nBypass the entire vision loop using Plex API directly. Searches your library and tells the Plex client on Apple TV to play. Instant playback, zero vision cost.\n\n# Play a movie\npython3 ~/Developer/clawtv/clawtv.py plex play \"Fight Club\"\n\n# Play a specific episode\npython3 ~/Developer/clawtv/clawtv.py plex play \"Westworld\" -s 2 -e 6\n\n# Search your library\npython3 ~/Developer/clawtv/clawtv.py plex search \"matrix\"\n\n# List Plex clients\npython3 ~/Developer/clawtv/clawtv.py plex clients\n\n# List libraries\npython3 ~/Developer/clawtv/clawtv.py plex libraries\n\n\nRequirements:\n\nplex_url, plex_token, and plex_client in ~/.clawtv/config.json\nPlex server running and accessible from Mac\nPlex client running on Apple TV\n\nAuto-detection: The do command automatically detects Plex goals (e.g., \"play Fight Club on Plex\") and routes through this path without any vision API calls.\n\nScreenshot (screenshot)\n\nTake a screenshot of the Apple TV and save to ~/.clawtv/screenshots/.\n\npython3 ~/Developer/clawtv/clawtv.py screenshot [--method auto|quicktime|lookout|xcode]\n\n\nScreenshot methods:\n\nMethod\tSpeed\tDRM Apps\tRequires\nQuickTime (default)\t~0.6s\t❌ Kills mirror (DRM)\tQuickTime Player, pyobjc-framework-Quartz\nLookout\t~0.1s\t❌ Only captures Lookout app\tLookout tvOS app running on Apple TV\nXcode (legacy)\t~2.5s\t✅ Works with all apps\tXcode Devices window open\n\nDRM apps (YouTube, Netflix, Disney+, HBO Max) enforce HDCP and terminate the QuickTime AirPlay mirror entirely. Use Xcode method for these apps, or use Lookout for its own UI.\n\nConfiguration: Set default method in ~/.clawtv/config.json:\n\n{\n  \"screenshot_method\": \"auto\"\n}\n\n\nValues: auto (tries quicktime → lookout → xcode), quicktime, lookout, xcode\n\nDisconnect QuickTime (disconnect)\n\nClose the QuickTime mirror and auto-resume playback on the TV.\n\npython3 ~/Developer/clawtv/clawtv.py disconnect\n\n\nWhy: QuickTime mirroring shows a red recording border on the TV and routes audio to the Mac. After starting playback, always disconnect to remove the border and restore audio to the TV.\n\nAuto-resume: Sends play command twice to ensure playback resumes.\n\nStatus Commands\n# What's currently playing\npython3 ~/Developer/clawtv/clawtv.py playing\n\n# Find Apple TVs on network\npython3 ~/Developer/clawtv/clawtv.py scan\n\n# List installed apps with bundle IDs\npython3 ~/Developer/clawtv/clawtv.py apps\n\nImportant Notes\nDRM Limitations\n\nDRM apps (YouTube, Netflix, Disney+, HBO Max) terminate the QuickTime AirPlay mirror entirely. When this happens:\n\nQuickTime method shows a black screen\nClawTV auto-detects the disconnection in auto mode\nFalls back to Xcode method automatically\nOr manually use: --method xcode\n\nApps that work with QuickTime: Plex (local media), Settings, home screen, Apple TV+, most non-DRM apps.\n\nQuickTime Side Effects\n\nWhen QuickTime mirror is active:\n\nRed recording border appears on TV\nAudio routes to Mac instead of TV speakers\nDRM apps may refuse to play\n\nSolution: Always run disconnect after starting playback. The do command does this automatically.\n\nCost\n\nVision loop (AI agent mode): Uses Claude API for every see-think-act step. Each step = 1 API call with screenshot.\n\nTypical task: 5-10 steps = few cents\nComplex navigation: up to 20 steps = ~$0.10-0.20\nUses Haiku 4.5 (cheap) with auto-escalation to Sonnet 4.5 when stuck\n\nPlex direct control: 2 API calls total (pennies) — no vision loop.\n\nManual commands (cmd, type, launch): Zero API cost.\n\nConfig File\n\n~/.clawtv/config.json stores:\n\n{\n  \"devices\": {\n    \"Living Room\": {\n      \"identifier\": \"...\",\n      \"credentials\": \"...\"\n    }\n  },\n  \"screenshot_method\": \"auto\",\n  \"plex_url\": \"http://192.168.1.100:32400\",\n  \"plex_token\": \"your-plex-token\",\n  \"plex_client\": \"Living Room\"\n}\n\nCompanion Project\n\nLookout — tvOS app with built-in HTTP screenshot server at port 8080. Fastest possible screenshot method (~100ms) but only captures Lookout's own UI, not other apps.\n\nRequirements\nmacOS (uses AppleScript for automation)\nApple TV 4K (gen 2 or later, tvOS 16+) on same network as Mac\nPython 3.9+\nAnthropic API key for Claude vision\nQuickTime Player (built-in) or Xcode (free from App Store)\nTroubleshooting\n\n\"No Apple TV found\"\n\nRun python3 ~/Developer/clawtv/clawtv.py scan to verify device is on network\nCheck that Apple TV and Mac are on same WiFi/LAN\nVerify Apple TV is awake (not in sleep mode)\n\n\"QuickTime mirror disconnected\"\n\nDRM app killed the mirror — use --method xcode instead\nOr use Plex direct control to bypass vision entirely\n\n\"Screenshot failed\"\n\nQuickTime: Ensure AirPlay pairing is accepted on TV\nXcode: Verify Devices window is open and Apple TV is connected\nTry --method auto to fall back automatically\n\n\"API key not found\"\n\nSet export ANTHROPIC_API_KEY=sk-ant-... in your shell\nOr add to ~/.zshrc or ~/.bashrc\n\n\"Plex not found\"\n\nVerify plex_url, plex_token, and plex_client in config\nRun python3 ~/Developer/clawtv/clawtv.py plex clients to verify client name\nEnsure Plex server is running and accessible\nArchitecture\nclawtv.py            — Single-file CLI: pairing, remote, screenshots, AI agent\n~/.clawtv/\n  config.json        — Device pairing credentials + settings\n  screenshots/       — Screenshot history (timestamped PNGs)\n\n\nStack:\n\npyatv — Apple TV remote control (Companion protocol)\nQuickTime Player — AirPlay mirror for screenshots (primary)\nXcode — Developer device screenshots (fallback)\nClaude — Vision + reasoning for autonomous navigation\npython-plexapi — Plex direct control\nLicense\n\nMIT — see LICENSE"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/akivasolutions/clawtv",
    "publisherUrl": "https://clawhub.ai/akivasolutions/clawtv",
    "owner": "akivasolutions",
    "version": "1.0.2",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/clawtv",
    "downloadUrl": "https://openagent3.xyz/downloads/clawtv",
    "agentUrl": "https://openagent3.xyz/skills/clawtv/agent",
    "manifestUrl": "https://openagent3.xyz/skills/clawtv/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/clawtv/agent.md"
  }
}