tldw - too long; didn't watch

Transform YouTube videos and playlists into concise summaries using AI. Works with existing captions (free) or Whisper transcription (paid). Includes MCP server for Claude and other AI assistants and CLI.

See docs/architecture.md for the project structure and dependency direction.

Installation

brew install rtzll/tap/tldw
export OPENAI_API_KEY="your-api-key-here"  # optional: for AI summaries & Whisper

MCP

tldw mcp provides AI assistants with:

• get_youtube_metadata: Video metadata and captions status
• get_youtube_transcript: Free video captions transcript
• transcribe_youtube_whisper: Paid video Whisper transcription

get_youtube_transcript accepts include_timestamps=true to return caption lines with timestamps when timing data is available.

Claude Desktop Setup

Easy setup:

tldw mcp setup-claude

This automatically configures Claude Desktop to use tldw. Restart Claude Desktop afterward.

After setup, ask Claude: "tldw: https://youtu.be/tAP1eZYEuKA"

ChatGPT Setup

Use OpenAI Secure MCP Tunnel to connect ChatGPT to your local tldw mcp without exposing a public server.

Download tunnel-client from Platform tunnel settings.

mkdir -p bin
# Unzip the archive, then move the tunnel-client binary here:
mv /path/to/tunnel-client ./bin/tunnel-client
chmod +x ./bin/tunnel-client

export CONTROL_PLANE_API_KEY="sk-..."   # OpenAI runtime API key
export TLDW_TUNNEL_ID="tunnel_..."      # From Platform tunnel settings

just tunnel-init
just tunnel-doctor
just tunnel-run

The ChatGPT tunnel setup uses local HTTP MCP by default:

• tldw mcp --transport=http listens on 127.0.0.1:8765
• tunnel-client keeps its own health/UI listener on 127.0.0.1:8080

Override the MCP host or port with TLDW_MCP_HTTP_HOST or TLDW_MCP_HTTP_PORT before just tunnel-init, or rerun just tunnel-init after changing either value so the profile URL is updated.

Then open ChatGPT > Settings > Connectors > Create, choose Tunnel, and select or paste the tunnel ID. Keep just tunnel-run running while using the connector.

Optional: just tunnel-launchd-install stores the runtime key in Keychain and starts both the local HTTP MCP server and the tunnel at login. After upgrading tldw, run just tunnel-launchd-restart so launchd starts the new binary.

Tip: Put recurring summary prompts in a ChatGPT Project, then enable the tldw connector in chats from that Project.

CLI

Usage Examples

Single Videos

# Get transcript (free with captions)
tldw transcribe "https://youtu.be/tAP1eZYEuKA"
tldw transcribe tAP1eZYEuKA -o transcript.txt  # Save to file
tldw transcribe tAP1eZYEuKA --timestamps       # Include caption timestamps
tldw transcribe tAP1eZYEuKA --fallback-whisper # Use Whisper if video has no captions

# Copy transcript to clipboard
tldw cp "https://youtu.be/tAP1eZYEuKA"
tldw cp tAP1eZYEuKA --fallback-whisper        # Whisper fallback supported

# Generate summary (requires API key)
tldw "https://youtu.be/tAP1eZYEuKA"
tldw tAP1eZYEuKA -m gpt-4o-mini -p "tldr: {{.Transcript}}"

# Get video metadata
tldw metadata "https://youtu.be/tAP1eZYEuKA"
tldw metadata tAP1eZYEuKA -o metadata.json   # Save to file
tldw metadata tAP1eZYEuKA --pretty           # Format JSON output

# Show unique-video stats from the local metadata library
tldw stats
tldw stats --period month
tldw stats --period month --group-by day
tldw stats --period week --json

tldw stats reports the runtime of unique videos in the local metadata library. Supported periods are today, week, month, and all; grouped reports can use day, week, or month.

Transcription smoke test

Run the opt-in end-to-end check with:

just smoke-transcription

It builds tldw, transcribes the README video through both the CLI and the HTTP MCP get_youtube_transcript tool, and verifies that their timestamped outputs match. The test uses isolated temporary XDG directories and requires yt-dlp and network access. It is intentionally excluded from the default test suite.

Playlists

# Summarize entire playlist (use an explicit playlist URL)
tldw "https://youtube.com/playlist?list=PLSE8ODhjZXjYDBpQnSymaectKjxCy6BYq"

# URLs with a video ID and list parameter are treated as that single video
tldw "https://youtu.be/tAP1eZYEuKA?list=PLSE8ODhjZXjYDBpQnSymaectKjxCy6BYq"

Note: Playlist support is currently for summaries. Transcript and metadata commands accept individual videos.

Example Output

Summaries are shown as markdown and rendered in the terminal.

Configuration

Either edit the config file or use environment variables.

Config file

Find your config location:

tldw paths  # Shows config, data, and cache directories

Edit config file: config.toml

openai_api_key = "your-key"
tldr_model = "gpt-5.4-mini"
prompt = "tldr: {{.Transcript}}"

or edit the prompt.txt file in the config directory to change the default summary prompt.

Environment variables

export OPENAI_API_KEY="your-key"
export TLDW_TLDR_MODEL="gpt-5.4-mini"
export TLDW_PROMPT="tldr: {{.Transcript}}"