notebooklm

name	notebooklm
description	Full control over Google NotebookLM from Claude Code. Query notebooks, create new notebooks, add sources (URLs, text, files), delete notebooks, list remote notebooks, and manage your library. Browser automation with persistent auth and anti-detection.

NotebookLM Full Control Skill

Full control over Google NotebookLM directly from Claude Code. Query notebooks, create new ones, add sources (URLs, text, files), delete notebooks, and manage your library — all via browser automation.

AUTOMATIC FIRST-TIME SETUP (CRITICAL)

When this skill is used for the FIRST TIME, Claude MUST handle everything automatically. The user should NOT need to know technical details. Follow these steps IN ORDER:

Step 0: Detect Python

Before anything, check that Python is available:

python --version 2>&1 || python3 --version 2>&1 || py --version 2>&1

• If python works, use python for all commands
• If only python3 works, use python3
• If only py works (Windows), use py
• If NONE work, tell the user: "You need Python installed. Download it from https://python.org and make sure to check 'Add to PATH' during installation."
• Store which Python command works and use it for ALL subsequent commands

Step 1: Auto-setup environment

The first run of any script automatically creates the virtual environment. Just run:

cd ~/.claude/skills/notebooklm && [python-cmd] scripts/run.py auth_manager.py status

This triggers the automatic setup: creates .venv, installs dependencies, installs Chrome.

IMPORTANT for Windows: If you get encoding errors (cp1252, charmap), the run.py script already handles this. If it STILL fails, prefix with: PYTHONUTF8=1

IMPORTANT: If pip upgrade fails, it's non-critical. The setup will continue. If dependency install fails, try:

cd ~/.claude/skills/notebooklm && [python-cmd] -m venv .venv --clear && .venv/Scripts/pip.exe install -r requirements.txt && .venv/Scripts/python.exe -m patchright install chrome

(On Mac/Linux replace Scripts with bin and pip.exe/python.exe with pip/python)

Step 2: Auto-authenticate

If auth status shows "Not authenticated":

cd ~/.claude/skills/notebooklm && [python-cmd] scripts/run.py auth_manager.py setup

Tell user: "A Chrome window will open. Please log in to your Google account. Once you're in NotebookLM, I'll continue automatically."

Step 3: Ready!

Once authenticated, the skill is fully operational. Tell the user what they can do:

• "Ask questions to your NotebookLM notebooks"
• "Create new notebooks"
• "Add sources (URLs, text, files) to notebooks"
• "List your notebooks"
• "Delete notebooks"

ALL of the above steps should happen automatically the first time the user mentions NotebookLM. Do NOT ask the user to run commands manually.

When to Use This Skill

Trigger when user:

