notebooklm

What this skill does

<!-- notebooklm-py v0.1.3 -->


# NotebookLM Automation

Automate Google NotebookLM: create notebooks, add sources, chat with content, generate artifacts (podcasts, videos, quizzes), and download results.

## Prerequisites

**IMPORTANT:** Before using any command, you MUST authenticate:

```bash
notebooklm login          # Opens browser for Google OAuth
notebooklm list           # Verify authentication works
```

If commands fail with authentication errors, re-run `notebooklm login`.

### CI/CD, Multiple Accounts, and Parallel Agents

For automated environments, multiple accounts, or parallel agent workflows:

| Variable | Purpose |
|----------|---------|
| `NOTEBOOKLM_HOME` | Custom config directory (default: `~/.notebooklm`) |
| `NOTEBOOKLM_AUTH_JSON` | Inline auth JSON - no file writes needed |

**CI/CD setup:** Set `NOTEBOOKLM_AUTH_JSON` from a secret containing your `storage_state.json` contents.

**Multiple accounts:** Use different `NOTEBOOKLM_HOME` directories per account.

**Parallel agents:** The CLI stores notebook context in a shared file (`~/.notebooklm/context.json`). Multiple concurrent agents using `notebooklm use` can overwrite each other's context.

**Solutions for parallel workflows:**
1. **Always use explicit notebook ID** (recommended): Pass `-n <notebook_id>` (for `wait`/`download` commands) or `--notebook <notebook_id>` (for others) instead of relying on `use`
2. **Per-agent isolation:** Set unique `NOTEBOOKLM_HOME` per agent: `export NOTEBOOKLM_HOME=/tmp/agent-$ID`
3. **Use full UUIDs:** Avoid partial IDs in automation (they can become ambiguous)

## Agent Setup Verification

Before starting workflows, verify the CLI is ready:

1. `notebooklm status` → Should show "Authenticated as: email@..."
2. `notebooklm list --json` → Should return valid JSON (even if empty notebooks list)
3. If either fails → Run `notebooklm login`

## When This Skill Activates

**Explicit:** User says "/notebooklm", "use notebooklm", or mentions the tool by name

**Intent detection:** Recognize requests like:
- "Create a podcast about [topic]"
- "Summarize these URLs/documents"
- "Generate a quiz from my research"
- "Turn this into an audio overview"
- "Add these sources to NotebookLM"
- "Create a notebook from [Twitter/X link]"
- "Extract content from this [social media post]"

**Progressive fallback strategy (graceful degradation):**
1. **First attempt**: Regular URL addition via `notebooklm source add "url"` (always try first)
2. **Detect failure conditions**: Monitor for errors like:
   - Anti-crawler protection (Twitter/X, LinkedIn)
   - Login required errors
   - 403/404 access denied
   - Processing failures/timeouts
3. **Graceful fallback**: Only then use browser extraction:
   - Navigate via Playwright
   - Extract content using JavaScript
   - Save to `/tmp/` before adding to NotebookLM
4. **User notification**: Always inform user of the method used:
   - "✓ Added via direct URL" (success with regular method)
   - "⚠️ Required browser extraction (anti-crawler)" (fallback used)

## Autonomy Rules

**Run automatically (no confirmation):**
- `notebooklm status` - check context
- `notebooklm list` - list notebooks
- `notebooklm source list` - list sources
- `notebooklm artifact list` - list artifacts
- `notebooklm artifact wait` - wait for artifact completion (in subagent context)
- `notebooklm source wait` - wait for source processing (in subagent context)
- `notebooklm research status` - check research status
- `notebooklm research wait` - wait for research (in subagent context)
- `notebooklm use <id>` - set context (⚠️ SINGLE-AGENT ONLY - use `-n` flag in parallel workflows)
- `notebooklm create` - create notebook
- `notebooklm ask "..."` - chat queries
- `notebooklm source add` - add sources

**Smart Decision Framework (Pragmatic Approach)**

