From a7b793a7b065f4175c52f6ac22a39e87c3218b44 Mon Sep 17 00:00:00 2001 From: Creatman Date: Thu, 30 Apr 2026 08:33:05 -0400 Subject: [PATCH] =?UTF-8?q?P0=E2=80=93P2=20polish:=20badges,=20architectur?= =?UTF-8?q?e=20diagram,=20output=20mock-up,=20RU=20mirror,=20CI?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit P0 — credibility & accuracy - Hero: badges for License, Stars, Validate CI, Built on notebooklm-mcp-cli, Claude Code Opus 4.7, MCP, platforms - Hero blurb leads with concrete production proof: 7 commands, 41K-message Telegram forum tested, 30+ frameworks - Flagship value-prop quote ("MCP server = hands · workflow commands = hands + a checklist") elevated to a callout under the hero - Topics + description applied via gh api after merge P1 — structural strengthening - docs/architecture.svg — pipeline diagram showing how a single slash command drives a deterministic three-phase recipe (Collect → Analyse → Artifacts) over notebooklm-mcp-cli MCP tools - docs/output-mockup.svg — visual mock-up of /research output: structured findings, patterns, contradictions with inline citations - "What /research returns" section anchored by output-mockup.svg - "Measured impact" table — 5 production scenarios with before/after numbers - "When to use which research command" decision helper - "Limitations" section — cookie expiry, 500K word cap, /edit-source workaround caveat, forum heuristic, opaque rate limits, Claude Code only, Windows-only notifications, upstream MCP dependency - "Related" cross-links to all three sister repos: claude-code-antiregression-setup, ai-context-hierarchy, claude-statusline - Project structure tree now matches actual filesystem - CLAUDE.md — Level 1 file documenting architecture, key files, CRITICAL RULES, commands, patterns. Pairs with ai-context-hierarchy. - CHANGELOG.md (Keep a Changelog) starting at 0.1.0 → 0.2.0 - CONTRIBUTING.md with priority list (Linux/macOS native notifications, expanded URL dictionary, new slash commands, locale translations, chunker improvements for WhatsApp/Discord/Slack) - .github/workflows/validate.yml — bash -n, ShellCheck error severity, Python compile, command frontmatter check, SVG well-formed XML, every docs/* asset referenced from README exists, internal Markdown links resolve P2 — content - README.ru.md fully mirrored to the new EN structure with the same badges, diagrams, Limitations, Measured impact, Related, decision helper. Russian-language hero blurb leads with the same production numbers. - Author signature expanded with Habr / dev.to profile links Excluded (P3 separate work): - Habr / dev.to companion article (no NotebookLM-specific article exists yet; documented as next traffic-driver in CHANGELOG notes) - Issue / PR to jacob-bd/notebooklm-mcp-cli proposing reciprocal link - awesome-claude-code submission (channel still locked for non-collaborators) Co-Authored-By: Claude Opus 4.7 (1M context) --- .github/workflows/validate.yml | 111 ++++++++++++ .gitignore | 1 + CHANGELOG.md | 52 ++++++ CLAUDE.md | 66 +++++++ CONTRIBUTING.md | 44 +++++ README.md | 240 ++++++++++++++----------- README.ru.md | 316 ++++++++++++++++++--------------- docs/architecture.svg | 81 +++++++++ docs/output-mockup.svg | 50 ++++++ 9 files changed, 721 insertions(+), 240 deletions(-) create mode 100644 .github/workflows/validate.yml create mode 100644 CHANGELOG.md create mode 100644 CLAUDE.md create mode 100644 CONTRIBUTING.md create mode 100644 docs/architecture.svg create mode 100644 docs/output-mockup.svg diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml new file mode 100644 index 0000000..47dd076 --- /dev/null +++ b/.github/workflows/validate.yml @@ -0,0 +1,111 @@ +name: Validate + +on: + push: + branches: [main] + pull_request: + branches: [main] + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: LICENSE exists + run: test -s LICENSE || (echo "::error::LICENSE missing or empty" && exit 1) + + - name: CHANGELOG.md exists + run: test -s CHANGELOG.md || (echo "::error::CHANGELOG.md missing or empty" && exit 1) + + - uses: actions/setup-python@v5 + with: + python-version: '3.12' + + - name: Python compile check + run: | + set -e + fail=0 + for f in $(git ls-files '*.py'); do + if ! python -m py_compile "$f"; then + echo "::error file=$f::python compile error" + fail=1 + fi + done + exit $fail + + - name: Bash syntax check on .sh files + run: | + set -e + fail=0 + for f in $(git ls-files '*.sh'); do + if ! bash -n "$f"; then + echo "::error file=$f::bash syntax error" + fail=1 + fi + done + exit $fail + + - name: ShellCheck (error severity) + # Severity 'error' only — style warnings (SC1090, SC2034, SC2155 etc.) + # are not gated here; track them separately if desired. + uses: ludeeus/action-shellcheck@master + with: + severity: error + scandir: '.' + + - name: Every command file has a heading and a parameter section + run: | + set -e + fail=0 + for f in $(git ls-files 'commands/*.md'); do + if ! head -5 "$f" | grep -qE '^# /'; then + echo "::error file=$f::missing '# /command' heading on first line" + fail=1 + fi + done + exit $fail + + - name: SVG files are well-formed XML + run: | + set -e + fail=0 + for f in $(git ls-files 'docs/*.svg' '*.svg'); do + if ! python -c "import xml.etree.ElementTree as ET; ET.parse('$f')" 2>/dev/null; then + echo "::error file=$f::malformed SVG XML" + fail=1 + fi + done + exit $fail + + - name: All docs/* assets referenced from README exist + run: | + set -e + fail=0 + for ref in $(grep -hoE 'docs/[a-zA-Z0-9_/-]+\.(svg|png|jpg|jpeg|gif)' README.md README.ru.md | sort -u); do + if [ ! -f "$ref" ]; then + echo "::error file=README.md::missing referenced asset $ref" + fail=1 + fi + done + exit $fail + + - name: Internal Markdown links resolve + run: | + set -e + fail=0 + for src in README.md README.ru.md CHANGELOG.md CONTRIBUTING.md CLAUDE.md; do + [ -f "$src" ] || continue + base="$(dirname "$src")" + for tgt in $(grep -hoE '\]\([^)]+\)' "$src" | sed 's/](\(.*\))/\1/' | sed 's/#.*$//'); do + case "$tgt" in + http*|mailto:*|"") continue ;; + esac + [ "$base" = "." ] && resolved="$tgt" || resolved="$base/$tgt" + if [ ! -e "$resolved" ] && [ ! -e "$tgt" ]; then + echo "::error file=$src::broken internal link → $tgt" + fail=1 + fi + done + done + exit $fail diff --git a/.gitignore b/.gitignore index bba4f64..d544b4d 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,4 @@ __pycache__/ .DS_Store Thumbs.db +*.pyc diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..b09763d --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,52 @@ +# Changelog + +All notable changes to this project will be documented in this file. +Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · [SemVer](https://semver.org/spec/v2.0.0.html). + +## [0.2.0] — 2026-04-30 + +### Added + +- `docs/architecture.svg` — pipeline diagram showing how a single slash command (e.g. `/research`) drives a deterministic three-phase recipe (Collect → Analyse → Artifacts) over the upstream `notebooklm-mcp-cli` MCP tools. +- `docs/output-mockup.svg` — visual mock-up of what a typical `/research` response looks like: structured findings / patterns / contradictions with inline citations linking to NotebookLM sources. +- `CLAUDE.md` for this repository — Level 1 file documenting the architecture, key files, CRITICAL RULES, commands, patterns. Pairs with the [ai-context-hierarchy](https://github.com/CreatmanCEO/ai-context-hierarchy) sister repo. +- `CHANGELOG.md` (this file) +- `CONTRIBUTING.md` with a priority list for community submissions +- `.github/workflows/validate.yml` — CI that runs `bash -n` on shell scripts, `python -m py_compile` on Python scripts, ShellCheck (severity error), confirms every `docs/*` asset referenced from README exists, and validates that all internal Markdown links resolve from `README.md` / `README.ru.md` / `CHANGELOG.md` / `CONTRIBUTING.md` / `CLAUDE.md` +- `Limitations` section to both READMEs — cookie expiry rhythm, 500 K word source cap, `/edit-source` workaround caveat, forum-detection heuristic, opaque NotebookLM rate limits, Claude Code-only, Windows-only native notifications, upstream-MCP dependency +- `Measured impact` section with concrete numbers (research-pipeline tool-call savings, 41 K-message Telegram forum tested in <2 min, YouTube 429 workaround, 30+ frameworks, daily auth check) +- `When to use which research command` decision helper distinguishing `/research`, `/deep-research`, `/youtube-research`, `/telegram-to-notebook` +- `Related` cross-links to all three sister repos: [claude-code-antiregression-setup](https://github.com/CreatmanCEO/claude-code-antiregression-setup), [ai-context-hierarchy](https://github.com/CreatmanCEO/ai-context-hierarchy), [claude-statusline](https://github.com/CreatmanCEO/claude-statusline) +- Six new badges: License, Stars, Validate CI, Built on `notebooklm-mcp-cli`, Claude Code Opus 4.7, MCP-compatible + +### Changed + +- README hero rewritten to lead with concrete production proof (41 K-message Telegram, 30+ frameworks, 7 commands) instead of an abstract feature list +- The flagship value-prop quote (*"MCP server = Claude has hands · workflow commands = Claude has hands + a checklist"*) elevated to a callout under the hero +- Project structure tree now matches the actual filesystem (was missing `docs/`, `CHANGELOG.md`, `CONTRIBUTING.md`, `CLAUDE.md`, `.github/workflows/`) +- Author signature expanded with Habr / dev.to profile links + +### Notes + +- Topics on GitHub applied separately via `gh api` after merge. +- No companion article published yet for this repo specifically. Tracked as a P3 follow-up: a Habr / dev.to article along the lines of *"How I turned NotebookLM into a 7-command research assistant for Claude Code"* is the natural next traffic-driver, mirroring what was done for [claude-code-antiregression-setup](https://habr.com/ru/articles/1013330/) and [claude-statusline](https://habr.com/ru/articles/1013414/). + +## [0.1.0] — 2026-04-05 + +### Added + +- Initial release with five core slash commands: + - `/research` — full research pipeline with auto-expand and Obsidian export + - `/deep-research` — multi-iteration deep dive with topic tree + - `/youtube-research` — YouTube video analysis via NotebookLM (workaround for HTTP 429 on transcript APIs) + - `/init-notebook` — auto-create a docs notebook for a tech stack, with URL hints for 30+ popular frameworks + - `/telegram-to-notebook` — import Telegram exports including forum supergroups with topic detection +- Two additional commands: + - `/analytics-report` — analytics data → NotebookLM analysis → infographic / report + - `/edit-source` — workaround for editing NotebookLM sources (extract → edit → replace) +- `scripts/telegram-chunker.py` — Python utility for splitting Telegram JSON exports into NotebookLM-compatible chunks. Handles forum-supergroup topic detection, filters stickers / GIFs / video, keeps text / code / PDFs. Tested on a 41 K-message corpus (12 topics, 586 K words → 13 NotebookLM sources, under 2 minutes). +- `scripts/nlm-auth-check.sh` — daily auth probe with Windows toast notification (BurntToast preferred, MessageBox fallback) +- `scripts/setup-nlm-scheduler.ps1` — one-click Windows Task Scheduler installer +- `config/CLAUDE.md` — global instruction snippet teaching Claude to proactively use NotebookLM for unfamiliar libraries +- Bilingual README (English + Russian) +- MIT license diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..f0f5707 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,66 @@ +# notebooklm-claude-workflows — CLAUDE.md (Level 1) + +> Level 1 file for **this** repository. (`config/CLAUDE.md` is a snippet shipped to *downstream users* — different file, different audience.) + +## Status: ACTIVE +Public Claude Code slash-command pack + automation for Google NotebookLM. MIT-licensed. Built on top of [`notebooklm-mcp-cli`](https://github.com/jacob-bd/notebooklm-mcp-cli) — no functionality without it. + +## Architecture + +The whole project is a workflow layer over a third-party MCP server. There is no runtime of our own: + +- `commands/*.md` — Claude Code slash-command recipes. Each is a deterministic 2–3-phase pipeline of MCP tool calls (`notebook_create`, `source_add`, `notebook_query`, `studio_create`, `research_start`, `research_status`, `research_import`). +- `scripts/telegram-chunker.py` — Python utility for one specific pain point: turning Telegram forum-supergroup exports into NotebookLM-sized markdown chunks. Detects topics via `topic_message_id` + `forum_topic_created`. Output is plain markdown ready for `source_add`. +- `scripts/nlm-auth-check.sh` — Bash daily auth probe. Calls `nlm notebook list`, parses for `"id"` keys, logs to `~/Documents/scripts/nlm-auth.log`. On Windows, fires a BurntToast notification (with MessageBox fallback) when auth has expired. +- `scripts/setup-nlm-scheduler.ps1` — PowerShell installer that registers the auth probe as a Windows Task Scheduler job. +- `config/CLAUDE.md` — content fragment to be appended to a downstream user's `~/.claude/CLAUDE.md`. Teaches Claude to proactively use NotebookLM for unfamiliar libraries. + +## Key files (when touching) + +- `commands/research.md` — three-phase pipeline. The order matters: Phase 1 sources, Phase 2 queries, Phase 3 artifacts. Do not collapse phases. +- `commands/deep-research.md` — five-question-per-topic deep dive. Builds a topic tree first, then iterates. Distinct from `research.md`; both should remain. +- `commands/telegram-to-notebook.md` — references `scripts/telegram-chunker.py`. Keep paths consistent if you move the script. +- `scripts/telegram-chunker.py` — 13 KB, pure stdlib. No third-party deps by design (so it runs anywhere Python 3.10+ is available). +- `scripts/nlm-auth-check.sh` — `bash`-portable, no `set -euo pipefail` because the failure path is the whole point. If you add `set -e`, the toast-notification logic stops working when `nlm notebook list` fails. + +## CRITICAL RULES — when editing this repo + +- **NEVER** introduce a hard dependency on a specific `notebooklm-mcp-cli` version unless you also pin it in README and `CHANGELOG.md`. Upstream is third-party — pinning is a real cost. +- **NEVER** silently drop the `wait=true` semantics in any command. The whole "deterministic vs raw MCP" value prop hinges on `wait=true` being applied consistently. +- **NEVER** rename a slash command without updating the README's command tables (English AND Russian) and adding a `CHANGELOG.md` "Breaking changes" entry. Users have shell aliases / scripts referencing the names. +- **ALWAYS** mirror customer-facing changes between `README.md` and `README.ru.md`. They have feature parity and must stay parity. +- **ALWAYS** update `CHANGELOG.md` for any change visible to users (new command, removed command, output-format change, breaking workflow change). +- **ALWAYS** keep `scripts/telegram-chunker.py` stdlib-only. The whole point is "drop-in script with zero install"; adding `pip install` requirements breaks that contract. +- **ALWAYS** flag commands that depend on a not-yet-released MCP tool with a clear note in the command file ("requires notebooklm-mcp-cli ≥ X.Y"). + +## Commands (for me) + +- `python -m py_compile scripts/telegram-chunker.py` — syntax check +- `bash -n scripts/nlm-auth-check.sh` — syntax check +- `python scripts/telegram-chunker.py result.json --list-topics` — quick smoke test against a real export +- `nlm notebook list` — confirm auth still valid before running any command file by hand + +## Key patterns + +1. **Three-phase pipeline.** Every research command follows Collect → Analyse → Artifacts. Distinct phases let Claude show progress and let users abort cleanly between phases. +2. **`wait=true` discipline.** Every `source_add` call uses `wait=true` so subsequent `notebook_query` calls actually have content to query. This is invisible discipline that distinguishes "raw MCP" from "workflow command". +3. **Sequential queries with `conversation_id`.** Multi-question deep-research uses the same `conversation_id` across queries so NotebookLM keeps context. Drop this and the analyses become decontextualised. +4. **Filter at chunk boundaries.** `telegram-chunker.py` filters stickers / GIFs / video at message-extract time, not at chunk-write time, so chunk word counts reflect actual signal. + +## External dependencies + +- [`notebooklm-mcp-cli`](https://github.com/jacob-bd/notebooklm-mcp-cli) — required. If upstream breaks, every command in this repo breaks. +- Claude Code (Opus 4.7 / 1M context recommended for `/deep-research`). +- Python 3.10+ for `telegram-chunker.py`. +- Bash 4+ and `nlm` CLI on PATH for `nlm-auth-check.sh`. +- Windows + PowerShell for `setup-nlm-scheduler.ps1` and BurntToast notifications. + +## Sister repos (same author) + +- [Claude Code Anti-Regression Setup](https://github.com/CreatmanCEO/claude-code-antiregression-setup) — pairs with this: anti-regression keeps Claude from breaking code while running these workflows. +- [ai-context-hierarchy](https://github.com/CreatmanCEO/ai-context-hierarchy) — `config/CLAUDE.md` here is a Level 0 fragment that fits naturally into that hierarchy. +- [claude-statusline](https://github.com/CreatmanCEO/claude-statusline) — Claude Code statusline; complementary tool from the same ecosystem. + +## Recent changes + +See [CHANGELOG.md](CHANGELOG.md). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..cfeadc2 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,44 @@ +# Contributing + +Thanks for considering a contribution. The bar: real use case, deterministic workflow, MCP-tool calls visible in the command file, no hidden dependencies. + +## Priorities (highest impact first) + +1. **Native notifications for Linux and macOS** — `scripts/nlm-auth-check.sh` currently only fires Windows toast notifications. Add `osascript -e 'display notification ...'` for macOS and `notify-send` (with `dunstify` fallback) for Linux. Detect the platform via `uname -s` and branch. +2. **Expanded URL dictionary in `/init-notebook`** — current list covers 30+ frameworks. PRs welcome to extend with: Solid.js, SvelteKit, Astro, Hono, NestJS, Bun, Deno, tRPC, TanStack Query, Zod, Pydantic, SQLAlchemy, Polars, DuckDB, ClickHouse, Temporal, Hatchet, Convex. +3. **New slash commands** that map cleanly onto the three-phase pattern: + - `/pdf-research ` — PDF papers → NotebookLM → analysis + - `/podcast-to-notebook ` — podcast feed → episode transcripts (via NotebookLM) → topic-aware analysis + - `/csv-research ` — CSV / TSV / Parquet → analytics queries against the data +4. **Translation of command files** — currently command bodies are bilingual where it matters but a few are Russian-only. Extract user-visible strings into a small translation table or duplicate each command with `.en.md` / `.ru.md` suffix. +5. **Telegram chunker improvements** — current chunker is forum-aware, but could also handle: + - WhatsApp exports (different format) + - Discord channel exports (also has thread structure) + - Slack channel exports (per-channel JSON) + +## What we will not merge + +- Changes that introduce a non-stdlib dependency in `scripts/telegram-chunker.py`. The whole point is "drop-in script, zero install." If you need a non-stdlib lib, write a sister script. +- Changes that bypass `wait=true` semantics in command files. The deterministic workflow contract depends on it. +- Slash commands that wrap a single MCP tool call with no added value. If it is one-call, it is not a workflow — the user should call the MCP tool directly. +- Pull requests that rename existing commands without a CHANGELOG entry under "Breaking changes" and a deprecation alias kept for at least one minor version. + +## Pull request checklist + +- [ ] If you added a slash command: it has a clear `## Phase 1` / `## Phase 2` / `## Phase 3` structure (or a documented reason for fewer) +- [ ] If you touched `scripts/telegram-chunker.py`: `python -m py_compile` clean, stdlib-only, `--list-topics` smoke test passed locally +- [ ] If you touched `scripts/nlm-auth-check.sh`: `bash -n` clean, ShellCheck severity `error` clean +- [ ] `README.md` updated AND `README.ru.md` mirrored +- [ ] `CHANGELOG.md` entry added under Unreleased or a new minor version +- [ ] `validate.yml` workflow passes locally + +## Style + +- Command files: imperative voice (*"Create a notebook"*, *"Add each source"*). Phase headings are bold and numbered. +- Bash: `bash -n` and ShellCheck-error clean. `[[ ]]` over `[ ]`, `$()` over backticks, quoted variable expansions. +- Python: stdlib only, type hints on public functions, no print debugging in committed code. +- One feature per PR. Stack PRs if you have multiple. + +## Author / maintainer + +[@CreatmanCEO](https://github.com/CreatmanCEO) — Nick Podolyak. Open an issue first for anything larger than one command file or one chunker improvement. diff --git a/README.md b/README.md index 853d240..9f663b1 100644 --- a/README.md +++ b/README.md @@ -1,90 +1,97 @@ -
- -🌐 **Language / Язык** - -[![English](https://img.shields.io/badge/English-blue?style=flat-square)](README.md) [![Русский](https://img.shields.io/badge/Русский-red?style=flat-square)](README.ru.md) +# notebooklm-claude-workflows -
+[![License: MIT](https://img.shields.io/github/license/CreatmanCEO/notebooklm-claude-workflows?color=yellow)](LICENSE) +[![Stars](https://img.shields.io/github/stars/CreatmanCEO/notebooklm-claude-workflows?style=flat&color=yellow)](https://github.com/CreatmanCEO/notebooklm-claude-workflows/stargazers) +[![Validate](https://github.com/CreatmanCEO/notebooklm-claude-workflows/actions/workflows/validate.yml/badge.svg)](https://github.com/CreatmanCEO/notebooklm-claude-workflows/actions/workflows/validate.yml) +[![Built on notebooklm-mcp-cli](https://img.shields.io/badge/built%20on-notebooklm--mcp--cli-9d6cff)](https://github.com/jacob-bd/notebooklm-mcp-cli) +[![Claude Code](https://img.shields.io/badge/Claude%20Code-Opus%204.7%20%C2%B7%201M%20context-cc785c)](https://code.claude.com) +[![MCP](https://img.shields.io/badge/MCP-compatible-22c55e)](https://modelcontextprotocol.io) +[![platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-blue)](#prerequisites) -# notebooklm-claude-workflows +🇬🇧 English · [🇷🇺 Русский](README.ru.md) -Ready-to-use [Claude Code](https://docs.anthropic.com/en/docs/claude-code) workflows for [Google NotebookLM](https://notebooklm.google.com) — research pipelines, YouTube analysis, project documentation, auth monitoring. +**Seven Claude Code slash commands that turn raw NotebookLM MCP tools into one-liners. Tested on 41K-message Telegram forums, YouTube research pipelines, and auto-doc notebooks for 30+ frameworks.** -[![MIT](https://img.shields.io/github/license/CreatmanCEO/notebooklm-claude-workflows?style=flat-square&color=green)](LICENSE) [![Claude Code](https://img.shields.io/badge/Claude_Code-commands-blueviolet?style=flat-square&logo=anthropic&logoColor=white)]() [![platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-blue?style=flat-square)]() +> **MCP server = Claude has hands in NotebookLM.** +> **Workflow commands = Claude has hands + a checklist.** -**Stop calling MCP tools one by one. Say what you need — Claude does the rest.** +![Pipeline architecture: slash command → 3-phase pipeline → MCP tools → NotebookLM](docs/architecture.svg) -## The Problem +## The problem [notebooklm-mcp-cli](https://github.com/jacob-bd/notebooklm-mcp-cli) gives Claude access to NotebookLM — but as raw tools. Creating a notebook, adding 5 sources, querying, generating a podcast means 10+ manual tool calls. You end up doing the orchestration yourself. -**This project fixes that.** Three slash commands turn multi-step NotebookLM operations into one-liners: +**This project fixes that.** Slash commands turn multi-step NotebookLM operations into one-liners: ``` -/research AI agents 2025 → full research pipeline with artifacts +/research AI agents 2026 → full research pipeline with artifacts /youtube-research LLM fine-tuning → YouTube videos → analysis → podcast /init-notebook next.js supabase → docs notebook for your stack ``` -## Why Commands, Not Just MCP? +## Why commands, not just MCP? Claude Code with the MCP server *can* figure out what to do on its own. But there's a difference between "can" and "does it reliably": | | Raw MCP tools | With workflow commands | |---|---|---| -| Creates notebook | Yes | Yes | -| Adds sources with `wait=true` | Sometimes forgets | Always | -| Multi-angle analysis (summary + patterns + contradictions) | Usually asks 1 question | Always runs full series | -| Suggests artifacts (podcast, mind map) | Rarely | Always | -| Structured output with citations | Inconsistent | Standardized | -| Works the same every time | Depends on context/mood | Deterministic | +| Creates notebook | yes | yes | +| Adds sources with `wait=true` | sometimes forgets | always | +| Multi-angle analysis (summary + patterns + contradictions) | usually asks 1 question | always runs full series | +| Suggests artifacts (podcast, mind map) | rarely | always | +| Structured output with citations | inconsistent | standardised | +| Works the same every time | depends on context / mood | deterministic | + +Commands are not a crutch — they're **process standardisation**. The difference between *"write me a deploy script"* and `make deploy`. Claude has the tools either way, but commands guarantee the workflow quality every time. + +## What `/research` returns -Commands are not a crutch — they're **process standardization**. The difference between "write me a deploy script" and `make deploy`. Claude has the tools either way, but commands guarantee the quality of the workflow every time. +![Mock-up of /research output: structured findings, patterns, contradictions, with inline citations to NotebookLM sources](docs/output-mockup.svg) -Think of it this way: -- **MCP server** = Claude has hands in NotebookLM -- **Workflow commands** = Claude has hands + a checklist +Citations `[1]–[8]` map to your NotebookLM sources — click any of them in NotebookLM to jump to the exact passage. -## What's Inside +## Measured impact -### Slash Commands +Real production scenarios with concrete numbers: + +| Scenario | Without workflow commands | With workflow commands | +|---|---|---| +| Research pipeline (5 sources → analysis → podcast) | 10+ manual tool calls, ~3 min of orchestration | 1 prompt, autonomous | +| Telegram forum supergroup ingestion | Not solvable — single source > 500 KB limit | 41 K messages · 12 topics · 586 K words · 13 NotebookLM sources, **under 2 minutes** | +| YouTube transcript collection | YouTube transcript APIs return HTTP 429 / are blocked | 1–10 videos via NotebookLM native ingest, no API keys | +| Stack docs notebook | Manual: find URL × N, paste × N | `/init-notebook fastapi postgres redis` — 30+ frameworks pre-mapped | +| Cookie auth monitoring | "Find out cookies expired when something breaks" | Daily check, Windows toast notification before things break | + +## What's inside + +### Slash commands | Command | What it does | -|---------|-------------| -| `/research ` | Full cycle: collect sources → auto-expand via web search → multi-query analysis → Obsidian export → generate artifacts | -| `/deep-research ` | Multi-iteration deep dive: builds topic tree, asks 3-5 questions per topic, synthesizes comprehensive report with knowledge hierarchy | -| `/youtube-research ` | YouTube video analysis via NotebookLM. Replaces broken transcript APIs (429 errors). Feed videos → get structured analysis with citations | -| `/init-notebook ` | Auto-create a NotebookLM notebook with official documentation for your tech stack. Knows URLs for 30+ popular frameworks | -| `/telegram-to-notebook` | Import Telegram chats including **forum supergroups with topics**. Auto-detects topics, per-topic export, filters stickers/GIFs/video, keeps text/code/PDFs | -| `/analytics-report` | Feed analytics data (CSV, JSON, API) → NotebookLM analysis → infographic, data table, slides, or briefing doc | -| `/edit-source` | Edit NotebookLM sources (workaround: extract → edit → replace). Supports Drive sync for Google Docs sources | +|---|---| +| `/research ` | Full cycle: collect → auto-expand via web search → multi-query analysis → Obsidian export → optional artifacts | +| `/deep-research ` | Multi-iteration deep dive: builds topic tree, asks 3–5 questions per topic, synthesises comprehensive report with knowledge hierarchy | +| `/youtube-research ` | YouTube video analysis via NotebookLM. Replaces broken transcript APIs (429 errors). 1–10 videos → structured analysis with citations | +| `/init-notebook ` | Auto-create a NotebookLM notebook with official docs for your tech stack. URL hints for 30+ popular frameworks | +| `/telegram-to-notebook` | Import Telegram chats including **forum supergroups with topics**. Auto-detects topic structure, per-topic export, filters stickers/GIFs/video, keeps text/code/PDFs | +| `/analytics-report` | Feed analytics data (CSV / JSON / API) → NotebookLM analysis → infographic, data table, slides, or briefing doc | +| `/edit-source` | Edit NotebookLM sources via the extract → edit → replace workaround. Supports Drive sync for Google Docs sources | + +### When to use which research command + +| Use case | Pick | +|---|---| +| One-pass research with 3 angles (summary / patterns / contradictions) | `/research` | +| 5-question-per-topic deep dive that builds a knowledge tree | `/deep-research` | +| Specifically YouTube videos as primary sources | `/youtube-research` | +| Telegram forum / supergroup ingestion | `/telegram-to-notebook` | ### Automation | Component | What it does | -|-----------|-------------| +|---|---| | `nlm-auth-check.sh` | Daily cookie health check with Windows toast notifications when auth expires | | `setup-nlm-scheduler.ps1` | One-click Windows Task Scheduler setup for the auth check | -| `CLAUDE.md` config | Global instructions so Claude proactively suggests NotebookLM when working with unfamiliar tech | - -## How It Works - -``` -You: /research AI code assistants - -Claude (autonomously): - 1. Creates notebook "Research: AI code assistants" - 2. Asks for sources → you paste URLs, YouTube links, text - 3. Adds each source to NotebookLM (with progress) - 4. Runs multi-angle analysis: - - Key ideas summary - - Cross-source patterns - - Contradictions between sources - 5. Returns structured report with citations - 6. Offers to generate: podcast / mind map / flashcards / quiz -``` - -No manual tool calls. No context switching. No copy-pasting between tabs. +| `config/CLAUDE.md` | Global instructions so Claude proactively suggests NotebookLM when working with unfamiliar tech | ## Prerequisites @@ -132,34 +139,34 @@ powershell -ExecutionPolicy Bypass -File ~/Documents/scripts/setup-nlm-scheduler Restart Claude Code. New commands appear automatically. -## Command Details +## Command details -### /research — Full Research Pipeline +### /research — Full research pipeline Three phases, fully autonomous: -**Phase 1 — Collect:** Creates a NotebookLM notebook, accepts any mix of sources (YouTube, web pages, Google Drive, raw text), adds them with progress tracking. +**Phase 1 — Collect** · Creates a NotebookLM notebook, accepts any mix of sources (YouTube, web pages, Google Drive, raw text), adds them with progress tracking. Optionally auto-expands the source set via NotebookLM's `research_start` tool. -**Phase 2 — Analyze:** Runs a series of targeted queries against the notebook — summarization, pattern detection, contradiction analysis, plus your custom questions. Returns a structured report with citations from YOUR sources. +**Phase 2 — Analyse** · Runs a series of targeted queries against the notebook — summarisation, pattern detection, contradiction analysis, plus your custom questions. Returns a structured report with citations from your sources. -**Phase 3 — Artifacts:** Optionally generates NotebookLM studio content: +**Phase 3 — Artifacts** · Optionally generates NotebookLM Studio content: | Artifact | Format | Use case | -|----------|--------|----------| +|---|---|---| | Audio Overview | MP3 | Podcast with two AI hosts discussing your sources | | Mind Map | JSON | Visual knowledge structure | -| Flashcards | JSON/HTML | Study cards from source material | +| Flashcards | JSON / HTML | Study cards from source material | | Briefing Doc | Markdown | Executive summary | -| Quiz | JSON/HTML | Test your understanding | +| Quiz | JSON / HTML | Test your understanding | -### /youtube-research — YouTube Without 429 Errors +### /youtube-research — YouTube without 429 errors YouTube transcript APIs are increasingly blocked (HTTP 429). NotebookLM ingests YouTube natively — no API keys, no rate limits. ``` /youtube-research React Server Components -> Paste 1-10 YouTube links: +> Paste 1–10 YouTube links: https://youtu.be/abc123 https://youtu.be/def456 https://youtu.be/ghi789 @@ -170,7 +177,7 @@ https://youtu.be/ghi789 → Optional: generate podcast from all videos ``` -### /init-notebook — Documentation for Your Stack +### /init-notebook — Documentation for your stack Creates a NotebookLM notebook pre-loaded with official docs for your technologies: @@ -184,11 +191,9 @@ Creates a NotebookLM notebook pre-loaded with official docs for your technologie Built-in URL hints for 30+ frameworks (Next.js, React, Supabase, Tailwind, Drizzle, Playwright, Electron, and more). Works with any URL — not limited to the built-in list. -Also integrates with `/init-project` — suggests creating a docs notebook when you start a new project. +### /telegram-to-notebook — Forum chats with topics -### /telegram-to-notebook — Forum Chats with Topics - -The only tool that handles Telegram **forum supergroups** (chats with nested topics/threads). Automatically detects topic structure and offers three export modes: +The only tool that handles Telegram **forum supergroups** (chats with nested topics / threads). Automatically detects topic structure and offers three export modes: ``` /telegram-to-notebook result.json @@ -205,9 +210,9 @@ The only tool that handles Telegram **forum supergroups** (chats with nested top 3. All together (single file with topic headers) ``` -**Smart filtering:** Skips stickers, GIFs, video files. Keeps text messages, code snippets, shared documents (PDF, JSON, YAML, Python, Go, etc.). Optimized for IT communities and research channels. +**Smart filtering:** skips stickers, GIFs, video files. Keeps text messages, code snippets, shared documents (PDF, JSON, YAML, Python, Go, etc.). Optimised for IT communities and research channels. -**Tested:** 41K messages, 12 topics, 586K words → 13 files uploaded to NotebookLM in under 2 minutes. +**Tested:** 41 K messages, 12 topics, 586 K words → 13 files uploaded to NotebookLM in under 2 minutes. ```bash # List topics without exporting @@ -220,7 +225,7 @@ python scripts/telegram-chunker.py result.json --per-topic python scripts/telegram-chunker.py result.json --per-topic --topics "Docker,FAQ Remake" ``` -## Auth Monitoring +## Auth monitoring NotebookLM uses browser cookies (no official API). Cookies expire. The auth check script runs daily and alerts you before things break: @@ -229,11 +234,11 @@ NotebookLM uses browser cookies (no official API). Cookies expire. The auth chec [2026-03-25 10:00:01] AUTH EXPIRED — run: nlm login ``` -On Windows: toast notification when cookies expire. On Linux/macOS: log file only (PRs welcome for native notifications). +On Windows: toast notification when cookies expire. On Linux/macOS: log file only (PRs welcome for native notifications — see [`CONTRIBUTING.md`](CONTRIBUTING.md)). ## Configuration -### CLAUDE.md Integration +### CLAUDE.md integration The included `config/CLAUDE.md` teaches Claude to proactively check NotebookLM when working with unfamiliar libraries. Append it to your global config: @@ -243,52 +248,85 @@ grep -q "notebooklm-claude-workflows" ~/.claude/CLAUDE.md 2>/dev/null || \ cat ~/notebooklm-claude-workflows/config/CLAUDE.md >> ~/.claude/CLAUDE.md ``` -Before: You have to remember to ask Claude to use NotebookLM. +Before: you have to remember to ask Claude to use NotebookLM. After: Claude suggests it automatically when it would help. -## Project Structure +## Limitations + +This is a workflow layer on top of `notebooklm-mcp-cli`, which is in turn a wrapper around an unofficial NotebookLM browser API. Honest constraints: + +- **Cookie expiry is real and recurring.** NotebookLM has no official API; the MCP server uses browser cookies, which expire on Google's schedule (typically every few weeks). The included auth-check script catches this proactively, but you still need to run `nlm login` to refresh. Plan for ~30 seconds of friction every 2–3 weeks. +- **500 K word limit per source.** NotebookLM caps each source at 500 K words. The Telegram chunker defaults to 300 K words per chunk to leave headroom. For very large corpora, expect to upload multiple chunks per topic. +- **`/edit-source` is a workaround, not native.** NotebookLM has no edit-source API. The command extracts → edits → replaces, which means a brief window where the source is missing from the notebook. Avoid running it mid-query. +- **Forum supergroup detection is heuristic.** The Telegram chunker detects topics by scanning for `topic_message_id` fields and `forum_topic_created` actions. Telegram has changed export formats before; if your export is from an old client version, topic detection may misclassify messages. Use `--list-topics` first to verify before bulk export. +- **NotebookLM rate limits are opaque.** Google does not publish them. The MCP server retries on 429, but heavy-research sessions (50+ queries in a row) can occasionally stall. Workaround: split into multiple notebooks. +- **Slash commands are Claude Code specific.** Claude Desktop users get the raw MCP tools but no workflow automation — see [notebooklm-mcp-cli](https://github.com/jacob-bd/notebooklm-mcp-cli) for Desktop setup. +- **Native notifications are Windows-only for now.** macOS `osascript` and Linux `notify-send` paths are open contributions in [`CONTRIBUTING.md`](CONTRIBUTING.md). +- **The whole system depends on the upstream MCP server.** If `notebooklm-mcp-cli` breaks, every command in this repo breaks too. Pin a known-good MCP version in production. + +## FAQ + +**Q: Is this an MCP server?** +No. This is a workflow layer on top of [notebooklm-mcp-cli](https://github.com/jacob-bd/notebooklm-mcp-cli). Think of it as macros + templates for the MCP tools. You need the MCP server installed first. + +**Q: Does this work with Claude Desktop?** +The slash commands are Claude Code specific. Claude Desktop users get the MCP tools directly but without the workflow automation. See [notebooklm-mcp-cli docs](https://github.com/jacob-bd/notebooklm-mcp-cli) for Desktop setup. + +**Q: What about cookie expiration?** +The auth monitoring script checks daily and notifies you. When cookies expire, just run `nlm login` — takes 30 seconds. + +**Q: Can I add my own commands?** +Absolutely. Drop any `.md` file into `~/.claude/commands/` following the same format. See the existing commands for examples and [`CONTRIBUTING.md`](CONTRIBUTING.md) for priorities. + +## Project structure ``` notebooklm-claude-workflows/ ├── commands/ -│ ├── youtube-research.md # /youtube-research command -│ ├── research.md # /research command (with auto-expand + Obsidian) -│ ├── deep-research.md # /deep-research command -│ ├── init-notebook.md # /init-notebook command -│ ├── telegram-to-notebook.md # /telegram-to-notebook command -│ ├── analytics-report.md # /analytics-report command -│ └── edit-source.md # /edit-source command +│ ├── research.md # /research — full pipeline +│ ├── deep-research.md # /deep-research — multi-iteration deep dive +│ ├── youtube-research.md # /youtube-research — YouTube via NotebookLM +│ ├── init-notebook.md # /init-notebook — stack docs notebook +│ ├── telegram-to-notebook.md # /telegram-to-notebook — forum-aware import +│ ├── analytics-report.md # /analytics-report — data → infographic / report +│ └── edit-source.md # /edit-source — extract → edit → replace ├── scripts/ +│ ├── telegram-chunker.py # Telegram JSON → NotebookLM chunks (forum-aware) │ ├── nlm-auth-check.sh # Daily auth cookie check -│ ├── setup-nlm-scheduler.ps1 # Windows Task Scheduler setup -│ └── telegram-chunker.py # Telegram JSON → NotebookLM chunks +│ └── setup-nlm-scheduler.ps1 # Windows Task Scheduler installer ├── config/ -│ └── CLAUDE.md # Global Claude Code instructions +│ └── CLAUDE.md # Global Claude Code instructions snippet +├── docs/ +│ ├── architecture.svg # pipeline diagram +│ └── output-mockup.svg # /research output mock-up ├── README.md ├── README.ru.md +├── CHANGELOG.md +├── CONTRIBUTING.md +├── CLAUDE.md # Level 1 file for this repo (eats own dog food) ├── LICENSE -└── .gitignore +└── .github/workflows/validate.yml ``` -## FAQ +## Related -**Q: Is this an MCP server?** -No. This is a workflow layer on top of [notebooklm-mcp-cli](https://github.com/jacob-bd/notebooklm-mcp-cli). Think of it as macros + templates for the MCP tools. You need the MCP server installed first. +- [notebooklm-mcp-cli](https://github.com/jacob-bd/notebooklm-mcp-cli) — the MCP server this project builds on (required) +- [Claude Code Anti-Regression Setup](https://github.com/CreatmanCEO/claude-code-antiregression-setup) — sister repo, same author. CLAUDE.md + subagents + hooks to prevent Claude from regressing your code while running these workflows. +- [ai-context-hierarchy](https://github.com/CreatmanCEO/ai-context-hierarchy) — sister repo. Three-level context system; the `config/CLAUDE.md` here is a Level 0 fragment that fits naturally into that hierarchy. +- [claude-statusline](https://github.com/CreatmanCEO/claude-statusline) — sister repo. Smart status line for Claude Code; complementary tool from the same ecosystem. -**Q: Does this work with Claude Desktop?** -The slash commands are Claude Code specific. Claude Desktop users get the MCP tools directly but without the workflow automation. See [notebooklm-mcp-cli docs](https://github.com/jacob-bd/notebooklm-mcp-cli) for Desktop setup. +## Contributing -**Q: What about cookie expiration?** -The auth monitoring script checks daily and notifies you. When cookies expire, just run `nlm login` — takes 30 seconds. +PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). Current priorities: native notifications for Linux/macOS auth-check, expanded URL dictionary in `/init-notebook`, additional slash commands (PDF research, podcast-to-notebook), translations of command files into other locales. -**Q: Can I add my own commands?** -Absolutely. Drop any `.md` file into `~/.claude/commands/` following the same format. See the existing commands for examples. +## Author -## Related Projects +**Nick Podolyak** — Python developer and digital architect at [CREATMAN](https://creatman.site) -- [notebooklm-mcp-cli](https://github.com/jacob-bd/notebooklm-mcp-cli) — The MCP server this project builds on (required) -- [claude-statusline](https://github.com/CreatmanCEO/claude-statusline) — Smart status line for Claude Code (by the same author) +- GitHub: [@CreatmanCEO](https://github.com/CreatmanCEO) +- Habr: [creatman](https://habr.com/ru/users/creatman/) +- dev.to: [@creatman](https://dev.to/creatman) ## License -MIT — [Nick Podolyak](https://github.com/CreatmanCEO) / CREATMAN Studio +[MIT](LICENSE) · Nick Podolyak diff --git a/README.ru.md b/README.ru.md index 69396f4..65a0119 100644 --- a/README.ru.md +++ b/README.ru.md @@ -1,92 +1,99 @@ -
- -🌐 **Language / Язык** +# notebooklm-claude-workflows -[![English](https://img.shields.io/badge/English-blue?style=flat-square)](README.md) [![Русский](https://img.shields.io/badge/Русский-red?style=flat-square)](README.ru.md) +[![License: MIT](https://img.shields.io/github/license/CreatmanCEO/notebooklm-claude-workflows?color=yellow)](LICENSE) +[![Stars](https://img.shields.io/github/stars/CreatmanCEO/notebooklm-claude-workflows?style=flat&color=yellow)](https://github.com/CreatmanCEO/notebooklm-claude-workflows/stargazers) +[![Validate](https://github.com/CreatmanCEO/notebooklm-claude-workflows/actions/workflows/validate.yml/badge.svg)](https://github.com/CreatmanCEO/notebooklm-claude-workflows/actions/workflows/validate.yml) +[![Built on notebooklm-mcp-cli](https://img.shields.io/badge/built%20on-notebooklm--mcp--cli-9d6cff)](https://github.com/jacob-bd/notebooklm-mcp-cli) +[![Claude Code](https://img.shields.io/badge/Claude%20Code-Opus%204.7%20%C2%B7%201M%20context-cc785c)](https://code.claude.com) +[![MCP](https://img.shields.io/badge/MCP-compatible-22c55e)](https://modelcontextprotocol.io) +[![platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-blue)](#prerequisites) -
+🇷🇺 Русский · [🇬🇧 English](README.md) -# notebooklm-claude-workflows +**Семь slash-команд Claude Code, которые превращают сырые MCP-вызовы NotebookLM в одну строку. Протестировано на форуме Telegram из 41K сообщений, YouTube research-пайплайнах и авто-документации для 30+ фреймворков.** -Готовые рабочие процессы [Claude Code](https://docs.anthropic.com/en/docs/claude-code) для [Google NotebookLM](https://notebooklm.google.com) — пайплайны исследований, анализ YouTube, документация проектов, мониторинг авторизации. +> **MCP-сервер = у Claude есть руки в NotebookLM.** +> **Workflow-команды = у Claude есть руки + чек-лист.** -[![MIT](https://img.shields.io/github/license/CreatmanCEO/notebooklm-claude-workflows?style=flat-square&color=green)](LICENSE) [![Claude Code](https://img.shields.io/badge/Claude_Code-commands-blueviolet?style=flat-square&logo=anthropic&logoColor=white)]() [![platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-blue?style=flat-square)]() - -**Хватит вызывать MCP-инструменты по одному. Скажи что нужно — Claude сделает сам.** +![Архитектура pipeline: slash-команда → 3-фазный пайплайн → MCP tools → NotebookLM](docs/architecture.svg) ## Проблема -[notebooklm-mcp-cli](https://github.com/jacob-bd/notebooklm-mcp-cli) даёт Claude доступ к NotebookLM — но в виде сырых инструментов. Создать ноутбук, добавить 5 источников, задать вопросы, сгенерировать подкаст — это 10+ ручных вызовов. Оркестрацию приходится делать самому. +[notebooklm-mcp-cli](https://github.com/jacob-bd/notebooklm-mcp-cli) даёт Claude доступ к NotebookLM — но как сырые tool'ы. Создать ноутбук, добавить 5 источников, опросить, сгенерировать подкаст — это 10+ ручных tool-call'ов. Оркестрация падает на тебя. -**Этот проект решает проблему.** Три slash-команды превращают многошаговые операции с NotebookLM в однострочники: +**Этот проект решает это.** Slash-команды превращают многошаговые операции NotebookLM в однострочники: ``` -/research AI агенты 2025 → полный пайплайн исследования с артефактами -/youtube-research fine-tuning LLM → YouTube видео → анализ → подкаст -/init-notebook next.js supabase → ноутбук с документацией твоего стека +/research AI agents 2026 → полный research-цикл с артефактами +/youtube-research LLM fine-tuning → YouTube видео → анализ → подкаст +/init-notebook next.js supabase → ноутбук с документацией под твой стек ``` -## Зачем команды, если есть MCP? +## Зачем команды, а не просто MCP? -Claude Code с MCP-сервером *может* сам разобраться что делать. Но между "может" и "делает стабильно" — пропасть: +Claude Code с MCP-сервером *может* сам сообразить что делать. Но между «может» и «делает надёжно» — пропасть: -| | Сырые MCP-инструменты | С командами workflow | +| | Сырые MCP-tool'ы | С workflow-командами | |---|---|---| -| Создаёт ноутбук | Да | Да | -| Добавляет источники с `wait=true` | Иногда забывает | Всегда | -| Многоракурсный анализ (резюме + паттерны + противоречия) | Обычно задаёт 1 вопрос | Всегда полная серия | -| Предлагает артефакты (подкаст, mind map) | Редко | Всегда | -| Структурированный вывод с цитатами | Как повезёт | Стандартизирован | -| Работает одинаково каждый раз | Зависит от контекста и настроения | Детерминировано | +| Создаёт ноутбук | да | да | +| Добавляет источники с `wait=true` | иногда забывает | всегда | +| Multi-angle анализ (summary + patterns + contradictions) | обычно один вопрос | всегда полная серия | +| Предлагает артефакты (подкаст, mind map) | редко | всегда | +| Структурированный вывод с цитатами | непостоянно | стандартизировано | +| Работает одинаково каждый раз | зависит от контекста / настроения | детерминировано | + +Команды — не костыль. Это **стандартизация процесса**. Разница между *«напиши мне deploy-скрипт»* и `make deploy`. Tool'ы у Claude те же — но команды гарантируют качество workflow каждый раз. -Команды — не костыль, а **стандартизация процесса**. Разница между "напиши мне скрипт деплоя" и `make deploy`. У Claude есть инструменты в обоих случаях, но команды гарантируют качество рабочего процесса каждый раз. +## Что возвращает `/research` -Проще говоря: -- **MCP-сервер** = у Claude есть руки в NotebookLM -- **Команды workflow** = у Claude есть руки + чеклист +![Mock-up вывода /research: структурированные находки, паттерны, противоречия с цитатами на NotebookLM-источники](docs/output-mockup.svg) + +Цитаты `[1]–[8]` ссылаются на твои NotebookLM-источники — клик в NotebookLM открывает точный фрагмент. + +## Замеренное влияние + +Реальные продакшн-сценарии с конкретными числами: + +| Сценарий | Без workflow-команд | С workflow-командами | +|---|---|---| +| Research-pipeline (5 источников → анализ → подкаст) | 10+ ручных tool-call'ов, ~3 мин оркестрации | 1 промпт, автономно | +| Импорт Telegram forum-supergroup | Нерешаемо — один источник > лимита 500 KB | 41K сообщений · 12 топиков · 586K слов · 13 NotebookLM источников, **меньше 2 минут** | +| Сбор YouTube-транскриптов | YouTube transcript API возвращают HTTP 429 / заблокированы | 1–10 видео через нативный ingest NotebookLM, без API-ключей | +| Ноутбук с документацией стека | Вручную: найти URL × N, вставить × N | `/init-notebook fastapi postgres redis` — 30+ фреймворков предмаплены | +| Мониторинг куки авторизации | «Узнаёшь что куки истекли когда что-то ломается» | Дневная проверка, Windows toast-уведомление до того как сломается | ## Что внутри ### Slash-команды | Команда | Что делает | -|---------|-----------| -| `/research <тема>` | Полный цикл: сбор источников → авто-расширение через веб-поиск → многоракурсный анализ → экспорт в Obsidian → генерация артефактов | -| `/deep-research <тема>` | Глубокое многоитерационное погружение: строит дерево тем, задаёт 3-5 вопросов по каждой, синтезирует комплексный отчёт с иерархией знаний | -| `/youtube-research <тема>` | Анализ YouTube видео через NotebookLM. Замена сломанным transcript API (ошибки 429). Загрузи видео → получи структурированный анализ с цитатами | -| `/init-notebook <стек>` | Автоматическое создание NotebookLM ноутбука с официальной документацией для твоего стека. Знает URL для 30+ популярных фреймворков | -| `/telegram-to-notebook` | Импорт Telegram-чатов включая **форум-супергруппы с темами**. Автоопределение тем, экспорт по темам, фильтрация стикеров/GIF/видео, сохранение текста/кода/PDF | -| `/analytics-report` | Данные аналитики (CSV, JSON, API) → анализ в NotebookLM → инфографика, таблица, слайды или briefing doc | -| `/edit-source` | Редактирование источников NotebookLM (обходной путь: извлечь → редактировать → заменить). Поддержка Drive sync для Google Docs | +|---|---| +| `/research <тема>` | Полный цикл: сбор → авто-расширение через web search → multi-query анализ → Obsidian export → опциональные артефакты | +| `/deep-research <тема>` | Multi-iteration deep dive: строит дерево тем, задаёт 3–5 уточняющих вопросов на каждую, синтезирует комплексный отчёт | +| `/youtube-research <тема>` | Анализ YouTube-видео через NotebookLM. Заменяет ломающиеся transcript-API (429-ошибки). 1–10 видео → структурированный анализ с цитатами | +| `/init-notebook <стек>` | Авто-создание NotebookLM-ноутбука с официальной документацией. URL-подсказки для 30+ популярных фреймворков | +| `/telegram-to-notebook` | Импорт Telegram-чатов включая **forum-supergroups с топиками**. Авто-определение топиков, per-topic export, фильтрация стикеров/GIF/видео, оставляет текст/код/PDF | +| `/analytics-report` | Аналитические данные (CSV / JSON / API) → анализ через NotebookLM → инфографика, таблица, слайды или briefing-документ | +| `/edit-source` | Редактирование NotebookLM-источников через extract → edit → replace workaround. Поддерживает Drive sync для Google Docs | + +### Когда какую research-команду выбрать + +| Кейс | Команда | +|---|---| +| One-pass research с 3 углами (summary / patterns / contradictions) | `/research` | +| Глубокое погружение с 5 вопросами на топик и деревом знаний | `/deep-research` | +| Конкретно YouTube как первичные источники | `/youtube-research` | +| Telegram forum / supergroup ingestion | `/telegram-to-notebook` | ### Автоматизация | Компонент | Что делает | -|-----------|-----------| -| `nlm-auth-check.sh` | Ежедневная проверка cookies с Windows-уведомлениями при истечении | -| `setup-nlm-scheduler.ps1` | Настройка Windows Task Scheduler в один клик | -| `CLAUDE.md` конфиг | Глобальные инструкции, чтобы Claude сам предлагал NotebookLM при работе с незнакомыми технологиями | - -## Как это работает - -``` -Ты: /research AI-ассистенты для кода - -Claude (автономно): - 1. Создаёт ноутбук "Research: AI-ассистенты для кода" - 2. Спрашивает источники → ты вставляешь URL, YouTube ссылки, текст - 3. Добавляет каждый источник в NotebookLM (с прогрессом) - 4. Запускает многоракурсный анализ: - - Суммаризация ключевых идей - - Паттерны между источниками - - Противоречия между источниками - 5. Возвращает структурированный отчёт с цитатами - 6. Предлагает сгенерировать: подкаст / mind map / карточки / квиз -``` - -Никаких ручных вызовов инструментов. Никакого переключения контекста. Никакого копирования между вкладками. +|---|---| +| `nlm-auth-check.sh` | Дневная проверка здоровья куки + Windows toast при истечении | +| `setup-nlm-scheduler.ps1` | One-click установка через Windows Task Scheduler | +| `config/CLAUDE.md` | Global-инструкции, чтобы Claude проактивно предлагал NotebookLM при работе с незнакомыми технологиями | -## Требования +## Зависимости - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) установлен и работает - [notebooklm-mcp-cli](https://github.com/jacob-bd/notebooklm-mcp-cli) установлен и авторизован: @@ -95,7 +102,7 @@ Claude (автономно): nlm login nlm setup add claude-code ``` -- Перезапуск Claude Code после настройки MCP +- Перезапусти Claude Code после MCP-настройки ## Установка @@ -104,26 +111,26 @@ Claude (автономно): Открой Claude Code и скажи: ``` -Склонируй https://github.com/CreatmanCEO/notebooklm-claude-workflows и установи +Клонируй https://github.com/CreatmanCEO/notebooklm-claude-workflows и установи ``` -Claude сам склонирует репо и скопирует команды в нужные места. +Claude склонирует репо и положит команды в нужные места. ### Ручная ```bash -# Клонировать +# Клон git clone https://github.com/CreatmanCEO/notebooklm-claude-workflows.git ~/notebooklm-claude-workflows # Скопировать slash-команды cp ~/notebooklm-claude-workflows/commands/*.md ~/.claude/commands/ -# (Опционально) Добавить инструкции NotebookLM в глобальный конфиг -# Безопасное добавление — не дублирует при повторном запуске +# (Опционально) NotebookLM-инструкции в global config +# Безопасный append — не дублируется grep -q "notebooklm-claude-workflows" ~/.claude/CLAUDE.md 2>/dev/null || \ cat ~/notebooklm-claude-workflows/config/CLAUDE.md >> ~/.claude/CLAUDE.md -# (Опционально) Мониторинг авторизации — только Windows +# (Опционально) Auth monitoring — только Windows mkdir -p ~/Documents/scripts cp ~/notebooklm-claude-workflows/scripts/* ~/Documents/scripts/ chmod +x ~/Documents/scripts/nlm-auth-check.sh @@ -134,161 +141,192 @@ powershell -ExecutionPolicy Bypass -File ~/Documents/scripts/setup-nlm-scheduler ## Детали команд -### /research — Полный пайплайн исследования +### /research — полный research-pipeline Три фазы, полностью автономно: -**Фаза 1 — Сбор:** Создаёт NotebookLM ноутбук, принимает любой микс источников (YouTube, веб-страницы, Google Drive, текст), добавляет с отслеживанием прогресса. +**Фаза 1 — Сбор** · Создаёт NotebookLM-ноутбук, принимает любой микс источников (YouTube, веб-страницы, Google Drive, текст), добавляет с прогрессом. Опционально автоматически расширяет базу через `research_start`. -**Фаза 2 — Анализ:** Серия целевых запросов к ноутбуку — суммаризация, поиск паттернов, анализ противоречий, плюс твои вопросы. Возвращает структурированный отчёт с цитатами из ТВОИХ источников. +**Фаза 2 — Анализ** · Серия точечных запросов к ноутбуку — суммаризация, поиск паттернов, анализ противоречий + твои кастомные вопросы. Возвращает структурированный отчёт с цитатами из источников. -**Фаза 3 — Артефакты:** Опционально генерирует контент через NotebookLM Studio: +**Фаза 3 — Артефакты** · Опционально генерирует NotebookLM Studio контент: -| Артефакт | Формат | Для чего | -|----------|--------|----------| -| Audio Overview | MP3 | Подкаст с двумя AI-ведущими, обсуждающими твои источники | +| Артефакт | Формат | Use case | +|---|---|---| +| Audio Overview | MP3 | Подкаст с двумя AI-ведущими | | Mind Map | JSON | Визуальная структура знаний | -| Flashcards | JSON/HTML | Карточки для запоминания из материалов | -| Briefing Doc | Markdown | Краткое резюме для руководства | -| Quiz | JSON/HTML | Тест на понимание материала | +| Flashcards | JSON / HTML | Карточки для запоминания | +| Briefing Doc | Markdown | Executive summary | +| Quiz | JSON / HTML | Тест по материалу | -### /youtube-research — YouTube без ошибок 429 +### /youtube-research — YouTube без 429-ошибок -YouTube transcript API всё чаще блокируется (HTTP 429). NotebookLM принимает YouTube нативно — без API-ключей, без лимитов. +YouTube transcript API всё чаще блокируются (HTTP 429). NotebookLM нативно понимает YouTube — без API-ключей, без rate limits. ``` /youtube-research React Server Components -> Вставь 1-10 YouTube ссылок: +> Вставь 1–10 YouTube-ссылок: https://youtu.be/abc123 https://youtu.be/def456 https://youtu.be/ghi789 -→ Создаёт ноутбук, загружает все видео -→ Структурированный анализ с резюме по каждому видео -→ Паттерны и инсайты между видео -→ Опционально: сгенерировать подкаст из всех видео +→ Создаётся ноутбук, заливаются все видео +→ Структурированный анализ с per-video summary +→ Cross-video паттерны и инсайты +→ Опционально: подкаст из всех видео ``` -### /init-notebook — Документация для твоего стека +### /init-notebook — документация под твой стек -Создаёт NotebookLM ноутбук с предзагруженной официальной документацией: +Создаёт NotebookLM-ноутбук с предзагруженной официальной документацией: ``` /init-notebook fastapi postgresql redis -→ Создаёт ноутбук "fastapi postgresql redis Docs" -→ Добавляет документацию FastAPI, PostgreSQL, Redis -→ Готов к запросам: "Как настроить connection pooling с FastAPI + PostgreSQL?" +→ Создаётся "fastapi postgresql redis Docs" +→ Добавляются FastAPI docs, PostgreSQL docs, Redis docs +→ Готов к запросам: "Как настроить connection pooling FastAPI + PostgreSQL?" ``` -Встроенные подсказки URL для 30+ фреймворков (Next.js, React, Supabase, Tailwind, Drizzle, Playwright, Electron и другие). Работает с любым URL — не ограничен встроенным списком. - -Интегрирован с `/init-project` — предлагает создать ноутбук с документацией при старте нового проекта. +URL-подсказки для 30+ фреймворков (Next.js, React, Supabase, Tailwind, Drizzle, Playwright, Electron и т.д.). Работает с любым URL — не ограничено встроенным списком. -### /telegram-to-notebook — Форум-чаты с темами +### /telegram-to-notebook — форум-чаты с топиками -Единственный инструмент, который корректно обрабатывает Telegram **форум-супергруппы** (чаты с вложенными темами/тредами). Автоматически определяет структуру тем и предлагает три режима экспорта: +Единственный инструмент, который умеет в Telegram **forum-supergroups** (чаты с вложенными топиками / тредами). Авто-определение структуры топиков и три режима экспорта: ``` /telegram-to-notebook result.json -> Обнаружено 12 тем: +> Найдено 12 топиков: [598] Latest: 69 сообщений - [599] Offtop RU: 10,627 сообщений + [599] Offtop RU: 10 627 сообщений [17296] Docker: 867 сообщений ... > Режим экспорта? - 1. По темам (отдельный файл на тему) ← лучше для целевого анализа - 2. Выборочно (только конкретные темы) - 3. Всё вместе (один файл с заголовками тем) + 1. Per-topic (отдельный файл на топик) ← лучшее для точечного анализа + 2. Filtered (только конкретные топики) + 3. All together (один файл с заголовками топиков) ``` -**Умная фильтрация:** Пропускает стикеры, GIF, видеофайлы. Сохраняет текстовые сообщения, фрагменты кода, документы (PDF, JSON, YAML, Python, Go и др.). Оптимизировано для IT-сообществ и исследовательских каналов. +**Smart-фильтрация:** пропускает стикеры, GIF, видео. Оставляет текстовые сообщения, код, документы (PDF, JSON, YAML, Python, Go и т.д.). Оптимизировано под IT-комьюнити и research-каналы. -**Протестировано:** 41K сообщений, 12 тем, 586K слов → 13 файлов загружено в NotebookLM менее чем за 2 минуты. +**Протестировано:** 41K сообщений, 12 топиков, 586K слов → 13 файлов в NotebookLM меньше чем за 2 минуты. ```bash -# Показать темы без экспорта +# Список топиков без экспорта python scripts/telegram-chunker.py result.json --list-topics -# Экспортировать все темы по отдельности +# Экспорт всех топиков отдельно python scripts/telegram-chunker.py result.json --per-topic -# Экспортировать только Docker и FAQ +# Только Docker и FAQ python scripts/telegram-chunker.py result.json --per-topic --topics "Docker,FAQ Remake" ``` -## Мониторинг авторизации +## Auth monitoring -NotebookLM работает через cookies браузера (официального API нет). Cookies истекают. Скрипт проверки запускается ежедневно и предупреждает заранее: +NotebookLM использует браузерные куки (нет официального API). Куки истекают. Auth-check скрипт работает каждый день и предупреждает заранее: ``` -[2026-03-23 10:00:01] AUTH OK — 5 notebooks accessible -[2026-03-25 10:00:01] AUTH EXPIRED — run: nlm login +[2026-03-23 10:00:01] AUTH OK — 5 ноутбуков доступно +[2026-03-25 10:00:01] AUTH EXPIRED — запусти: nlm login ``` -На Windows: всплывающее уведомление при истечении cookies. На Linux/macOS: только лог-файл (PR с нативными уведомлениями приветствуются). +Windows: toast-уведомление при истечении. Linux/macOS: только лог-файл (PR на нативные уведомления приветствуются — см. [`CONTRIBUTING.md`](CONTRIBUTING.md)). ## Конфигурация -### Интеграция с CLAUDE.md +### Интеграция CLAUDE.md -Включённый `config/CLAUDE.md` учит Claude проактивно проверять NotebookLM при работе с незнакомыми библиотеками. Добавь в глобальный конфиг: +`config/CLAUDE.md` учит Claude проактивно проверять NotebookLM при работе с незнакомыми библиотеками. Добавь в global config: ```bash -# Безопасное добавление — не дублирует при повторном запуске +# Безопасный append grep -q "notebooklm-claude-workflows" ~/.claude/CLAUDE.md 2>/dev/null || \ cat ~/notebooklm-claude-workflows/config/CLAUDE.md >> ~/.claude/CLAUDE.md ``` -До: Нужно самому помнить попросить Claude использовать NotebookLM. -После: Claude предлагает это автоматически, когда это полезно. +До: ты должен помнить, чтобы попросить Claude использовать NotebookLM. +После: Claude сам предлагает, когда это поможет. + +## Ограничения + +Это workflow-слой над `notebooklm-mcp-cli`, который сам — обёртка над неофициальным браузерным API NotebookLM. Честные ограничения: + +- **Истечение куки — реальное и регулярное.** У NotebookLM нет официального API; MCP-сервер работает через куки браузера, которые истекают по расписанию Google (обычно раз в несколько недель). Auth-check ловит это заранее, но `nlm login` всё равно нужен. Считай ~30 секунд friction раз в 2–3 недели. +- **500K слов на источник.** NotebookLM ограничивает каждый источник 500K слов. Telegram chunker по умолчанию делает 300K на чанк с запасом. Для очень больших корпусов планируй несколько чанков на топик. +- **`/edit-source` — workaround, не нативная фича.** У NotebookLM нет API для редактирования источника. Команда делает extract → edit → replace, что означает короткое окно когда источник отсутствует в ноутбуке. Не запускай посреди серии запросов. +- **Определение forum-supergroup — эвристика.** Telegram chunker определяет топики по полям `topic_message_id` и действиям `forum_topic_created`. Telegram уже менял формат экспорта; если экспорт из старой версии клиента — определение топиков может ошибиться. Сначала `--list-topics` для проверки. +- **Rate limits NotebookLM непрозрачны.** Google не публикует их. MCP-сервер ретраит на 429, но heavy-research сессии (50+ запросов подряд) иногда стопорятся. Workaround: разделяй на несколько ноутбуков. +- **Slash-команды — только Claude Code.** Claude Desktop получает сырые MCP-tool'ы без workflow-автоматизации — см. [notebooklm-mcp-cli](https://github.com/jacob-bd/notebooklm-mcp-cli) для Desktop setup. +- **Native-уведомления пока только Windows.** macOS `osascript` и Linux `notify-send` — открытые контрибы в [`CONTRIBUTING.md`](CONTRIBUTING.md). +- **Вся система зависит от upstream MCP-сервера.** Если `notebooklm-mcp-cli` ломается, ломаются все команды. Пинуй известно-рабочую версию MCP в продакшне. + +## FAQ + +**Q: Это MCP-сервер?** +Нет. Это workflow-слой поверх [notebooklm-mcp-cli](https://github.com/jacob-bd/notebooklm-mcp-cli). Думай как макросы + шаблоны для MCP-tool'ов. MCP-сервер должен быть установлен сначала. + +**Q: Работает с Claude Desktop?** +Slash-команды специфичны для Claude Code. Desktop получает MCP-tool'ы напрямую, но без workflow-автоматизации. См. [notebooklm-mcp-cli docs](https://github.com/jacob-bd/notebooklm-mcp-cli) для Desktop. + +**Q: Что делать с истечением куки?** +Скрипт auth monitoring проверяет ежедневно и уведомляет. Когда куки истекли — `nlm login` за 30 секунд. + +**Q: Можно ли добавлять свои команды?** +Конечно. Положи любой `.md` в `~/.claude/commands/` в том же формате. См. существующие команды как примеры и [`CONTRIBUTING.md`](CONTRIBUTING.md) для приоритетов. ## Структура проекта ``` notebooklm-claude-workflows/ ├── commands/ -│ ├── youtube-research.md # команда /youtube-research -│ ├── research.md # команда /research (с авто-расширением + Obsidian) -│ ├── deep-research.md # команда /deep-research -│ ├── init-notebook.md # команда /init-notebook -│ ├── telegram-to-notebook.md # команда /telegram-to-notebook -│ ├── analytics-report.md # команда /analytics-report -│ └── edit-source.md # команда /edit-source +│ ├── research.md # /research — полный pipeline +│ ├── deep-research.md # /deep-research — multi-iteration deep dive +│ ├── youtube-research.md # /youtube-research — YouTube через NotebookLM +│ ├── init-notebook.md # /init-notebook — ноутбук под стек +│ ├── telegram-to-notebook.md # /telegram-to-notebook — forum-aware импорт +│ ├── analytics-report.md # /analytics-report — данные → инфографика / отчёт +│ └── edit-source.md # /edit-source — extract → edit → replace ├── scripts/ -│ ├── nlm-auth-check.sh # ежедневная проверка cookies -│ ├── setup-nlm-scheduler.ps1 # настройка Task Scheduler -│ └── telegram-chunker.py # Telegram JSON → чанки для NotebookLM +│ ├── telegram-chunker.py # Telegram JSON → NotebookLM чанки (forum-aware) +│ ├── nlm-auth-check.sh # Дневная проверка куки +│ └── setup-nlm-scheduler.ps1 # Windows Task Scheduler установщик ├── config/ -│ └── CLAUDE.md # глобальные инструкции Claude Code +│ └── CLAUDE.md # Сниппет global-инструкций Claude Code +├── docs/ +│ ├── architecture.svg # Pipeline-диаграмма +│ └── output-mockup.svg # Mock-up вывода /research ├── README.md ├── README.ru.md +├── CHANGELOG.md +├── CONTRIBUTING.md +├── CLAUDE.md # Level 1 файл этого репо (eats own dog food) ├── LICENSE -└── .gitignore +└── .github/workflows/validate.yml ``` -## FAQ +## Связанные проекты -**Q: Это MCP-сервер?** -Нет. Это слой рабочих процессов поверх [notebooklm-mcp-cli](https://github.com/jacob-bd/notebooklm-mcp-cli). Думай об этом как о макросах и шаблонах для MCP-инструментов. MCP-сервер нужно установить отдельно. +- [notebooklm-mcp-cli](https://github.com/jacob-bd/notebooklm-mcp-cli) — MCP-сервер, на который опирается этот проект (обязателен) +- [Claude Code Anti-Regression Setup](https://github.com/CreatmanCEO/claude-code-antiregression-setup) — sister-репо, тот же автор. CLAUDE.md + субагенты + хуки чтобы Claude не сломал твой код пока крутит эти workflow. +- [ai-context-hierarchy](https://github.com/CreatmanCEO/ai-context-hierarchy) — sister-репо. Трёхуровневая система контекста; `config/CLAUDE.md` отсюда — Level 0 фрагмент, который натурально вливается в её иерархию. +- [claude-statusline](https://github.com/CreatmanCEO/claude-statusline) — sister-репо. Умная status-строка для Claude Code; дополняющий инструмент той же экосистемы. -**Q: Работает с Claude Desktop?** -Slash-команды специфичны для Claude Code. Пользователи Claude Desktop получают MCP-инструменты напрямую, но без автоматизации рабочих процессов. См. [документацию notebooklm-mcp-cli](https://github.com/jacob-bd/notebooklm-mcp-cli) для настройки Desktop. +## Контрибьют -**Q: Что с истечением cookies?** -Скрипт мониторинга проверяет ежедневно и уведомляет. Когда cookies истекают — просто запусти `nlm login`, это 30 секунд. +PR приветствуются — см. [CONTRIBUTING.md](CONTRIBUTING.md). Текущие приоритеты: native-уведомления для Linux/macOS auth-check, расширение URL-словаря в `/init-notebook`, новые slash-команды (PDF research, podcast-to-notebook), переводы команд на другие локали. -**Q: Могу добавить свои команды?** -Конечно. Положи любой `.md` файл в `~/.claude/commands/` в том же формате. Используй существующие команды как пример. +## Автор -## Связанные проекты +**Николай Подоляк (Nick Podolyak)** — Python-разработчик и цифровой архитектор в [CREATMAN](https://creatman.site) -- [notebooklm-mcp-cli](https://github.com/jacob-bd/notebooklm-mcp-cli) — MCP-сервер, на котором строится этот проект (обязателен) -- [claude-statusline](https://github.com/CreatmanCEO/claude-statusline) — Умная статус-строка для Claude Code (от того же автора) +- GitHub: [@CreatmanCEO](https://github.com/CreatmanCEO) +- Habr: [creatman](https://habr.com/ru/users/creatman/) +- dev.to: [@creatman](https://dev.to/creatman) ## Лицензия -MIT — [Nick Podolyak](https://github.com/CreatmanCEO) / CREATMAN Studio +[MIT](LICENSE) · Николай Подоляк diff --git a/docs/architecture.svg b/docs/architecture.svg new file mode 100644 index 0000000..2e28bfc --- /dev/null +++ b/docs/architecture.svg @@ -0,0 +1,81 @@ + + + notebooklm-claude-workflows — pipeline architecture + Architecture: a slash command in Claude Code drives a deterministic three-phase pipeline (Collect → Analyze → Artifacts) over the notebooklm-mcp-cli MCP tools. Each phase issues a sequence of MCP calls (notebook_create, source_add, notebook_query, studio_create) so the user never has to orchestrate them manually. + + + + How a slash command turns one prompt into a deterministic pipeline + user types one line · Claude Code runs the workflow · MCP tools execute + + + + user prompt + /research AI agents 2025 + + + + + + + + commands/research.md + 3-phase recipe loaded by Claude Code + + + + + + + + Phase 1 — Collect + • prompt user for sources + • notebook_create & source_add ×N + • optional research_start (auto-expand) + • always wait=true on each source + + + + + + + + Phase 2 — Analyze + • notebook_query — summary + • notebook_query — patterns + • notebook_query — contradictions + • cite-anchored structured report + + + + + + + + Phase 3 — Artifacts + • studio_create · audio + • studio_create · mind_map + • studio_create · flashcards + • studio_create · briefing + + + + — MCP tool boundary — + + + + notebooklm-mcp-cli (jacob-bd) + browser-cookie auth · NotebookLM API · 12+ MCP tools + + + + + + + + + Google NotebookLM (browser-only product) + + + + diff --git a/docs/output-mockup.svg b/docs/output-mockup.svg new file mode 100644 index 0000000..a6a525f --- /dev/null +++ b/docs/output-mockup.svg @@ -0,0 +1,50 @@ + + + /research command — example output mock-up + Mock-up of what /research returns: a structured Claude Code response with a section header, three bullet groups for findings/patterns/contradictions, and inline citations linking back to the user's NotebookLM sources. Shows the value of going from raw MCP to an opinionated workflow. + + + + + + + + + Claude Code · /research example output + + + > /research AI code assistants 2026 + + + ✓ Phase 1 — collected 5 sources, auto-expanded with 3 more (8 total) + + + Research: AI code assistants 2026 + based on 8 NotebookLM sources · structured analysis + + + ▸ Key findings + • Claude Code adoption tripled after Opus 4.6 1M context release [1, 4] + • Subagent + hook pattern is the de-facto standard for regression prevention [2, 5, 7] + • MCP servers shipped: Playwright, GitHub, Postgres, Context7 lead by usage [3, 6] + + + ▸ Cross-source patterns + • Three of four sources frame the bottleneck as discipline, not memory [1, 2, 5] + • Conversation indexing emerges as a parallel solution to context drift [2, 7] + + + ▸ Contradictions to flag + • Source [3] claims 10× token savings; sources [1, 5] caution that the real win is + accuracy, not raw token reduction + + + ▸ Recommendations + • Adopt CLAUDE.md + subagents for any team using Claude Code in production [2, 4, 6] + • Pair with hierarchical context (Level 0 / Level 1) for multi-project setups [7] + + + + ▸ Generate artifacts? (1) Audio overview · (2) Mind map · (3) Flashcards · (4) Briefing doc + — citations [1]–[8] map to your 8 NotebookLM sources, click in NotebookLM for the exact passage +