How steipete/summarize works
1. Repository shape
This is a TypeScript monorepo with three main deliverables: a terminal CLI (src/), a browser extension (apps/chrome-extension/), and a shared core library (packages/core/). The root also contains docs, tests, release tooling, and CI workflows. pnpm workspaces and Vitest are the primary build/test tooling.
2. Top-level architecture
The project is organized around a single product idea: extract content from URLs/files/media, optionally transcribe or render slides, then summarize with an LLM. The CLI can run standalone, while the extension delegates heavy work to a local daemon. Shared logic is reused across both surfaces rather than duplicated.
3. CLI execution path
The CLI entrypoint (src/cli-main.ts, src/cli.ts) feeds into the src/run/ orchestration layer. That layer resolves input type, applies config and flags, runs extraction/transcription, builds prompts, selects a model/provider, and emits either streamed Markdown, text, or JSON diagnostics. It also owns progress reporting, terminal formatting, retries, and finish-line/cost/metrics output.
4. Daemon as browser-extension backend
The daemon (src/daemon/) is the bridge between the extension and the local machine. It exposes HTTP/SSE endpoints, session/state routes, summarize routes, and admin/status routes. The extension talks to 127.0.0.1 with token-based auth; the daemon then executes the same core summarization and media pipelines used by the CLI. It is designed to autostart via platform-specific service managers.
5. Browser extension structure
apps/chrome-extension/ is a multi-entry extension with a Side Panel / Firefox Sidebar, an options page, background scripts, and content scripts. The side panel provides chat, navigation, summary rendering, and slides UI. The background layer mediates between panel state, page content, and the daemon. Content scripts handle page extraction/hover/automation tasks inside the active tab.
6. Extension UX subsystems
The side panel is not just a thin viewer: it has its own chat session state, streaming controllers, history storage, slide rendering, summary rendering, navigation handling, and UI settings. There is also a dedicated options page for daemon status, skill/model configuration, logging, and persistence. The panel and options page communicate through shared contracts and runtime message bridges.
7. Content extraction subsystem
The core content pipeline lives in packages/core/src/content/ and src/content/. It covers link previews, readable-HTML extraction, JSON-LD parsing, Firecrawl fallback, URL normalization, and specialized handling for YouTube, podcasts, and generic media pages. This layer is responsible for producing a clean textual representation before any LLM work happens.
8. Media and transcript pipeline
Media handling is a major subsystem, not an edge case. For YouTube, podcasts, audio, and video, the system prefers existing transcripts, then falls back to local or remote transcription providers. The project also has a slide-extraction flow (src/slides/ and src/run/flows/url/slides-*) that uses scene detection, frame extraction, OCR, and timestamped slide cards. External tools like ffmpeg, yt-dlp, tesseract, and whisper/transcription providers materially shape this pipeline.
9. LLM/provider layer
src/llm/ and parts of packages/core/src/transcription/ abstract model selection and provider-specific behavior. The repo supports OpenAI-compatible providers plus Anthropic, Google, OpenRouter, NVIDIA, Z.AI, and several CLI backends like Claude/Gemini/Codex/Agent. There is built-in model auto-selection, capability checks, streaming support, prompt formatting, and provider-specific limits/compatibility handling.
10. Configuration and state boundaries
Configuration is layered: CLI flags override SUMMARIZE_* env vars, which override ~/.summarize/config.json, with defaults as fallback. State is split by concern: summary cache, media cache, transcript cache, slide outputs, daemon/session state, and extension persistence. This separation matters because the same input may be processed through different caches depending on whether it came from the CLI, daemon, or extension.
11. Shared contracts
The repo uses explicit contract modules to keep the CLI, daemon, and extension in sync: shared SSE events, runtime/panel payloads, status objects, token/metrics types, and slides text contracts. These contracts are important architecture boundaries because they define what can cross process and transport lines safely.
12. Infrastructure and delivery
The project ships via npm/Homebrew and also supports an installable browser extension. The daemon can register itself with launchd/systemd/Scheduled Tasks, and the repo includes GitHub Actions for CI and GitHub Pages for docs. The documentation site is part of the architecture because it explains operational flows like daemon install, media requirements, and Firefox compatibility.
Main entry points: run Run engine · sidepanel Side panel · content Content extraction · transcript Transcript engine
Components 20
CLI & Daemon
Terminal entrypoint, orchestration, and local backend service.
- CLI entrypoint · Main terminal entrypoints that parse flags and hand off to the runner.
src/cli-main.ts - Run engine · Coordinates input resolution, extraction, prompting, model selection, streaming, and finish-line output.
src/run - URL flow · URL-centric extraction and summary flow, including markdown, timestamps, JSON, and slide variants.
src/run/flows/url - Asset flow · File and media ingestion flow for local assets and cached summaries.
src/run/flows/asset - Slides pipeline · Scene detection, frame extraction, OCR, and slide output rendering.
src/slides - Daemon server · Local HTTP/SSE backend with session, summarize, admin, and agent routes for the extension.
src/daemon/server.ts - Daemon runtime · Daemon request handling, model wiring, progress tracking, autostart integration, and state management.
src/daemon - LLM layer · Model/provider selection, streaming generation, prompt formatting, and provider-specific behavior.
src/llm
Browser Extension
Side panel, options page, background bridge, and content scripts.
- Side panel · Chat, summary, navigation, slides, and streaming UI for the browser extension.
apps/chrome-extension/src/entrypoints/sidepanel - Background bridge · Mediates panel state, tab content, daemon access, and runtime message flows.
apps/chrome-extension/src/entrypoints/background - Options page · Daemon status, model and skill configuration, logging, and persistence controls.
apps/chrome-extension/src/entrypoints/options - Content scripts · Extraction, hover, and automation scripts running in the active tab.
apps/chrome-extension/src/entrypoints - Extension contracts · Shared payloads, SSE, token, metrics, settings, and daemon-status utilities.
apps/chrome-extension/src/lib
Shared Core
Reusable content extraction, transcript, prompt, and contract logic.
- Content extraction · Shared URL normalization, link previews, readable HTML, JSON-LD, and media-aware extraction.
packages/core/src/content - Transcript engine · Transcript detection, normalization, parsing, caching, and provider flows for YouTube and podcasts.
packages/core/src/content/transcript - Transcription providers · Whisper and remote transcription backends, chunking, ffmpeg integration, and provider setup.
packages/core/src/transcription - Prompt kit · Shared prompt builders and summary-length/system templates.
packages/core/src/prompts - Shared contracts · Cross-runtime event, stream, slides, status, and payload contracts.
packages/core/src/shared/contracts.ts
Delivery & Ops
Docs, CI, packaging, release, and workspace tooling.
- Docs site · Operational docs for CLI, extension, media, config, daemon install, and release flows.
docs - CI & release · GitHub Actions, packaging scripts, release helpers, and workspace configuration.
.github/workflows/ci.yml
Connections 27
- CLI entrypoint → Run engine: starts · CLI entrypoints hand off parsed commands and flags to the run engine.
- Run engine → Content extraction: extracts · The run layer uses shared extraction for URLs and media pages.
- Run engine → Transcript engine: loads transcripts · The run layer resolves transcripts before LLM summarization.
- Run engine → Prompt kit: builds prompts · Prompt templates shape summary and extract-only output.
- Run engine → LLM layer: generates · The run engine streams text or JSON through provider abstractions.
- Run engine → Slides pipeline: renders slides · URL flows can branch into slide extraction and slide output rendering.
- Run engine → URL flow: routes url · URL inputs are processed through the URL flow.
- Run engine → Asset flow: routes asset · Files and local media are processed through the asset flow.
- Daemon server → Daemon runtime: serves · HTTP/SSE endpoints expose the daemon runtime to clients.
- Daemon runtime → Content extraction: reuses · Daemon-backed requests use the same extraction layer as the CLI.
- Daemon runtime → Transcript engine: reuses · Daemon-backed requests use the shared transcript pipeline.
- Daemon runtime → LLM layer: summarizes · The daemon delegates model execution to the shared LLM layer.
- Side panel → Background bridge: messages · The side panel talks to the background layer for tab and daemon actions.
- Background bridge → Daemon server: calls localhost · The extension reaches the local daemon over token-authenticated HTTP/SSE.
- Background bridge → Content scripts: coordinates tab · Background scripts bridge panel state with content-script extraction and automation.
- Side panel → Extension contracts: shares contracts · Panel UI relies on shared extension payload and state contracts.
- Options page → Extension contracts: shares contracts · Options UI uses the same settings, status, and persistence helpers.
- Content scripts → Content extraction: extracts pages · Content scripts feed page data into the shared extraction logic.
- Content extraction → Transcript engine: prefers transcripts · Media-aware extraction can hand off to transcript discovery and normalization.
- Transcript engine → Transcription providers: falls back · When transcripts are unavailable, transcription providers are used.
- Content extraction → Shared contracts: serializes · Extraction and stream results are shaped by shared contracts.
- Transcript engine → Shared contracts: serializes · Transcript and timestamp payloads use shared contracts.
- Side panel → Shared contracts: consumes · The panel renders SSE, summary, and slides payloads from shared contracts.
- Docs site → CLI entrypoint: documents · Docs cover CLI usage and operational flows.
- Docs site → Side panel: documents · Docs explain extension behavior and browser support.
- CI & release → CLI entrypoint: builds · Workspace tooling and CI produce the CLI and daemon artifacts.
- CI & release → Side panel: builds · CI and release tooling also package the browser extension.