**Installation Status System**:
```bash
# Installation flag - prevents redundant checks
INSTALL_FLAG="$HOME/.cache/notebooklm/.playwright_installed"

# Function to check installation status (only once per session)
check_install_status() {
  # Fast check only if not explicitly checking
  if [[ "$1" == "--check-install-only" ]]; then
    if [ -f "$INSTALL_FLAG" ]; then
      echo "✓ Playwright is marked as installed"
      return 0
    else
      echo "⚠️ Playwright not marked, checking installation..."
      # Here you have options:
      # Option A: Quick check (try once)
      # Option B: Full installation verification
      
      # Option A (recommended): Quick check
      if timeout 3 python3 -c "import playwright" 2>/dev/null; then
        echo "✓ Playwright Python library installed"
        touch "$INSTALL_FLAG"
        return 0
      fi
      
      # Option B: Full verification (if needed)
      # pip3 install playwright
      # python3 -m playwright install chromium
  fi
}
```

**Platform and Content Detection**:
```bash
# Function: Platform type detection
detect_platform_type() {
  local url="$1"
  
  # Twitter/X: Always anti-crawler
  if [[ "$url" =~ (twitter\.com|x\.com) ]]; then
    echo "ANTICRAWLER_TWITTER"
    return 0
  
  # Other known anti-crawler platforms
  elif [[ "$url" =~ (linkedin\.com|facebook\.com|instagram\.com) ]]; then
    echo "ANTICRAWLER_OTHER"
    return 1
  
  # Open web (could support direct addition)
  else
    echo "OPEN_WEB"
    return 2
  fi
}
```
- **Browser-based extraction** for anti-crawler URLs (Twitter/X, LinkedIn, etc.):
  - Automatically detect protected platforms
  - Use Playwright automation to extract content
  - Save to `/tmp/` before adding to NotebookLM
  - No confirmation needed for extraction process

**Ask before running:**
- `notebooklm delete` - destructive
- `notebooklm generate *` - long-running, may fail
- `notebooklm download *` - writes to filesystem
- `notebooklm artifact wait` - long-running (when in main conversation)
- `notebooklm source wait` - long-running (when in main conversation)
- `notebooklm research wait` - long-running (when in main conversation)

## Quick Reference

| Task | Command |
|------|---------|
| Authenticate | `notebooklm login` |
| List notebooks | `notebooklm list` |
| Create notebook | `notebooklm create "Title"` |
| Set context | `notebooklm use <notebook_id>` |
| Show context | `notebooklm status` |
| Add URL source | `notebooklm source add "https://..."` |
| Add file | `notebooklm source add ./file.pdf` |
| Add YouTube | `notebooklm source add "https://youtube.com/..."` |
| Extract Twitter/X via browser | Use Playwright skill → Save → `notebooklm source add ./file.md` |
| Extract anti-crawler content | Use browser automation → Save → Add to notebook |
| List sources | `notebooklm source list` |
| Wait for source processing | `notebooklm source wait <source_id>` |
| Web research (fast) | `notebooklm source add-research "query"` |
| Web research (deep) | `notebooklm source add-research "query" --mode deep --no-wait` |
| Check research status | `notebooklm research status` |
| Wait for research | `notebooklm research wait --import-all` |
| Chat | `notebooklm ask "question"` |
| Chat (new conversation) | `notebooklm ask "question" --new` |
| Chat (specific sources) | `notebooklm ask "question" -s src_id1 -s src_id2` |
| Generate podcast | `notebooklm generate audio "instructions"` |
| Generate podcast (specific sources) | `notebooklm generate audio -s src_id1 -s src_id2` |
| Generate video | `notebooklm generate video "instructions"` |
| Generate quiz | `notebooklm generate quiz` |
| Check artifact status | `notebooklm artifact list` |
| Wait for completion | `notebooklm artifact wait <artifact_id>` |
| Download audio | `notebooklm download audio ./output.mp3` |
| Download video | `notebooklm download video ./output.mp4` |
| Delete notebook | `notebooklm notebook delete <id>` |

**Parallel safety:** Use explicit notebook IDs in parallel workflows. Commands supporting `-n` shorthand: `artifact wait`, `source wait`, `research wait/status`, `download *`. Other commands use `--notebook`. For chat, use `--new` to start