youtube-advisor 0.1.0__tar.gz

youtube_advisor-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,45 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Extract release notes from CHANGELOG
+        id: notes
+        run: |
+          VERSION="${GITHUB_REF#refs/tags/v}"
+          NOTES=$(awk -v ver="$VERSION" '
+            /^## \[/ {
+              if (capture) exit
+              if (index($0, "[" ver "]")) { capture = 1; next }
+            }
+            capture { print }
+          ' CHANGELOG.md)
+          if [ -z "$NOTES" ]; then
+            echo "No CHANGELOG entry for v$VERSION" >&2
+            exit 1
+          fi
+          {
+            echo "notes<<NOTES_EOF"
+            echo "$NOTES"
+            echo "NOTES_EOF"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          name: ${{ github.ref_name }}
+          body: ${{ steps.notes.outputs.notes }}
+          prerelease: ${{ contains(github.ref_name, '-') }}

youtube_advisor-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+*.bak
+*.tmp
+.venv/
+.pytest_cache/
+*.egg-info/
+build/
+dist/
+.DS_Store
+tests/cassettes/_local/
+tests/fixtures/whisper-cache/

youtube_advisor-0.1.0/AGENTS.md

@@ -0,0 +1,19 @@
+# youtube-advisor — build a Claude Code advisor from any YouTube channel
+
+> AGENTS.md is a tool-agnostic pointer for non-Claude-Code AI agents (Codex CLI, Cursor, Continue.dev, Aider, Goose, …). Setup is the only thing that differs per tool; the workflow, rules, and worked examples are canonical in [SKILL.md](./SKILL.md).
+
+## Your tool → how to wire
+
+| Tool                          | Setup                                                                                  | Invoke                                              |
+| ----------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| **Claude Code**               | `git clone … ~/.claude/skills/youtube-advisor`                                         | `/youtube-advisor` then paste channel + intent      |
+| **OpenAI Codex CLI**          | clone anywhere, place `AGENTS.md` at `~/.codex/AGENTS.md` (or project root)            | "build me an advisor on @ycombinator"               |
+| **Cursor**                    | clone anywhere, copy `AGENTS.md` → `.cursor/rules/youtube-advisor.md`                  | mention `@youtube-advisor` or natural language       |
+| **Continue.dev**              | clone anywhere, register as custom slash command in `~/.continue/config.yaml`          | `/youtube-advisor <channel>`                        |
+| **Aider**                     | clone anywhere, `aider --read <install-dir>/AGENTS.md`                                        | natural language in chat                             |
+| **Goose** (Block)             | clone anywhere, add as a shell-command extension                                       | mention youtube-advisor                              |
+| **No AI at all**              | clone anywhere                                                                          | `youtube-advisor bootstrap --channel @yc --out ...` (see CLI in README) |
+
+The bash CLI works in any environment with or without an AI driving it.
+
+> See [SKILL.md](./SKILL.md) for the full workflow, two-action user contract, worked examples, anti-patterns, and installation prerequisites.

youtube_advisor-0.1.0/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to youtube-advisor will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-06-06
+
+First public beta. Build a Claude Code advisor skill from any YouTube channel.
+
+### Added
+- Two-action user UX: paste a channel + intent in chat → AI builds the advisor → invoke `/<channel-slug>-advisor` to ask questions.
+- Three-tier transcript cascade: `youtube-transcript-api` (free YT captions) → `yt-dlp` VTT fallback → local Whisper via `faster-whisper` or scriba.
+- Hybrid retrieval: BM25 + dense embeddings (`fastembed` with `bge-small-en-v1.5` default, `bge-m3` opt-in for multilingual) fused via Reciprocal Rank Fusion.
+- Citation-first answer contract: every answer carries verbatim quotes with `youtube.com/watch?v=ID&t=SECONDS` deep-links.
+- LLM-drafted SKILL.md and benchmark per advisor (when `ANTHROPIC_API_KEY` is set) — OR — handoff to the AI agent in chat via `.pending-llm-draft.json` when no API key is set (`--no-llm` mode, auto-detected).
+- Incremental updates: saved selection filter is replayed on `update`, only new videos are fetched and indexed.
+- Eval scaffolding: generated benchmark + runner with regression detection (`--run-evals`).
+- Selection DSL: `--channel`, `--playlist`, `--since`, `--until`, `--max`, `--title-include`, `--title-exclude`, `--ids`.
+- Anti-bot defaults: 1–5s randomized sleep between yt-dlp requests, exponential-backoff retries on HTTP 429.
+- Live progress: bootstrap writes `<advisor>/.progress.json` on every stage change and per-video ingest; `scripts/status.sh <advisor>` (and `youtube-advisor status <advisor>`) print a one-line snapshot for a peek from a side terminal.
+- YouTube JS-challenge solver: yt-dlp invocations now pass `--remote-components ejs:github` (auto-detected via `yt-dlp --help` probe — silently omitted on older yt-dlp builds without the flag) and `--extractor-args youtube:formats=missing_pot` to avoid HTTP 429s and PO-token errors. Requires `deno` on PATH at runtime; `install.sh` now warns if missing.
+- Cookie support: `--cookies-from-browser {chrome,firefox,safari,brave,edge,…}`, `--cookies <file>`, env vars `YOUTUBE_ADVISOR_COOKIES_BROWSER` / `YOUTUBE_ADVISOR_COOKIES_FILE`, and auto-discovery of `~/.config/youtube-advisor/cookies.txt`.
+- OSS scaffolding: MIT license, scriba-style README, CONTRIBUTING, THIRD_PARTY_LICENSES, `bash scripts/install.sh` helper.
+- Python package uses `src/` layout (`src/youtube_advisor/`).
+- 183 tests (unit + integration + E2E).
+
+### Known limitations
+- Single channel per advisor (multi-channel rollups planned for v0.2).
+- Length-based filtering (e.g. "interviews > 60 minutes") not yet a selection flag.
+- LangDetect on update doesn't re-fire — corpus language persists from bootstrap.
+
+[Unreleased]: https://github.com/AlexanderAbramovPav/youtube-advisor/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/AlexanderAbramovPav/youtube-advisor/releases/tag/v0.1.0

youtube_advisor-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Contributing to youtube-advisor
+
+Issues and pull requests welcome. A few orientation notes:
+
+## Project layout
+
+- `src/youtube_advisor/` — Python package (filters / fetch_channel / ingest tiers / build_index / build_embeddings / search / gen_skill_md / gen_benchmark / eval_runner / postrun_guide / bootstrap / update / cli). Uses the [src layout](https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/).
+- `templates/` — Jinja2 scaffolds rendered into each emitted advisor.
+- `tests/` — unit + integration + E2E. Tier-1/Tier-2 ingest tests use mock subprocess + fixture VTT files (no live network). E2E tests mock at module boundaries and exercise the real index/search/eval pipeline.
+
+## Running tests
+
+```bash
+cd youtube-advisor && source .venv/bin/activate
+pytest -q                    # default: all unit + E2E (mocked-network only)
+pytest -m slow               # requires RUN_SLOW=1 — actual fastembed model + faster-whisper
+pytest -m e2e                # E2E only
+```
+
+## Adding a fixture channel
+
+`tests/fixtures/yc_flat.json` is a `yt-dlp --flat-playlist -J` snapshot of `@ycombinator/videos`. To add another channel for testing, run:
+
+```bash
+yt-dlp --flat-playlist -J --playlist-end 5 https://www.youtube.com/@<handle>/videos > tests/fixtures/<handle>_flat.json
+```
+
+then patch `subprocess.run` in your test to return this JSON (see `tests/test_fetch_channel.py`).
+
+## Swapping the embedding model
+
+The default is `BAAI/bge-small-en-v1.5` (384-dim, 24 MB). To experiment with another `fastembed`-supported model, pass `--multilingual` to use `BAAI/bge-m3` (1 GB) or fork `youtube_advisor/build_embeddings.py` to accept a custom model name and re-run `build_embeddings` with `incremental=False` to re-encode the corpus.
+
+## Adding language tests
+
+Captions language is auto-detected from the YT API; advisor answer language is configurable. To add a language-specific assertion, ingest a Russian or Spanish video (e.g., a Lex Fridman interview with non-English content) and add a test that verifies `transcript_language` in the frontmatter and `corpus_language` in `corpus_meta.json`.
+
+## Style
+
+- Follow the project's CLAUDE.md conventions: no defensive code for impossible cases; only validate at system boundaries; minimal comments (only when the WHY is non-obvious).
+- TDD: write the failing test first, then minimal implementation, then commit.
+- One concern per file. Files growing past ~150 lines are a smell.
+
+## Releasing
+
+We use [Semantic Versioning](https://semver.org/) and maintain a [Keep a Changelog](https://keepachangelog.com/) at `CHANGELOG.md`.
+
+To cut a release:
+
+1. Move the `## [Unreleased]` block's entries under a new `## [X.Y.Z] — YYYY-MM-DD` heading.
+2. Bump `version` in `pyproject.toml` to match.
+3. Commit: `release: vX.Y.Z`.
+4. Tag: `git tag -s vX.Y.Z -m "vX.Y.Z"`.
+5. Push: `git push && git push --tags`.
+
+The release workflow (`.github/workflows/release.yml`) creates a GitHub Release with the CHANGELOG entry as the body.
+
+Tags that contain a hyphen (e.g. `v0.2.0-beta1`) are auto-marked as prereleases.

youtube_advisor-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Abramov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

youtube_advisor-0.1.0/PKG-INFO

@@ -0,0 +1,255 @@
+Metadata-Version: 2.4
+Name: youtube-advisor
+Version: 0.1.0
+Summary: Turn any YouTube channel into an AI assistant skill that answers questions with verbatim quotes and timestamped video links.
+Project-URL: Homepage, https://github.com/AlexanderAbramovPav/youtube-advisor
+Project-URL: Repository, https://github.com/AlexanderAbramovPav/youtube-advisor
+Project-URL: Issues, https://github.com/AlexanderAbramovPav/youtube-advisor/issues
+Project-URL: Changelog, https://github.com/AlexanderAbramovPav/youtube-advisor/blob/main/CHANGELOG.md
+Project-URL: Releases, https://github.com/AlexanderAbramovPav/youtube-advisor/releases
+Author: Alexander Abramov
+License: MIT License
+        
+        Copyright (c) 2026 Alexander Abramov
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: advisor,agent-skill,bm25,claude-code,claude-skill,fastembed,llm,rag,semantic-search,transcripts,youtube,yt-dlp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Text Processing :: Indexing
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: anthropic>=0.34.0
+Requires-Dist: click>=8.1
+Requires-Dist: fastembed>=0.3.0
+Requires-Dist: jinja2>=3.1
+Requires-Dist: numpy>=1.26
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rank-bm25>=0.2.2
+Requires-Dist: tqdm>=4.66
+Requires-Dist: youtube-transcript-api>=0.6.2
+Requires-Dist: yt-dlp>=2024.5.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: vcrpy>=6.0; extra == 'dev'
+Provides-Extra: multilingual
+Requires-Dist: fastembed[multilingual]; extra == 'multilingual'
+Provides-Extra: whisper
+Requires-Dist: faster-whisper>=1.0.0; extra == 'whisper'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="docs/logo.png" alt="youtube-advisor" width="180" />
+</p>
+
+<h1 align="center">youtube-advisor</h1>
+
+<p align="center">
+  <strong>Turn any YouTube channel into an AI assistant skill that answers questions with verbatim quotes and timestamped video links.</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/AlexanderAbramovPav/youtube-advisor/stargazers"><img alt="GitHub Stars" src="https://img.shields.io/github/stars/AlexanderAbramovPav/youtube-advisor?style=flat-square&label=Stars&logo=github&color=lightgrey" /></a>
+  <a href="https://github.com/AlexanderAbramovPav/youtube-advisor/releases/latest"><img alt="Latest release" src="https://img.shields.io/github/v/release/AlexanderAbramovPav/youtube-advisor?style=flat-square&label=Release&color=lightgrey" /></a>
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-lightgrey?style=flat-square" /></a>
+  <img alt="100% Local" src="https://img.shields.io/badge/100%25-Local-lightgrey?style=flat-square" />
+  <img alt="No API key" src="https://img.shields.io/badge/No_API_Key-required-lightgrey?style=flat-square" />
+</p>
+
+---
+
+## What it feels like
+
+```
+You: build an advisor on @ycombinator,
+     last 200 videos, hiring + fundraising
+
+AI:  ✓ Resolving @ycombinator (200 videos)
+     ✓ Fetching transcripts (3 min)
+     ✓ Indexing + embedding
+     ✓ Advisor ready: /yc-advisor
+
+You: /yc-advisor how should I think about hiring my first engineer?
+AI:  → answer with quoted videos and timestamps
+```
+
+## Install
+
+Paste this in your AI chat (Claude Code, Cursor, Codex CLI, etc.):
+
+> Install youtube-advisor for me. The repo is https://github.com/AlexanderAbramovPav/youtube-advisor.
+
+The AI clones, runs `scripts/install.sh`, checks `ffmpeg` and `uv`, sets up the venv. You walk away.
+
+## Use it
+
+**Create an advisor.** Drop a channel URL or handle in chat with a one-sentence intent:
+
+```
+build an advisor on @ycombinator from the last 200 videos,
+focused on hiring and fundraising
+```
+
+```
+make an advisor on @lexfridman, interviews from 2024 onwards
+```
+
+The assistant resolves the channel, fetches transcripts, builds indices, drafts the advisor's voice, and runs a self-check. No flags, no paths, no shell. You get a new slash command like `/yc-advisor`.
+
+**Ask the advisor.**
+
+```
+/yc-advisor how should I think about hiring my first engineer?
+```
+
+Every answer comes back with verbatim quotes and clickable timestamps linking to the exact second of the source.
+
+**Refresh later.** One sentence:
+
+```
+refresh @ycombinator — check for new videos this week
+```
+
+The assistant replays your original selection filter, fetches only what's new, re-indexes the delta, and tells you what changed.
+
+## Why
+
+- **Local-first.** Transcripts and indices live on your disk. No SaaS account, no per-query fees, no vendor that can take your corpus offline.
+- **Verbatim quotes with timestamps.** Every answer is grounded in real transcript text and links to `youtube.com/watch?v=ID&t=SECONDS` — click and the video opens at that exact second.
+- **Uses your AI's brain.** Skill drafting and answering run through whatever assistant you're already using — nothing extra to configure.
+- **Free captions when available; local Whisper when not.** A three-tier cascade keeps cost near zero and falls back to on-device transcription only when YouTube has none.
+- **Incremental updates that respect your filter.** Your original selection (channel + date range + title filters + max count) is saved and replayed on every refresh.
+
+## What an answer looks like
+
+> *"The scariest fundraising stories are the ones where the founder spends six months on an 'almost-yes' from an investor who eventually just ghosts."*
+>
+> — [Dalton & Michael: Fundraising Mistakes (2024-03-12), 14:22](https://youtube.com/watch?v=abc123&t=862)
+
+Each citation is a real line from a real video, anchored to the second. Click through and verify.
+
+## Limitations
+
+- **One channel per advisor.** Multi-channel rollups ("YC + Naval + a16z combined") are planned for v0.2.
+- **Whisper fallback is CPU-bound.** Videos without YT captions fall back to local Whisper — roughly 1 hour of compute per 1 hour of audio on Apple Silicon. The assistant warns you and asks before going that route.
+- **YouTube anti-bot.** Defaults (1–5s randomized sleep, exponential-backoff retries on 429) handle most cases. On persistent blocks the assistant will offer to use cookies from your logged-in browser.
+
+## Works with other AI tools
+
+`AGENTS.md` is a tool-agnostic mirror of `SKILL.md`. Wire it into whichever tool you use:
+
+| Your tool          | Where to point it                                                              | How to invoke                            |
+| ------------------ | ------------------------------------------------------------------------------ | ---------------------------------------- |
+| Claude Code        | clone into `~/.claude/skills/youtube-advisor/`                                 | `/youtube-advisor <request>`             |
+| OpenAI Codex CLI   | clone anywhere, place `AGENTS.md` at `~/.codex/AGENTS.md` (or project root)    | "build me an advisor on `<channel>`"     |
+| Cursor             | clone anywhere, copy `AGENTS.md` to `.cursor/rules/youtube-advisor.md`         | `@youtube-advisor` or natural language   |
+| Continue.dev       | clone anywhere, register `youtube-advisor` as a custom slash command           | `/youtube-advisor <request>`             |
+| Aider              | clone anywhere, `aider --read <install-dir>/AGENTS.md`                         | natural language in chat                 |
+| Goose (Block)      | clone anywhere, add as a shell-command extension                               | mention youtube-advisor in chat          |
+| No AI at all       | clone anywhere                                                                 | `youtube-advisor bootstrap --channel @… --out …` |
+
+<details>
+<summary><strong>Advanced — for CI and scripting</strong></summary>
+
+Everything below is for power users running outside an AI chat (CI, cron, scripts). **You almost never need this.**
+
+### Manual install
+
+```bash
+git clone https://github.com/AlexanderAbramovPav/youtube-advisor ~/.claude/skills/youtube-advisor
+cd ~/.claude/skills/youtube-advisor && bash scripts/install.sh
+```
+
+### CLI
+
+```bash
+# Bootstrap
+youtube-advisor bootstrap \
+  --channel @ycombinator \
+  --since 2022-01-01 \
+  --max 200 \
+  --title-include "Founder Stories|How to" \
+  --title-exclude "shorts|#shorts" \
+  --out ~/.claude/skills/yc-advisor \
+  --yes
+
+# Update (replays the saved selection filter)
+youtube-advisor update --advisor ~/.claude/skills/yc-advisor --yes
+
+# Update — override date, reindex only, or run regression evals
+youtube-advisor update --advisor ~/.claude/skills/yc-advisor --since 2026-01-01 --yes
+youtube-advisor update --advisor ~/.claude/skills/yc-advisor --reindex-only
+youtube-advisor update --advisor ~/.claude/skills/yc-advisor --run-evals --yes
+```
+
+`youtube-advisor bootstrap --help` and `youtube-advisor update --help` print the full flag list.
+
+### Bypassing YT anti-bot with browser cookies
+
+When unauthenticated channel-resolution gets 429-blocked, pass cookies from a logged-in browser. yt-dlp reads them straight from the browser profile — no copy-paste:
+
+```bash
+youtube-advisor bootstrap --channel @ycombinator --out ~/.claude/skills/yc-advisor \
+  --cookies-from-browser chrome --yes
+
+# Or a Netscape-format cookies.txt:
+youtube-advisor bootstrap --channel @ycombinator --out ~/.claude/skills/yc-advisor \
+  --cookies ~/secrets/yt-cookies.txt --yes
+```
+
+Resolution order: explicit flag → `YOUTUBE_ADVISOR_COOKIES_BROWSER` / `YOUTUBE_ADVISOR_COOKIES_FILE` env → `~/.config/youtube-advisor/cookies.txt` if present → none. With cookies set the captions pool stays at concurrency 8; without them it drops to 2 + per-call jitter so YT is less likely to block you.
+
+### Vendoring `_lib`
+
+`youtube-advisor bootstrap --vendor` copies the `youtube_advisor` Python package into the emitted advisor's `scripts/_lib/`. Useful if you want the advisor directory to be fully portable (pushed to a separate Git repo and cloned elsewhere without a Python install of `youtube-advisor`).
+
+### Eval-driven regression detection
+
+`youtube-advisor update --advisor <path> --run-evals` reruns the channel's generated benchmark after sync and prompts to roll back if pass rate dropped.
+
+</details>
+
+## License
+
+[MIT](./LICENSE) — © 2026 Alexander Abramov.
+
+Runtime dependencies (yt-dlp, youtube-transcript-api, fastembed, faster-whisper, rank-bm25, ffmpeg, scriba) are installed locally, not vendored. Their licenses are catalogued in [`THIRD_PARTY_LICENSES.md`](./THIRD_PARTY_LICENSES.md).
+
+## Acknowledgments
+
+This tool is glue around several excellent OSS projects:
+
+- [**yt-dlp**](https://github.com/yt-dlp/yt-dlp) — channel resolution, caption download, audio extraction.
+- [**youtube-transcript-api**](https://github.com/jdepoix/youtube-transcript-api) — Jonas Depoix — Tier 1 captions fetcher.
+- [**fastembed**](https://github.com/qdrant/fastembed) — Qdrant — local embedding inference with `bge-small-en-v1.5` (BAAI).
+- [**rank-bm25**](https://github.com/dorianbrown/rank_bm25) — Dorian Brown — BM25 ranking.
+- [**faster-whisper**](https://github.com/SYSTRAN/faster-whisper) — SYSTRAN — local ASR fallback.
+- [**scriba**](https://github.com/AlexanderAbramovPav/scriba) — sibling skill — alternative Whisper transcription backend.
+- [**uv**](https://github.com/astral-sh/uv) (Astral) for env setup, and [`ffmpeg`](https://ffmpeg.org/) for audio extraction.
+- Conceptual lineage: [yc-avisor](https://github.com/AlexanderAbramovPav/cowork) — the hand-rolled YC-channel-specific predecessor.

youtube_advisor-0.1.0/README.md

@@ -0,0 +1,189 @@
+<p align="center">
+  <img src="docs/logo.png" alt="youtube-advisor" width="180" />
+</p>
+
+<h1 align="center">youtube-advisor</h1>
+
+<p align="center">
+  <strong>Turn any YouTube channel into an AI assistant skill that answers questions with verbatim quotes and timestamped video links.</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/AlexanderAbramovPav/youtube-advisor/stargazers"><img alt="GitHub Stars" src="https://img.shields.io/github/stars/AlexanderAbramovPav/youtube-advisor?style=flat-square&label=Stars&logo=github&color=lightgrey" /></a>
+  <a href="https://github.com/AlexanderAbramovPav/youtube-advisor/releases/latest"><img alt="Latest release" src="https://img.shields.io/github/v/release/AlexanderAbramovPav/youtube-advisor?style=flat-square&label=Release&color=lightgrey" /></a>
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-lightgrey?style=flat-square" /></a>
+  <img alt="100% Local" src="https://img.shields.io/badge/100%25-Local-lightgrey?style=flat-square" />
+  <img alt="No API key" src="https://img.shields.io/badge/No_API_Key-required-lightgrey?style=flat-square" />
+</p>
+
+---
+
+## What it feels like
+
+```
+You: build an advisor on @ycombinator,
+     last 200 videos, hiring + fundraising
+
+AI:  ✓ Resolving @ycombinator (200 videos)
+     ✓ Fetching transcripts (3 min)
+     ✓ Indexing + embedding
+     ✓ Advisor ready: /yc-advisor
+
+You: /yc-advisor how should I think about hiring my first engineer?
+AI:  → answer with quoted videos and timestamps
+```
+
+## Install
+
+Paste this in your AI chat (Claude Code, Cursor, Codex CLI, etc.):
+
+> Install youtube-advisor for me. The repo is https://github.com/AlexanderAbramovPav/youtube-advisor.
+
+The AI clones, runs `scripts/install.sh`, checks `ffmpeg` and `uv`, sets up the venv. You walk away.
+
+## Use it
+
+**Create an advisor.** Drop a channel URL or handle in chat with a one-sentence intent:
+
+```
+build an advisor on @ycombinator from the last 200 videos,
+focused on hiring and fundraising
+```
+
+```
+make an advisor on @lexfridman, interviews from 2024 onwards
+```
+
+The assistant resolves the channel, fetches transcripts, builds indices, drafts the advisor's voice, and runs a self-check. No flags, no paths, no shell. You get a new slash command like `/yc-advisor`.
+
+**Ask the advisor.**
+
+```
+/yc-advisor how should I think about hiring my first engineer?
+```
+
+Every answer comes back with verbatim quotes and clickable timestamps linking to the exact second of the source.
+
+**Refresh later.** One sentence:
+
+```
+refresh @ycombinator — check for new videos this week
+```
+
+The assistant replays your original selection filter, fetches only what's new, re-indexes the delta, and tells you what changed.
+
+## Why
+
+- **Local-first.** Transcripts and indices live on your disk. No SaaS account, no per-query fees, no vendor that can take your corpus offline.
+- **Verbatim quotes with timestamps.** Every answer is grounded in real transcript text and links to `youtube.com/watch?v=ID&t=SECONDS` — click and the video opens at that exact second.
+- **Uses your AI's brain.** Skill drafting and answering run through whatever assistant you're already using — nothing extra to configure.
+- **Free captions when available; local Whisper when not.** A three-tier cascade keeps cost near zero and falls back to on-device transcription only when YouTube has none.
+- **Incremental updates that respect your filter.** Your original selection (channel + date range + title filters + max count) is saved and replayed on every refresh.
+
+## What an answer looks like
+
+> *"The scariest fundraising stories are the ones where the founder spends six months on an 'almost-yes' from an investor who eventually just ghosts."*
+>
+> — [Dalton & Michael: Fundraising Mistakes (2024-03-12), 14:22](https://youtube.com/watch?v=abc123&t=862)
+
+Each citation is a real line from a real video, anchored to the second. Click through and verify.
+
+## Limitations
+
+- **One channel per advisor.** Multi-channel rollups ("YC + Naval + a16z combined") are planned for v0.2.
+- **Whisper fallback is CPU-bound.** Videos without YT captions fall back to local Whisper — roughly 1 hour of compute per 1 hour of audio on Apple Silicon. The assistant warns you and asks before going that route.
+- **YouTube anti-bot.** Defaults (1–5s randomized sleep, exponential-backoff retries on 429) handle most cases. On persistent blocks the assistant will offer to use cookies from your logged-in browser.
+
+## Works with other AI tools
+
+`AGENTS.md` is a tool-agnostic mirror of `SKILL.md`. Wire it into whichever tool you use:
+
+| Your tool          | Where to point it                                                              | How to invoke                            |
+| ------------------ | ------------------------------------------------------------------------------ | ---------------------------------------- |
+| Claude Code        | clone into `~/.claude/skills/youtube-advisor/`                                 | `/youtube-advisor <request>`             |
+| OpenAI Codex CLI   | clone anywhere, place `AGENTS.md` at `~/.codex/AGENTS.md` (or project root)    | "build me an advisor on `<channel>`"     |
+| Cursor             | clone anywhere, copy `AGENTS.md` to `.cursor/rules/youtube-advisor.md`         | `@youtube-advisor` or natural language   |
+| Continue.dev       | clone anywhere, register `youtube-advisor` as a custom slash command           | `/youtube-advisor <request>`             |
+| Aider              | clone anywhere, `aider --read <install-dir>/AGENTS.md`                         | natural language in chat                 |
+| Goose (Block)      | clone anywhere, add as a shell-command extension                               | mention youtube-advisor in chat          |
+| No AI at all       | clone anywhere                                                                 | `youtube-advisor bootstrap --channel @… --out …` |
+
+<details>
+<summary><strong>Advanced — for CI and scripting</strong></summary>
+
+Everything below is for power users running outside an AI chat (CI, cron, scripts). **You almost never need this.**
+
+### Manual install
+
+```bash
+git clone https://github.com/AlexanderAbramovPav/youtube-advisor ~/.claude/skills/youtube-advisor
+cd ~/.claude/skills/youtube-advisor && bash scripts/install.sh
+```
+
+### CLI
+
+```bash
+# Bootstrap
+youtube-advisor bootstrap \
+  --channel @ycombinator \
+  --since 2022-01-01 \
+  --max 200 \
+  --title-include "Founder Stories|How to" \
+  --title-exclude "shorts|#shorts" \
+  --out ~/.claude/skills/yc-advisor \
+  --yes
+
+# Update (replays the saved selection filter)
+youtube-advisor update --advisor ~/.claude/skills/yc-advisor --yes
+
+# Update — override date, reindex only, or run regression evals
+youtube-advisor update --advisor ~/.claude/skills/yc-advisor --since 2026-01-01 --yes
+youtube-advisor update --advisor ~/.claude/skills/yc-advisor --reindex-only
+youtube-advisor update --advisor ~/.claude/skills/yc-advisor --run-evals --yes
+```
+
+`youtube-advisor bootstrap --help` and `youtube-advisor update --help` print the full flag list.
+
+### Bypassing YT anti-bot with browser cookies
+
+When unauthenticated channel-resolution gets 429-blocked, pass cookies from a logged-in browser. yt-dlp reads them straight from the browser profile — no copy-paste:
+
+```bash
+youtube-advisor bootstrap --channel @ycombinator --out ~/.claude/skills/yc-advisor \
+  --cookies-from-browser chrome --yes
+
+# Or a Netscape-format cookies.txt:
+youtube-advisor bootstrap --channel @ycombinator --out ~/.claude/skills/yc-advisor \
+  --cookies ~/secrets/yt-cookies.txt --yes
+```
+
+Resolution order: explicit flag → `YOUTUBE_ADVISOR_COOKIES_BROWSER` / `YOUTUBE_ADVISOR_COOKIES_FILE` env → `~/.config/youtube-advisor/cookies.txt` if present → none. With cookies set the captions pool stays at concurrency 8; without them it drops to 2 + per-call jitter so YT is less likely to block you.
+
+### Vendoring `_lib`
+
+`youtube-advisor bootstrap --vendor` copies the `youtube_advisor` Python package into the emitted advisor's `scripts/_lib/`. Useful if you want the advisor directory to be fully portable (pushed to a separate Git repo and cloned elsewhere without a Python install of `youtube-advisor`).
+
+### Eval-driven regression detection
+
+`youtube-advisor update --advisor <path> --run-evals` reruns the channel's generated benchmark after sync and prompts to roll back if pass rate dropped.
+
+</details>
+
+## License
+
+[MIT](./LICENSE) — © 2026 Alexander Abramov.
+
+Runtime dependencies (yt-dlp, youtube-transcript-api, fastembed, faster-whisper, rank-bm25, ffmpeg, scriba) are installed locally, not vendored. Their licenses are catalogued in [`THIRD_PARTY_LICENSES.md`](./THIRD_PARTY_LICENSES.md).
+
+## Acknowledgments
+
+This tool is glue around several excellent OSS projects:
+
+- [**yt-dlp**](https://github.com/yt-dlp/yt-dlp) — channel resolution, caption download, audio extraction.
+- [**youtube-transcript-api**](https://github.com/jdepoix/youtube-transcript-api) — Jonas Depoix — Tier 1 captions fetcher.
+- [**fastembed**](https://github.com/qdrant/fastembed) — Qdrant — local embedding inference with `bge-small-en-v1.5` (BAAI).
+- [**rank-bm25**](https://github.com/dorianbrown/rank_bm25) — Dorian Brown — BM25 ranking.
+- [**faster-whisper**](https://github.com/SYSTRAN/faster-whisper) — SYSTRAN — local ASR fallback.
+- [**scriba**](https://github.com/AlexanderAbramovPav/scriba) — sibling skill — alternative Whisper transcription backend.
+- [**uv**](https://github.com/astral-sh/uv) (Astral) for env setup, and [`ffmpeg`](https://ffmpeg.org/) for audio extraction.
+- Conceptual lineage: [yc-avisor](https://github.com/AlexanderAbramovPav/cowork) — the hand-rolled YC-channel-specific predecessor.