| name | analyze-social |
| description | Use when the user shares a social video/post link or local video and wants it understood — an Instagram (instagram.com), TikTok (tiktok.com), YouTube or YouTube Shorts (youtube.com/youtu.be), or X/Twitter (x.com/twitter.com) URL, or a local .mp4/.mov file, OR when they say "analyze/watch/transcribe this video/reel/post." Downloads it, transcribes the audio, extracts frames Claude can see, and produces a thorough breakdown. |
Analyze Social (watch a video/post for the user)
Overview
Turns a social link (or local video) into material you can actually read: sampled
frames you view with native vision, a full transcript, and the post's caption.
Then you write a thorough breakdown. A bundled cross-platform Python pipeline does
the fetching/transcribing; you do the understanding.
When to use
- The user pastes an Instagram / TikTok / YouTube / YouTube Shorts / X (Twitter) URL.
- The user gives a local video file path.
- The user asks to watch / analyze / transcribe / summarize a video, reel, short, or post.
Workflow
-
Run the pipeline (use the Bash tool):
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/analyze.py" "<URL or local file path>"
- The first run auto-installs its tools (yt-dlp, gallery-dl, a Whisper engine, and ffmpeg). Tell the user this one-time setup can take a few minutes and may ask them to approve installs. Subsequent runs are fast.
- Useful flags:
--no-transcribe (frames + caption only, faster), --target-frames N, --lang <code>.
-
Read the printed result block. It ends with ERROR_CODE, BUNDLE, TYPE, FRAMES, TRANSCRIPT. Handle the error code:
NEEDS_LOGIN → the content is private/login-walled. Ask the user: "Which browser are you logged into that platform on? (chrome / firefox / safari / edge / brave)" then re-run with --cookies-from-browser <browser>. Only do this when the user has opted in — reading browser cookies is sensitive and may trigger a keychain prompt.RATE_LIMITED → tell them to wait a few minutes, or retry with --cookies-from-browser to use their logged-in session.SETUP_FAILED → show the MESSAGE (usually a one-line command to install ffmpeg) and offer to run it.none → success, continue.
-
Load the bundle. Read manifest.json (the contract) from the BUNDLE path, then:
- Read
meta.txt (caption + metadata) and, if present, transcript.txt.
- View the frames with the Read tool — a spread across the timeline (first, several middle, last) for video; all slides in order for an image carousel. You read on-screen text/captions directly from the frames; no separate OCR.
-
Write the analysis using the template below.
Output template (be thorough — a faithful record, not a teaser)
- Header — platform · creator handle/name · date · type · duration · engagement (views/likes/comments if present) · URL.
- TL;DR — 1–2 sentences: what this is.
- Full transcript — verbatim, everything. The complete spoken audio word-for-word, with timestamps from
transcript.srt. Do not summarize or drop lines. The only allowed cleanup is collapsing obvious hallucinated repeat-lines (e.g. "Okay. Okay. Okay."), never real speech. If there's no audio/speech, say so.
- On-screen text & visuals (timeline) — everything visible across the frames: text overlays/captions transcribed, graphics, charts/numbers, b-roll, setting, what the creator is doing, products/profiles shown. For carousels: every slide in order, with its full text + a description of its image.
- Caption / description — verbatim — exactly as posted, including hashtags, @mentions, links.
- Beat-by-beat structure (video) — how it's built, with timestamps: hook → point 1 → … → CTA.
- Takeaway & intent — core message, what it's actually sharing, the goal (educate / sell / lead-gen / entertain), and any explicit CTA.
- Notable details — names, tools, stats, claims, prices, links, anything quotable.
Adapt per type: a plain text tweet skips transcript/frames; an image carousel leans on the visuals section.
Then stay open for follow-ups ("just the hook," "list every stat," "summarize in 3 bullets," etc.).
Notes
- Everything runs locally; nothing is uploaded. Browser cookies are read only when the user opts in for login-walled content.
- TikTok and YouTube are usually public (no login). Instagram posts/carousels and many X posts require being logged in.
