✨ 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 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.
• Uses transcript chunking to handle long videos, with provider-specific optimizations where they are measured to help.
• 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, summarize each chunk, and merge the results.
4. Output a Markdown file and/or print to stdout, with optional key points.

The portable chunked workflow is the default foundation. When a provider exposes capabilities that make a different route demonstrably worthwhile, reko can use it automatically while retaining the same output contract and safe fallback.

OpenAI routing optimization

For eligible official OpenAI models, reko has a benchmarked full-context route. It estimates input tokens locally, uses one request when the transcript safely fits a conservative capacity and cost threshold, generates directly in the target language, and validates the requested Markdown sections. Other providers and larger inputs continue to use the portable chunked workflow. This is an implementation detail rather than a provider preference, and leaves room for future provider-specific routes supported by comparable evidence.

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. Its benchmarked OpenAI route uses LiteLLM's local model metadata and tiktoken to choose a full-context request without contacting an extra API. It reserves completion and safety tokens, and uses a conservative fallback limit when metadata is unavailable. 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, the selected workflow, any applicable token estimate and route ceiling, 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.

Container logs remain available through Docker, for example with docker compose logs -f reko. The Compose service uses Docker's local logging driver with compression and rotation: up to three 10 MiB files are retained per container. Docker manages these files in its own data directory; do not edit them directly.

The image runs as UID/GID 10001 by default. If ./data is managed by your host user, set its actual numeric IDs in .env and align the directory ownership before starting the service:

REKO_UID=1000
REKO_GID=1000
sudo chown -R 1000:1000 ./data

Use id -u and id -g to obtain the correct values instead of assuming 1000. The container only receives the provider credentials explicitly declared in compose.yaml. For example, to use an OpenAI key from an ignored local .env, add this entry under the Compose service environment mapping:

OPENAI_API_KEY: ${OPENAI_API_KEY:-}

Then add OPENAI_API_KEY=... to .env and protect it with chmod 600 .env. Do not commit provider credentials.

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.

If a tagged release fails after PyPI accepts the artifacts, fix the later workflow configuration and rerun the workflow. Existing identical PyPI artifacts are skipped, so the rerun can continue to GHCR and the GitHub Release.

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.