2,500+ videos scanned · 130+ outliers found · 30 AI copy angles · ~30 seconds to scan
viral-ops scans YouTube channels you admire, scores every video by how far it outperformed that channel's average, surfaces the top outliers, and uses AI to explain exactly why each one went viral — then generates three copy angles tailored to your niche.
Outputs: a swipe file in Markdown and a beautiful dark-mode gallery that opens in your browser automatically.
- Channel scanning — point it at any YouTube handle or channel ID, scores every video in seconds
- Virality scoring — every video gets a score:
views ÷ channel average. No guessing, no vibes - Outlier detection — anything above your threshold (default 2×) is flagged automatically
- AI analysis — top outliers analyzed for hook mechanics, viral drivers, and 3 copy angles tailored to your exact niche
- Dark-mode gallery — YouTube-style grid with thumbnails, virality badges, copy angle previews on hover, full analysis on expand — auto-opens in your browser
- Swipe file — every hook, title, and copy angle saved to a clean Markdown file
- On-demand analysis — dig into any of the 128 saved outliers later with
viral-ops analyze - Content type filter — scan longform only, Shorts only, or both
- Multi-provider AI — Gemini free tier by default, Claude or OpenAI as alternatives
The gallery it generates:
Hover any thumbnail for copy angle previews. Click to watch on YouTube. Expand Analysis for the full breakdown.
| viral-ops | Manual Research | |
|---|---|---|
| Videos scanned | 2,500+ in ~30 seconds | Scroll for hours |
| Channels at once | Unlimited | One at a time |
| Virality scoring | Automatic (math) | Eyeballed |
| AI copy angles | ✅ Instant, niche-specific | ❌ ChatGPT separately |
| Gallery export | ✅ Auto-opens in browser | ❌ Screenshot folder chaos |
| Swipe file | ✅ Clean Markdown | ❌ Notes app |
| Repeatable | ✅ One command | ❌ Start over every time |
# 1. Clone and install
git clone https://github.com/tabato/viral-ops.git && cd viral-ops
python3.11 -m venv .venv && source .venv/bin/activate
pip install -e .
# 2. Configure
cp templates/profile.example.yml profile.yml
cp templates/creators.example.yml creators.yml
cp templates/.env.example .env # add your API keys
# 3. Run
viral-opsPython 3.11+ required. Run
python3.11 --versionto confirm. On Mac:brew install python@3.11
That's it. Gallery opens automatically when the run finishes.
→ Having trouble? See SETUP.md for step-by-step API key setup and troubleshooting.
Get a free key at aistudio.google.com/app/apikey — no credit card, instant. Free tier: 15 req/min · 1M tokens/day · $0.
→ Full setup guide: GEMINI.md
Paid API. Best if you want more voice-forward copy angles or are already on an Anthropic plan.
Uses claude-sonnet-4-6 · ~$0.50 per full run.
→ Full setup guide: CLAUDE.md
Paid API. Uses gpt-4o-mini · under $0.01 per full run.
→ Full setup guide: OPENAI.md
- Go to console.cloud.google.com
- Enable YouTube Data API v3
- Go to Credentials → Create API key → Public data
- Add to
.env:YOUTUBE_API_KEY=your_key_here
Free tier: 10,000 quota units/day. A typical viral-ops run uses ~60–80 units.
viral-ops is a research tool, not a content copy machine.
It tells you why things work — the psychological hooks, the format patterns, the timing signals. The copy angles it generates are starting points for your own voice, not scripts to paste verbatim.
The best creators don't copy what went viral. They understand it well enough to make their own version better.
niche: "AI sales coaching for business owners and entrepreneurs"
target_audience: "Founders and sales professionals who want to use AI to close more deals"
content_style: "Mix of talking head, tutorials, and short-form clips — direct and high-energy"
# FREE ✨ | gemini claude openai
ai_provider: gemini
virality_threshold: 2.0 # flag videos that outperform channel avg by this multiple
months_back: 4 # how far back to scan
# Which videos to include:
# both — everything (default)
# longform — videos over 5 minutes only. Filters out Shorts AND short clips
# (1–4 min repurposes). Keeps only true long-form content where
# the full 16:9 thumbnail format makes sense.
# shorts — only YouTube Shorts (60 seconds or under)
content_type: bothThe more specific your niche and target_audience, the sharper the AI copy angles.
creators:
- "@AlexHormozi"
- "@danmartell"
- "UCX6OQ3DkcsbYNE6H8uQQuVA" # channel ID also worksMix handles (@handle) and channel IDs freely.
| File | What's in it |
|---|---|
gallery.html |
Dark-mode grid — thumbnails, virality badges, copy angle preview on hover, full analysis on expand. Auto-opens in browser. |
swipe_file.md |
Full written analysis for each video: hook breakdown, why it went viral, and 3 copy angles tailored to your niche. Your content cheat sheet. |
outliers.json |
Every ranked outlier from the scan saved locally — used by viral-ops analyze so you never have to rescan. |
thumbnails/ |
Downloaded thumbnail images used by gallery.html. |
Scans all channels, scores every video, analyzes the top 3 outliers with AI, and opens the gallery.
viral-ops [OPTIONS]
-p, --profile PATH Path to profile.yml [default: profile.yml]
-c, --creators PATH Path to creators.yml [default: creators.yml]
-o, --output PATH Output directory [default: .]
--top INTEGER How many outliers to analyze [default: 3]
--no-browser Don't auto-open gallery
After a scan, all outliers are saved to outliers.json. Use this command to analyze any of them on demand — no re-scanning needed.
# Show the full ranked list and pick interactively
viral-ops analyze
# Go straight to a specific video by rank
viral-ops analyze --rank 7Example workflow:
$ viral-ops
# → Scans 1,200+ videos, finds 128 outliers, analyzes top 3, opens gallery
# → All 128 outliers saved to outliers.json
$ viral-ops analyze --rank 12
# → Pulls video #12 from the saved list, runs AI analysis, appends to swipe_file.md
virality_score = video_views / channel_average_views
A score of 3.5x means that video got 3.5× more views than that channel's typical video in the same time window. This controls for channel size — a 100K-view video on a small channel can outperform a 1M-view video on a massive one.
Videos above virality_threshold (default 2.0) are flagged as outliers.
- viral-ops uses the YouTube Data API v3 in compliance with YouTube's Terms of Service
- No video content is downloaded — only metadata and publicly available thumbnails
- AI-generated copy angles are starting points, not finished scripts
- Respect the creators whose content you're studying — understand the pattern, don't lift the execution
Went viral using viral-ops? Share it.
If you're building something, making content, or just want to talk — find me here:
MIT © 2026
Inspired by career-ops.