yt-is — YouTube Intelligence System
YouTube transcript ingestion and analysis pipeline — discover new videos, download transcripts with the full fallback chain (oEmbed → yt-dlp → yt-dlp+cookies → direct API → NotebookLM → Selenium → Whisper), and store results in CKS.
Operator Notes
For implementation gotchas, recurring bugs, and lessons learned from live canaries, see CODEX_MEMORY.md.
Quick Start
# Check tracked channels for new videos
/yt-is sync
# Industrial Ingest (NLM Batch) - BEST FOR BACKLOG (worker-count dependent; benchmark sweep continues through 8 workers)
/yt-nlm
# Surgical Fetch (full transcript fallback chain)
/yt-is fetch
Installation
Three Deployment Models
IMPORTANT: This package supports three different deployment modes. Choose the right one for your use case.
1. SKILLS (Dev Deployment) ⭐ Recommended for Development
For: When you're actively developing this package and want instant feedback.
Setup:
# Windows (Junction - No admin required)
New-Item -ItemType Junction -Path "$CLAUDE_ROOT/skills\yt-is" -Target "$CLAUDE_ROOT/skills\yt-is"
New-Item -ItemType Junction -Path "$CLAUDE_ROOT/skills\yt-nlm" -Target "$CLAUDE_ROOT/skills\yt-nlm"
Key points:
- Skills are in
P://.claude/skills/yt-is/ and P://.claude/skills/yt-nlm/
- Changes to skill files take effect immediately
- No reinstallation required
2. SYMLINK (CLI Tools)
For: When you want yt-is and csf-source commands available in your terminal.
Setup:
# Symlink bin tools to a directory in your PATH
cmd /c "mklink P://bin/yt-is $CLAUDE_PLUGIN_ROOT/bin\yt-is"
cmd /c "mklink P://bin/csf-source $CLAUDE_PLUGIN_ROOT/bin\csf-source"
Key points:
yt-is — channel management (sync, list, add, fetch)csf-source — backend for channel and transcript operations- Both commands share the same SQLite database
3. PLUGINS (End User Deployment)
For: Distributing this package to other users via marketplace or GitHub.
Setup:
# End users install via /plugin command
/plugin P://packages/yt-is
# Or from marketplace (when published)
/plugin install yt-is
Skills
/yt-is — YouTube Channel Management
Check all tracked YouTube channels for new videos and manage your channel list.
Commands:
sync — Check all tracked channels for new videoslist — List all tracked channels with metadataadd <url> — Add a new channel or playlist to trackfetch — Download transcripts for all pending videos using the full fallback chain
Escalation Chain (per video):
- yt-dlp (WEB client) — Fastest (~5 seconds), works for most public videos
- yt-dlp with cookies — For age-restricted videos
- Selenium Firefox — Fallback for bot-check failures (~15-30 seconds)
/yt-nlm — NotebookLM Transcript Extraction
Extract YouTube transcripts using NotebookLM's batch notebook workflow.
Recommended approach: Worker-owned batch notebooks (one notebook per worker title, reused across batches; batch size 200) — uses nlm source content (raw text), has auth auto-recovery built in.
Auth contract for tests: nlm login covers the CLI path only. The DOM/spinner readiness path uses a separate persistent Chrome profile and must be bootstrapped once with a signed-in browser session before DOM tests will work. yt-is also refreshes the NotebookLM CLI itself with uv tool install --upgrade notebooklm-mcp-cli unless YTIS_NLM_AUTO_UPDATE=0, then probes nlm login --check and falls back to the known-good pinned git spec via YTIS_NLM_FALLBACK_SPEC if the latest release breaks login on this machine.
Old approach (deprecated): Ephemeral notebooks — one notebook per video, slow, wastes NotebookLM slots.
CLI Tools
yt-is
Channel management CLI wrapping csf-source.
yt-is sync # Check all tracked channels for new videos
yt-is list # List all tracked channels
yt-is add <url> # Add a new channel to track
yt-is fetch # Download pending transcripts (full fallback chain)
yt-is fetch --dry-run # Preview what would be fetched
yt-is fetch --source <url> # Process only one channel
yt-is fetch --workers 2 # Use 2 parallel workers
csf-source
Backend implementation for channel and transcript operations.
