repository·main·Indexed 27 days ago
https://github.com/steipete/summarizeA tool for generating fast summaries from URLs, files, and media including YouTube and podcasts. It provides a CLI, a browser extension for Chrome and Firefox, and an optional daemon for advanced media processing, native OCR, and enhanced AI capabilities. Supports multiple providers including OpenAI, Anthropic, Gemini, and local Ollama models. Includes @steipete/summarize-core for content extraction and prompt building.
The execution engine (src/engine) is a headless core responsible for summary policy and execution. It is designed to be transport-agnostic and does not depend on terminal (TTY), daemon, or HTTP layers.
Key Responsibilities of the Engine:
Adapter Responsibilities (CLI, Daemon, Browser):
Adapters are responsible for the UI and transport layers, including stdout/stderr, terminal rendering, progress lifecycles, and SSE/HTTP serialization.
The project documentation is organized into several specialized guides covering different aspects of the Summarize tool. You can find specific information in the following files:
docs/chrome-extension.md (Side panel extension and daemon setup/troubleshooting)docs/cache.md (SQLite cache design and configuration)docs/cli.md (Claude, Codex, Gemini, Agent, OpenClaw, OpenCode, Copilot, Antigravity, pi)docs/config.md (File location, precedence, and schema)docs/extract-only.md (Running without LLM summarization)docs/engine.md (Headless execution engine)docs/firecrawl.md (Firecrawl mode and API key usage)docs/language.md (Setting output language via --language or config)docs/llm.md (Summarization via Gateway or OpenAI)docs/manual-tests.md (End-to-end test checklist)docs/model-auto.md (Using --model auto)docs/ollama.md (Using local Ollama models via OpenAI-compatible endpoints)docs/openai.md (OpenAI model usage and flags)docs/releasing.md (Release checklist and Homebrew verification)docs/smoketest.md (20-case smoke test plan)docs/website.md (HTML extraction and Firecrawl fallback)docs/youtube.md (Transcript extraction via youtubei, captionTracks, or Apify)summarize CLI supports multiple input types including URLs, YouTube videos, and local files. Use the --model flag to specify the LLM and the --length flag to control summary verbosity. For YouTube videos, use the --youtube auto flag to enable automatic caption/transcript handling.OPENAI_API_KEY environment variable. summarize will forward this value as an Authorization: Bearer … header. For bare Ollama instances, any value for this variable is acceptable.The recommended way to release the project is using the scripts/release.sh helper script. This script manages the complex workflow of publishing to npm, building artifacts, and preparing GitHub releases.
Release Phases:
gates: Runs pre-flight checks (pnpm install, check, build).build: Builds various artifacts (Bun, Chrome, Firefox).publish: Publishes core and CLI to npm using the next tag, performs a smoke test, and then promotes to latest.tag: Creates an annotated git tag.github: Verifies the GitHub Release and assets.homebrew: Verifies the Homebrew installation.deprecate: Used to deprecate a broken version.all: Runs the full release pipeline.Run summarize followed by a URL to generate a streaming Markdown summary in your terminal. The default summary length is long (~4k chars). You can adjust the length using the --length flag with predefined values like short or specific character counts.
summarize "https://en.wikipedia.org/wiki/Llama"
# Custom lengths
summarize "https://example.com/long-article" --length short
summarize "https://example.com/long-article" --length 3k
summarize "https://example.com/long-article" --length 30000The summarize CLI can be used to extract and summarize various content types. It uses Readability for articles, markitdown for files, and various transcript fetchers for media.
Common usage patterns include:
yt-dlp + Whisper).--extract to skip the LLM and output only the cleaned content, which is ideal for piping to other tools.summarize using -.# Web page
summarize "https://example.com/article"
# YouTube
summarize "https://youtu.be/I845O57ZSy4"
# Local file with specific model
summarize ./report.pdf --model openai/gpt-5-mini
# Extract content only (no LLM) for pipes
summarize "https://example.com" --extract --format md | wc -w
# From clipboard/stdin
pbpaste | summarize -To use specific LLM providers with summarize, you must set the corresponding API key in your environment or a .env file in the current working directory. Some providers also allow overriding the base URL for OpenAI-compatible endpoints.
XAI_API_KEY (Optional: XAI_BASE_URL)OPENAI_API_KEY (Optional: OPENAI_BASE_URL, OPENAI_USE_CHAT_COMPLETIONS)NVIDIA_API_KEY or NGC_API_KEY (Optional: NVIDIA_BASE_URL)MINIMAX_API_KEY (Optional: MINIMAX_BASE_URL)OPENROUTER_API_KEY (Used if OPENAI_BASE_URL points to OpenRouter)GITHUB_TOKEN or GH_TOKEN (for github-copilot/... models)Z_AI_API_KEY or XAI_API_KEY (Optional: Z_AI_BASE_URL)OLLAMA_BASE_URL (Default: http://localhost:11434/v1)GEMINI_API_KEY or GOOGLE_API_KEY or GOOGLE_GENERATIVE_AI_API_KEY (Optional: GOOGLE_BASE_URL or GEMINI_BASE_URL)ANTHROPIC_API_KEY (Optional: ANTHROPIC_BASE_URL)If process environment variables are missing, summarize reads fallback defaults from ~/.summarize/config.json under the env key.
The CLI can summarize websites, handle podcast URLs, and use specific transcription providers.
--max-output-tokens to limit output.--max-output-tokens value (e.g., 99999) will print the extracted text without invoking an AI model.ASSEMBLYAI_API_KEY is set, it will use assemblyai as the transcriptionProvider.--metrics detailed to see more information during processing.The daemon allows the Chrome extension to access native tools (like yt-dlp, ffmpeg, and tesseract OCR), shared caches, and CLI model fallbacks. To pair the extension with the CLI, you must install the daemon using a token copied from the extension's Side Panel.
If you use a non-default port, you must specify it during installation and then update the extension settings in Options → Runtime → Daemon → Port.
When extending the project with a new transcript provider, follow these implementation rules to maintain architectural consistency:
transcription-capability.ts to include the new provider's capabilities (e.g., canTranscribe).