✨ What is reko?

reko is a command-line tool that converts YouTube videos into clean Markdown summaries using transcripts and Large Language Models.

Give it a video URL, a playlist, or a file containing multiple URLs, and reko will fetch the transcript, summarize the content in manageable chunks, and generate a readable Markdown document with a summary and optional key points.

It’s designed to be simple, fast, and automation-friendly, making it easy to extract useful information from long, informational videos.
By default, reko is local-first and privacy-friendly when used with Ollama, while still supporting paid cloud models when needed.

🚀 Features

• Generate clean Markdown summaries with optional key points.
• Summarize a single video, a playlist, or a batch of URLs.
• Optimized for Small Language Models (SLMs), which are often sufficient for high-quality summarization.
• Works with Ollama and cloud providers via APIs.
• Multi-language summaries: uses native transcripts when available, with automatic fallback and translation.
• Handles long videos via transcript chunking.
• Skips reprocessing when a summary already exists (with an option to force regeneration).

🧠 How it works

At a high level, reko follows a simple pipeline:

1. Resolve the input target (video, playlist, or file).
2. Fetch the YouTube transcript in the requested language, with fallback and translation when needed.
3. Split the transcript into word-based chunks.
4. Summarize each chunk independently.
5. Merge chunk summaries into a coherent final result.
6. Output a Markdown file and/or print to stdout.
7. Optionally extract key points from the generated summary.

This approach allows reko to scale smoothly from short clips to multi-hour videos.

Transcript cache

Raw YouTube transcripts are cached locally by video ID and requested language. Re-running a video with different output options or LLM settings reuses the cached transcript and avoids unnecessary YouTube requests. Set REKO_DATA_DIR to choose the cache location; use --refresh-transcript only when you explicitly need to fetch a fresh transcript.

📦 Installation

Prerequisites

• Python 3.10–3.14 (all versions are verified in CI)
• An LLM endpoint:
  • Ollama (local): install Ollama and pull the model you want to use.
  • Hosted APIs (for example openai/...): configure the required API keys in your environment. When using non-local providers, the required environment variables must be configured according to the supported provider of the model which can be found here.

Install from PyPI

pip install reko-yt

⚡ Quick start

Show available commands:

reko --help
reko summarize --help

[!NOTE] Small Language Models are a great default for most summarization tasks.

Summarize a single YouTube video (prints and saves by default):

reko summarize 'https://www.youtube.com/watch?v=eMlx5fFNoYc' 'ollama/llama3.2:3b'
reko summarize 'https://www.youtube.com/watch?v=eMlx5fFNoYc' 'openai/gpt-5-nano'

For OpenAI GPT-5 models, reko uses the Responses API and maps --max-tokens to OpenAI's completion-token limit. GPT-5 reasoning models only support the default sampling temperature, so custom --temperature values are ignored for those models. You can tune reasoning cost/latency with:

reko summarize 'https://www.youtube.com/watch?v=eMlx5fFNoYc' \
  'openai/gpt-5-nano' \
  --reasoning-effort low

Generate key points only, in Italian, without saving to disk:

reko summarize 'https://www.youtube.com/watch?v=eMlx5fFNoYc' \
  'ollama/llama3.2:3b' \
  --length short \
  --language it \
  --key-points-only \
  --print-only

Summarize a playlist or a batch of URLs:

reko summarize 'https://www.youtube.com/playlist?list=PL908547EAA7E4AE74' 'ollama/llama3.2:3b'
reko summarize urls.txt 'ollama/llama3.2:3b'

[!WARNING] When processing playlists or large batches, YouTube may temporarily rate-limit your IP.
Using a proxy is recommended for high-volume usage.

Use a remote Ollama instance:

reko summarize 'https://www.youtube.com/watch?v=eMlx5fFNoYc' 'ollama/llama3.2:3b' --host 'http://YOUR_OLLAMA_HOST:11434'

🌐 Local web UI

Start a local web page that can summarize a YouTube URL and render the Markdown:

reko serve

Then open http://127.0.0.1:8000 in your browser.

Options:

reko serve --host 127.0.0.1 --port 8000
reko serve --host 0.0.0.0 --port 8000  # expose on your LAN

Notes:

• The web UI supports single video URLs (no playlists/batch files).
• Jobs run asynchronously. The UI streams progress with Server-Sent Events (SSE) and falls back to a one-second status poll when SSE is unavailable.
• A job reports transcript-cache hit/miss, chunk progress, retries, input/output words, elapsed time, phase timings, and terminal success/failure/cancellation.
• Cancel is cooperative: an active LLM request is allowed to finish, but no next phase is started. Failed and cancelled jobs can be retried from the UI.
• REKO_MAX_CONCURRENT_JOBS controls the in-memory job limit and defaults to 1, which is appropriate for a home server or a local LLM endpoint.
• If a reverse proxy is in front of reko, disable response buffering for /api/jobs/*/events and preserve text/event-stream; otherwise the browser will automatically use polling instead of live progress.

🐳 Container deployment

The container runs only reko. Configure Ollama or another LLM provider separately in the web UI; Ollama is intentionally not part of the Compose stack.

cp .env.example .env
docker compose up -d

Open http://YOUR_SERVER:8000. Transcript cache files are persisted in ./data. For an Ollama service running on the Docker host, use http://host.docker.internal:11434 in the UI; for a different host, use an address reachable from the container.

Check service health with:

curl http://localhost:8000/health

🧪 Development

All automated checks are offline and use mock data only. Install the development dependencies and run them with uv:

uv sync --group dev
uv run ruff format --check src test
uv run ruff check src test
uv run python -m pytest --cov=src/reko --cov-branch --cov-report=term-missing --cov-report=xml --cov-fail-under=90
uv build

🚀 Releases

The release workflow runs when a vX.Y.Z tag is pushed. It runs the offline quality checks, builds the Python distributions, publishes to PyPI through Trusted Publishing, pushes a tagged image to GHCR, and creates GitHub release notes with git-cliff.

Before the first release, configure PyPI Trusted Publishing for this repository and the release.yml workflow, create the protected GitHub environment named pypi, and set the GHCR package visibility you want. Set the release version in pyproject.toml; the workflow verifies that the tag version matches it.

To refresh the committed changelog before creating a release, run git-cliff locally:

git cliff --tag vX.Y.Z --output CHANGELOG.md

📄 License

MIT. See LICENSE.