Turns a YouTube video into a dense Markdown rules file you can load as Claude Code context — not a raw transcript dump.
yt-distiller https://www.youtube.com/watch?v=EcbgbKtOELY --profile design
# -> context/how-to-design-better-uis.md (147 lines, every one actionable)Every YouTube-to-Markdown tool gives you a transcript. A transcript is 8,000 words of "so basically what I like to do here is..." with # headings sprinkled on top. Dropping that into an agent's context window is expensive and steers badly, because the model has to infer the rules from anecdote.
yt-distiller treats the transcript as an intermediate artifact. The deliverable is a short, imperative rules document — the kind of thing that belongs in a CLAUDE.md:
### Spacing
- Use a 4pt base unit. Every gap is a multiple of it.
- Give related elements 8pt; unrelated groups get 32pt minimum.
- Never use margin on both sides of a boundary. Pick one direction.
## Anti-patterns
- Don't centre body text. (Ragged left edge kills scan speed.)
- Don't use pure black on pure white. (Contrast is harsh at large areas.)Roughly 100–200 lines regardless of whether the source was 8 minutes or 2 hours. Cutting is the job.
Requires Python 3.11+, uv, and Claude Code (used for the distillation pass — no separate API key needed).
The distillation step shells out to the claude command, so the Claude Code CLI must be
installed and on your PATH — the Claude Desktop app on its own does not expose it.
Verify with claude --version, and run claude once to sign in if you haven't.
git clone https://github.com/KupperLupperDupper/tool.yt-distiller
cd tool.yt-distiller
uv sync
uv run yt-distiller --helpOptional, for videos with no captions at all:
uv sync --extra whisperyt-distiller <url> [options]| Option | Default | Description |
|---|---|---|
--profile |
general |
Which distillation profile to apply (design, technical, general, or your own) |
--out |
./context |
Output directory |
--lang |
en |
Caption language to prefer |
--refresh |
off | Re-distil from the cached transcript without re-fetching |
--dry-run |
off | Print the pipeline plan and exit without calling the model |
--keep-raw |
on | Keep the intermediate transcript file |
--whisper-model |
base |
Model for the tier-3 Whisper fallback (tiny … large-v3) |
Two files land in the output directory:
<slug>.raw.md— metadata + normalised transcript. The cache.<slug>.md— the distilled document. The thing you actually load.
Iterating on a profile is cheap because fetching is the slow, rate-limited part:
vim prompts/design.md # tweak the extraction instructions
yt-distiller <url> --refresh # re-distil from cache, no network---
source: https://www.youtube.com/watch?v=...
title: How to Design Better UIs
channel: ...
duration: 18m42s
extracted: 2026-08-10
profile: design
transcript_source: auto-captions
---
# How to Design Better UIs — extracted guidelines
## TL;DR
3–5 bullets. The thesis of the video.
## Rules
Grouped under topical headings. One imperative line each, with specific
values kept verbatim — px, ratios, hex, tool names.
## Anti-patterns
Things to avoid, each with the stated reason in parentheses.
## Uncertain / opinion
Claims that are the speaker's taste rather than defensible principle.
This section is deliberate: it stops the rules above from being over-trusted.Coarse timestamps survive as HTML comments, so you can trace any rule back to the moment it was said.
Profiles are plain Markdown prompt files in prompts/, not code. Edit them freely.
| Profile | For |
|---|---|
design |
Design and UI talks. Emphasises concrete values and anti-patterns. |
technical |
Architecture and engineering talks. Preserves trade-offs and constraints. |
general |
Everything else. Claims, evidence, conclusions. |
Adding one is just dropping prompts/<name>.md in place and passing --profile <name>.
| Stage | What happens |
|---|---|
| 1. Metadata | yt-dlp --dump-json --skip-download for title, channel, date, chapters |
| 2. Transcript | Three fallback tiers, first success wins (below) |
| 3. Normalise | Strip caption timing artifacts, dedupe repeated auto-caption lines, merge into paragraphs |
| 4. Distil | Chunk to ~15k tokens with overlap, one pass per chunk, then a merge pass to dedupe and resolve contradictions |
| 5. Write | Frontmatter + the distilled document |
Transcript fallback tiers:
youtube-transcript-api— fastest, no download, works on most videosyt-dlp --write-auto-subs— more robust to blockingfaster-whisper— downloads audio and transcribes locally. Slow; you're warned before it starts.
The tier used is recorded in the output frontmatter, because tier 3 output is noticeably noisier and worth knowing about when you're reading the results.
- Extraction is faithful to what was said. If the speaker was vague, the rules will be thin — the tool won't fill gaps from general knowledge, by design.
- Auto-captions mangle proper nouns and code. Check anything that looks like an API name.
- YouTube rate-limits transcript requests from datacentre IPs. This is built to run on your own machine.
- Single video only. No playlists, no channels, no GUI, no database.
MIT