notebooklm

# 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: ```bash 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: ```bash 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: ```bash 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": ```bash 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: ```bash # 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]`:** ```bash # ✅ 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 ```bash python scripts/run.py auth_manager.py status ``` If not authenticated, proceed to setup. ### Step 2: Authenticate (One-Time Setup) ```bash # 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 ```bash # 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 ```bash # 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: ```bash 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`) ```bash 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`) ```bash 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 ```bash # 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 ```bash # 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`) ```bash python scripts/run.py ask_question.py --question "..." [--notebook-id ID] [--notebook-url URL] [--show-browser] ``` ### Data Cleanup (`cleanup_manager.py`) ```bash 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): ```bash 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: ```env 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 | |---------|----------|