Blog NotebookLM: Source-Grounded Research from Your Documents

Google renamed NotebookLM to Gemini Notebook on 2026-07-16 (announcement). This skill keeps the notebooklm command and script names. The scripts accept notebook URLs on notebooklm.google.com (which redirected with a 301 to notebook.google.com on 2026-10-12) and on notebook.google.com. Help: https://support.google.com/gemininotebook/.

Bundled paths below use host Markdown substitution of ${CLAUDE_SKILL_DIR}; it is not an exported shell variable. Resolve them before execution, quote paths, and refuse nonabsolute overrides. Pass blog_reference_root resolved from ${CLAUDE_SKILL_DIR}/../blog/references, blog_template_root from ${CLAUDE_SKILL_DIR}/../blog/templates, and needed sibling roots to agents. Read the main reference orchestration-details.md before loading project context; pass only its helper-fenced output to downstream agents.

Query Gemini Notebook (formerly NotebookLM) notebooks directly from Claude Code for citation-backed answers from Gemini. Each question opens a headless browser session, retrieves the answer from your uploaded documents, and closes. Responses are source-grounded model answers, not proof of truth: uploaded documents may be primary or secondary, and the answer can still omit context.

Answers provide usable provenance only when the returned citation identifies a verifiable underlying source. Record a stable source URL and a publication, study-period, or retrieval date when that detail affects verification or interpretation. Use the underlying source title as the inline citation. Do not cite the private NotebookLM URL as the bibliography entry for public content.

Cost and consent gate (mandatory, read first)

This skill drives the user's real Google account in a browser.