• Mentions NotebookLM explicitly
• Shares NotebookLM URL (https://notebooklm.google.com/notebook/...)
• Asks to query their notebooks/documentation
• Wants to add documentation to NotebookLM library
• Wants to create a new notebook
• Wants to add sources (URL, text, file/PDF) to a notebook
• Wants to delete a notebook
• Wants to list their notebooks from NotebookLM
• Wants to see sources in a notebook
• Uses phrases like "ask my NotebookLM", "check my docs", "query my notebook"
• Uses phrases like "create a notebook", "add this to my notebook", "upload to NotebookLM"

⚠️ CRITICAL: Add Command - Smart Discovery

When user wants to add a notebook without providing details:

SMART ADD (Recommended): Query the notebook first to discover its content:

# Step 1: Query the notebook about its content
python scripts/run.py 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: Use the discovered information to add it
python scripts/run.py notebook_manager.py add --url "[URL]" --name "[Based on content]" --description "[Based on content]" --topics "[Based on content]"

MANUAL ADD: If user provides all details:

• --url - The NotebookLM URL
• --name - A descriptive name
• --description - What the notebook contains (REQUIRED!)
• --topics - Comma-separated topics (REQUIRED!)

NEVER guess or use generic descriptions! If details missing, use Smart Add to discover them.

Critical: Always Use run.py Wrapper

NEVER call scripts directly. ALWAYS use python scripts/run.py [script]:

# ✅ CORRECT - Always use run.py:
python scripts/run.py auth_manager.py status
python scripts/run.py notebook_manager.py list
python scripts/run.py ask_question.py --question "..."

# ❌ WRONG - Never call directly:
python scripts/auth_manager.py status  # Fails without venv!

The run.py wrapper automatically:

1. Creates .venv if needed
2. Installs all dependencies
3. Activates environment
4. Executes script properly

Core Workflow

Step 1: Check Authentication Status

python scripts/run.py auth_manager.py status

If not authenticated, proceed to setup.

Step 2: Authenticate (One-Time Setup)

# Browser MUST be visible for manual Google login
python scripts/run.py auth_manager.py setup

Important:

• Browser is VISIBLE for authentication
• Browser window opens automatically
• User must manually log in to Google
• Tell user: "A browser window will open for Google login"

Step 3: Manage Notebook Library

# List all notebooks
python scripts/run.py notebook_manager.py list

# BEFORE ADDING: Ask user for metadata if unknown!
# "What does this notebook contain?"
# "What topics should I tag it with?"

# Add notebook to library (ALL parameters are REQUIRED!)
python scripts/run.py notebook_manager.py add \
  --url "https://notebooklm.google.com/notebook/..." \
  --name "Descriptive Name" \
  --description "What this notebook contains" \  # REQUIRED - ASK USER IF UNKNOWN!
  --topics "topic1,topic2,topic3"  # REQUIRED - ASK USER IF UNKNOWN!

# Search notebooks by topic
python scripts/run.py notebook_manager.py search --query "keyword"

# Set active notebook
python scripts/run.py notebook_manager.py activate --id notebook-id

# Remove notebook
python scripts/run.py notebook_manager.py remove --id notebook-id

Quick Workflow

1. Check library: python scripts/run.py notebook_manager.py list
2. Ask question: python scripts/run.py ask_question.py --question "..." --notebook-id ID

Step 4: Ask Questions

# Basic query (uses active notebook if set)
python scripts/run.py ask_question.py --question "Your question here"

# Query specific notebook
python scripts/run.py ask_question.py --question "..." --notebook-id notebook-id

# Query with notebook URL directly
python scripts/run.py ask_question.py --question "..." --notebook-url "https://..."

# Show browser for debugging
python scripts/run.py ask_question.py --question "..." --show-browser

Follow-Up Mechanism (CRITICAL)

Every NotebookLM answer ends with: "EXTREMELY IMPORTANT: Is that ALL you need to know?"

Required Claude Behavior:

1. STOP - Do not immediately respond to user
2. ANALYZE - Compare answer to user's original request
3. IDENTIFY GAPS - Determine if more information needed
4. ASK FOLLOW-UP - If gaps exist, immediately ask:

   python scripts/run.py ask_question.py --question "Follow-up with context..."
   

5. REPEAT - Continue until information is complete
6. SYNTHESIZE - Combine all answers before responding to user

Script Reference

Authentication Management (auth_manager.py)

python scripts/run.py auth_manager.py setup    # Initial setup (browser visible)
python scripts/run.py auth_manager.py status   # Check authentication
python scripts/run.py auth_manager.py reauth   # Re-authenticate (browser visible)
python scripts/run.py auth_manager.py clear    # Clear authentication

Notebook Management - Local Library (notebook_manager.py)

python scripts/run.py notebook_manager.py add --url URL --name NAME --description DESC --topics TOPICS
python scripts/run.py notebook_manager.py list
python scripts/run.py notebook_manager.py search --query QUERY
python scripts/run.py notebook_manager.py activate --id ID
python scripts/run.py notebook_manager.py remove --id ID
python scripts/run.py notebook_manager.py stats

Notebook Creator (notebook_creator.py) - NEW

# Create a new notebook in NotebookLM
python scripts/run.py notebook_creator.py create --name "My Notebook"

# Create and automatically add to local library
python scripts/run.py notebook_creator.py create --name "My Notebook" --add-to-library --description "What it contains" --topics "topic1,topic2"

# List all notebooks from your NotebookLM account
python scripts/run.py notebook_creator.py list-remote

# Delete a notebook (requires --confirm for safety)
python scripts/run.py notebook_creator.py delete --url "https://notebooklm.google.com/notebook/..." --confirm
python scripts/run.py notebook_creator.py delete --notebook-id my-notebook --confirm

# All commands support --show-browser for debugging
python scripts/run.py notebook_creator.py create --name "Test" --show-browser

Source Manager (source_manager.py) - NEW

# Add a website URL as source
python scripts/run.py source_manager.py add-url --url "https://example.com/article" --notebook-id my-notebook
python scripts/run.py source_manager.py add-url --url "https://example.com" --notebook-url "https://notebooklm.google.com/notebook/..."

# Add text as source (inline or from file)
python scripts/run.py source_manager.py add-text --text "Your content here..." --title "My Notes" --notebook-id my-notebook
python scripts/run.py source_manager.py add-text --file "/path/to/notes.txt" --title "My Notes" --notebook-id my-notebook

# Upload a file (PDF, etc.) as source
python scripts/run.py source_manager.py add-file --file "/path/to/document.pdf" --notebook-id my-notebook

# List sources in a notebook
python scripts/run.py source_manager.py list --notebook-id my-notebook

# All commands support --show-browser for debugging
python scripts/run.py source_manager.py add-url --url "https://example.com" --notebook-id my-notebook --show-browser

Question Interface (ask_question.py)

python scripts/run.py ask_question.py --question "..." [--notebook-id ID] [--notebook-url URL] [--show-browser]

Data Cleanup (cleanup_manager.py)

python scripts/run.py cleanup_manager.py                    # Preview cleanup
python scripts/run.py cleanup_manager.py --confirm          # Execute cleanup
python scripts/run.py cleanup_manager.py --preserve-library # Keep notebooks

Full Workflow Example (Create + Add Sources + Query)

User: "Create a notebook about AI safety and add some sources"

Step 1: Create notebook
python scripts/run.py notebook_creator.py create --name "AI Safety Research" --add-to-library --description "Research on AI safety" --topics "AI,safety,alignment"

Step 2: Add sources
python scripts/run.py source_manager.py add-url --url "https://example.com/ai-safety-paper" --notebook-id ai-safety-research
python scripts/run.py source_manager.py add-file --file "/path/to/paper.pdf" --notebook-id ai-safety-research
python scripts/run.py source_manager.py add-text --text "Key points about AI safety..." --title "My Notes" --notebook-id ai-safety-research

Step 3: Query the notebook
python scripts/run.py ask_question.py --question "What are the main AI safety concerns?" --notebook-id ai-safety-research

Environment Management

The virtual environment is automatically managed:

• First run creates .venv automatically
• Dependencies install automatically
• Chromium browser installs automatically
• Everything isolated in skill directory

Manual setup (only if automatic fails):

python -m venv .venv
source .venv/bin/activate  # Linux/Mac
pip install -r requirements.txt
python -m patchright install chromium

Data Storage

All data stored in ~/.claude/skills/notebooklm/data/:

• library.json - Notebook metadata
• auth_info.json - Authentication status
• browser_state/ - Browser cookies and session

Security: Protected by .gitignore, never commit to git.

Configuration

Optional .env file in skill directory:

HEADLESS=false           # Browser visibility
SHOW_BROWSER=false       # Default browser display
STEALTH_ENABLED=true     # Human-like behavior
TYPING_WPM_MIN=160       # Typing speed
TYPING_WPM_MAX=240
DEFAULT_NOTEBOOK_ID=     # Default notebook

Decision Flow

User mentions NotebookLM
    ↓
Check auth → python scripts/run.py auth_manager.py status
    ↓
If not authenticated → python scripts/run.py auth_manager.py setup
    ↓
What does the user want?
    ├── QUERY a notebook:
    │   ├── Check/Add notebook → notebook_manager.py list/add
    │   ├── Activate notebook → notebook_manager.py activate --id ID
    │   ├── Ask question → ask_question.py --question "..."
    │   ├── Follow-up until complete
    │   └── Synthesize and respond
    │
    ├── CREATE a notebook:
    │   ├── Create → notebook_creator.py create --name "..." --add-to-library
    │   └── Return URL to user
    │
    ├── ADD SOURCES to a notebook:
    │   ├── URL → source_manager.py add-url --url "..." --notebook-id ID
    │   ├── Text → source_manager.py add-text --text "..." --notebook-id ID
    │   ├── File → source_manager.py add-file --file "..." --notebook-id ID
    │   └── Confirm success to user
    │
    ├── LIST notebooks:
    │   ├── Local library → notebook_manager.py list
    │   └── Remote (from account) → notebook_creator.py list-remote
    │
    ├── LIST SOURCES in a notebook:
    │   └── source_manager.py list --notebook-id ID
    │
    └── DELETE a notebook:
        ├── Confirm with user first!
        ├── Delete → notebook_creator.py delete --url "..." --confirm
        └── Remove from library → notebook_manager.py remove --id ID

Troubleshooting

Problem	Solution
ModuleNotFoundError	Use run.py wrapper
Authentication fails	Browser must be visible for setup! --show-browser
Rate limit (50/day)	Wait or switch Google account
Browser crashes	python scripts/run.py cleanup_manager.py --preserve-library
Notebook not found	Check with notebook_manager.py list
Create button not found	NotebookLM UI may have changed. Use --show-browser to debug
Source upload fails	Use --show-browser to see what's happening. Check file format
Selector not found	UI may have updated. Check debug_create.png in data/ folder

Best Practices

1. Always use run.py - Handles environment automatically
2. Check auth first - Before any operations
3. Follow-up questions - Don't stop at first answer
4. Browser visible for auth - Required for manual login
5. Include context - Each question is independent
6. Synthesize answers - Combine multiple responses
7. Use --show-browser for new features - Create/source commands are UI-dependent
8. Confirm before deleting - Always ask user before running delete with --confirm

Limitations

• No session persistence (each question = new browser)
• Rate limits on free Google accounts (50 queries/day)
• Browser overhead (few seconds per operation)
• Create/source/delete features depend on NotebookLM UI (may break if Google changes the interface)
• File uploads support formats accepted by NotebookLM (PDF, Google Docs, etc.)
• Use --show-browser flag if any automated action fails

Resources (Skill Structure)

Important directories and files:

• scripts/ - All automation scripts:
  • ask_question.py - Query notebooks
  • notebook_manager.py - Local library management
  • notebook_creator.py - Create/delete notebooks in NotebookLM (NEW)
  • source_manager.py - Add/list sources in notebooks (NEW)
  • auth_manager.py - Authentication management
  • cleanup_manager.py - Data cleanup
  • browser_utils.py - Browser factory and stealth utilities
  • browser_session.py - Browser session management
  • config.py - Centralized configuration and selectors
  • run.py - Universal script runner (always use this!)
  • setup_environment.py - Environment setup
• data/ - Local storage for authentication and notebook library
• references/ - Extended documentation:
  • api_reference.md - Detailed API documentation for all scripts
  • troubleshooting.md - Common issues and solutions
  • usage_patterns.md - Best practices and workflow examples
• .venv/ - Isolated Python environment (auto-created on first run)
• .gitignore - Protects sensitive data from being committed