yt-transcript

YouTube Transcript

Fetch a YouTube video's transcript and save it as a clean Markdown document.

When to Use

• User shares a YouTube URL and asks for the transcript
• User says "grab the transcript", "transcribe this video", "get captions from this video"
• User wants to save a YouTube video's content as notes

How to Run

Use the CLI script at ${CLAUDE_PLUGIN_ROOT}/yt_transcript.py. Run it with uv run from the plugin directory:

cd "${CLAUDE_PLUGIN_ROOT}" && uv run python yt_transcript.py [OPTIONS] URL OUTPUT

Arguments

Argument	Description
URL	YouTube video URL or bare 11-char video ID
OUTPUT	Output filename (e.g. notes/talk.md). .md extension added automatically if missing.

Options

Option	Default	Description
--timestamps / --no-timestamps	--timestamps	Include [M:SS] timestamps per line, or merge into clean paragraphs
--language, -l	en	Transcript language code

Defaults

• Use --no-timestamps unless the user explicitly asks for timestamps. Clean paragraphs are better for notes.
• If the user doesn't specify an output file, generate one by slugifying the video ID (e.g. hnwM01CpzmA.md) in the current working directory.

Example

cd "${CLAUDE_PLUGIN_ROOT}" && uv run python yt_transcript.py --no-timestamps "https://www.youtube.com/watch?v=dQw4w9WgXcQ" ~/notes/rick-roll.md

After Running

• Read the saved file and provide a brief summary (title, key points) if the user asked for one.
• Report the saved file path, title, channel, and approximate word count.

Error Handling

• If the transcript fetch fails, tell the user -- the video may not have captions, or the language may not be available.
• If uv is not available, instruct the user to install it.