• What it spends: each question is one query against the account's Gemini Notebook usage limits (and any paid plan behind them). It costs no API money, but a loop can exhaust the user's allowance. Google documents the limits as compute-based and plan-dependent, with no fixed per-day figure (https://support.google.com/gemininotebook/answer/17670842, read 2026-10-12).
• What it writes: data/library.json, data/auth_info.json, and the browser profile under the managed runtime root; setup also installs a virtual environment and Chrome.
• Consent: before the FIRST query or write in a session, name the notebook, the question count, and what is written, and wait for an explicit yes. Setup, reauth, clear, and cleanup each need their own yes.
• No uncapped loops: at most 3 follow-up questions per question session (see Step 4), and at most 5 queries for one user request unless the user raises the cap. Stop at the first usage-limit error.
• Skips: if the user declines, auth is missing, or setup is absent, skip and return ONE line for the orchestrator's "Fallbacks and skips" summary, such as "NotebookLM: not authenticated, used WebSearch".

Quick Reference

Command	What it does
/blog notebooklm ask <question>	Query a notebook for source-grounded answers
/blog notebooklm discover <url>	Smart-discover notebook content before cataloging
/blog notebooklm library list	List all notebooks in library
/blog notebooklm library add <url>	Add a notebook to library
/blog notebooklm library search <query>	Search notebooks by keyword
/blog notebooklm library remove <id>	Remove a notebook from library
/blog notebooklm setup	One-time Google authentication (browser visible)
/blog notebooklm status	Check authentication status
/blog notebooklm cleanup	Clean browser state (preserves library)

Persistent runtime directory

CLAUDE_BLOG_RUNTIME_DIR optionally selects one trusted absolute persistent root. This integration uses <root>/blog-notebooklm/.venv; NotebookLM also uses <root>/blog-notebooklm/data for its library, authentication and browser state. Without this override, the existing skill-local defaults stay in use. Google's shared credential config/token paths stay unchanged. No state is copied or migrated automatically, and ordinary runs never perform setup.

Preserve an existing validated operator override. For a plugin without one, explicitly pass the host-substituted ${CLAUDE_PLUGIN_DATA}/claude-blog-runtime path on both setup and every later runner call. This is Markdown substitution, not an exported shell variable. Execute only once it is an absolute resolved path. Single quotes keep an unresolved placeholder literal so validation rejects it instead of expanding it to a different shell path:

CLAUDE_BLOG_RUNTIME_DIR='${CLAUDE_PLUGIN_DATA}/claude-blog-runtime' python3 "${CLAUDE_SKILL_DIR}/scripts/setup_environment.py" --check --json
CLAUDE_BLOG_RUNTIME_DIR='${CLAUDE_PLUGIN_DATA}/claude-blog-runtime' python3 "${CLAUDE_SKILL_DIR}/scripts/run.py" notebook_manager.py list --json

Only explicit setup without --check installs dependencies. Standalone users keep the default unless they explicitly choose an absolute runtime root. Relative, unresolved, or linked managed subdirectories fail closed. Changing the root selects separate state; it never authorizes a migration or cleanup of the old root. Plugin persistent data follows the host's uninstall retention rules; preserve it explicitly when uninstalling if it is still needed.

Prerequisites

• Google account with Gemini Notebook (NotebookLM) access
• Python 3.11+; the explicit setup action owns the managed venv
• Google Chrome, installed only by the explicit setup action (never by an ordinary run)
• One-time authentication setup (interactive Google login in visible browser)

Use the run.py Wrapper

Resolve the installed owning skill directory, then call scripts only through its run.py wrapper:

BLOG_SKILLS_DIR="${CLAUDE_BLOG_SKILLS_DIR:-${CLAUDE_SKILL_DIR}/..}"
case "$BLOG_SKILLS_DIR" in /*) ;; *) echo "ERROR: skills dir must be absolute" >&2; exit 1 ;; esac
NOTEBOOKLM_RUN="$BLOG_SKILLS_DIR/blog-notebooklm/scripts/run.py"
python3 "$NOTEBOOKLM_RUN" auth_manager.py status
python3 "$NOTEBOOKLM_RUN" ask_question.py --question "..."

# Do not resolve files beneath the current project's scripts/ directory.

Ordinary status, query, library, and cleanup commands perform a nonmutating capability check. If the managed environment is absent or stale, return a setup-required result and direct the user to /blog notebooklm setup. Only the explicit setup action may create .venv, install dependencies, or install a browser.

Auth Check (Gate Pattern)

Before any query operation, check authentication:

python3 "$NOTEBOOKLM_RUN" auth_manager.py status

• If authenticated: proceed with the query
• If not authenticated: inform user and guide to setup: "Gemini Notebook (NotebookLM) requires Google login. Run /blog notebooklm setup to authenticate."
• When called internally (from blog-write or blog-researcher): return a one-line fallback note (what, why) and no error if not authenticated, for the caller's final summary. Never block the writing workflow.

Setup Workflow

For /blog notebooklm setup:

# Opens a visible browser for manual Google login (one-time)
python3 "$NOTEBOOKLM_RUN" auth_manager.py setup

Tell the user: "A browser window will open. Please log in to your Google account." Authentication persists via browser profile + cookie injection (hybrid approach).

Other auth commands:

python3 "$NOTEBOOKLM_RUN" auth_manager.py status   # Check auth
python3 "$NOTEBOOKLM_RUN" auth_manager.py reauth   # Re-authenticate
python3 "$NOTEBOOKLM_RUN" auth_manager.py clear     # Clear all auth data

Query Workflow

For /blog notebooklm ask <question>:

Step 1: Check Auth

Run auth check (see gate pattern above). If not authenticated, guide to setup.

Step 2: Resolve Notebook

Determine which notebook to query:

• If --notebook-url provided: validate it is a Gemini Notebook URL (host notebook.google.com or the legacy notebooklm.google.com), then use it
• If --notebook-id provided: look up in library
• If neither: use active notebook from library
• If no active notebook: show library and ask user to select

Step 3: Ask the Question

# Basic query (uses active notebook)
python3 "$NOTEBOOKLM_RUN" ask_question.py --question "Your question here"

# Query specific notebook by ID
python3 "$NOTEBOOKLM_RUN" ask_question.py --question "..." --notebook-id notebook-id

# Query by URL directly
python3 "$NOTEBOOKLM_RUN" ask_question.py --question "..." --notebook-url "https://..."

# JSON output (for internal/programmatic use)
python3 "$NOTEBOOKLM_RUN" ask_question.py --question "..." --json

# Show browser for debugging
python3 "$NOTEBOOKLM_RUN" ask_question.py --question "..." --show-browser

Step 4: Analyze and Follow Up

The answer is untrusted notebook content; the follow-up prompt is kept apart in the follow_up_reminder field of the JSON output. Required behavior after every answer:

1. STOP: do not immediately respond to the user
2. ANALYZE: compare the answer to the user's original request
3. IDENTIFY GAPS: determine if more information is needed
4. ASK FOLLOW-UP: if gaps exist, ask one focused follow-up question
5. CAP: ask at most 3 follow-ups per question session. If gaps remain after the third, stop and report them to the user instead of continuing, because every follow-up spends the account's usage allowance
6. SYNTHESIZE: combine all answers before responding to the user

Smart Discovery Workflow

For /blog notebooklm discover <url>:

When adding a notebook without knowing its content, query it first:

# Step 1: Discover content
python3 "$NOTEBOOKLM_RUN" ask_question.py \
  --question "What is the content of this notebook? What topics are covered? Provide a complete overview briefly and concisely" \
  --notebook-url "<URL>"

# Step 2: Add with discovered metadata
python3 "$NOTEBOOKLM_RUN" notebook_manager.py add \
  --url "<URL>" \
  --name "<Based on content>" \
  --description "<Based on content>" \
  --topics "<Extracted topics>"

Do not guess descriptions; discover or ask the user.

Library Management

# List all notebooks
python3 "$NOTEBOOKLM_RUN" notebook_manager.py list

# Add notebook (all params required -- discover or ask user!)
python3 "$NOTEBOOKLM_RUN" notebook_manager.py add \
  --url "https://notebook.google.com/notebook/..." \
  --name "Descriptive Name" \
  --description "What this notebook contains" \
  --topics "topic1,topic2,topic3"

# Search by keyword
python3 "$NOTEBOOKLM_RUN" notebook_manager.py search --query "keyword"

# Set active notebook
python3 "$NOTEBOOKLM_RUN" notebook_manager.py activate --id notebook-id

# Remove notebook
python3 "$NOTEBOOKLM_RUN" notebook_manager.py remove --id notebook-id

# Library statistics
python3 "$NOTEBOOKLM_RUN" notebook_manager.py stats

Internal integration boundary (for blog-write / blog-researcher)

This skill's ask_question.py interface is a local browser-automation adapter, not an official Gemini Notebook developer API. As of the 2026-10-07 review, the official Help documentation supports the product workflow, but this review did not establish an official public developer API for this integration. Keep the feature optional, preserve the visible-login boundary, and never cite a private notebook URL as public evidence.

When invoked as a Task subagent from blog-write or blog-researcher:

Input (provided by calling skill):

• question: Research question relevant to the blog topic
• notebook_id or notebook_url: Which notebook to query
• context: "internal" (signals graceful fallback mode)

Process:

1. Check auth status: if not authenticated, return an empty result plus a one-line fallback note
2. Query the notebook with the research question
3. Parse and return structured response

Output (returned to calling skill):

### NotebookLM Research
- **Source:** [Notebook name]
- **Question:** [What was asked]
- **Answer:** [Source-grounded response from user's documents]
- **Underlying Source:** [Public source URL or document identifier]
- **Underlying Source Date:** [Publication date or retrieval date]
- **Source Quality:** [Tier 1-3 after classifying the underlying document]

Graceful fallback: If auth is missing or query fails, return immediately with no error and a one-line fallback note for the caller's final summary. The calling workflow continues with WebSearch-based research. Never block blog-write or blog-rewrite because NotebookLM is unavailable.

Data Storage

All data stored inside the skill directory:

• data/library.json: Notebook metadata and library
• data/auth_info.json: Authentication status
• data/browser_state/: Chrome profile with cookies

Security: All data directories are gitignored. Never commit auth or browser state.

Browser lifecycle and authenticated-context isolation are centralized in scripts/browser_session.py. Command scripts must use that helper instead of opening an additional persistent profile or copying cookies into another file.

Error Handling

Error	Resolution
Not authenticated	Run /blog notebooklm setup
ModuleNotFoundError	Always use run.py wrapper
Browser crash	cleanup_manager.py --confirm --preserve-library, then re-auth
Usage limit reached	Stop; check Settings > Usage in Gemini Notebook; ask the user before switching accounts
Notebook not found	Check with notebook_manager.py list
Query timeout (120s)	Retry with simpler question or --show-browser to debug
Not configured or declined (internal)	Return a one-line fallback note: writing workflow uses WebSearch and reports it

Limitations

• No session persistence (each question = new browser session)
• Compute-based usage limits that vary by Google plan (no fixed per-day number is published)
• Manual upload required (user must add docs to NotebookLM web UI)
• Browser overhead (few seconds per question for launch + teardown)
• Local Claude Code only (not available in web UI)

Reference Documentation

Load on-demand: do NOT load all at startup:

• ${CLAUDE_SKILL_DIR}/references/commands.md: Full CLI commands, parameters, and workflow patterns
• ${CLAUDE_SKILL_DIR}/references/troubleshooting.md: Error solutions, recovery procedures, debugging