guanyang/open-agent-hub / skills/notebooklm
notebooklm
UnverifiedUse this skill to query your Google NotebookLM notebooks directly from Claude Code for source-grounded, citation-backed answers from Gemini. Browser automation, library management, persistent auth. Drastically reduced hallucinations through document-only responses.
| File | Kind | Size |
|---|---|---|
| .gitignoreexecutable | script | 723 B |
| AUTHENTICATION.mdexecutable | script | 5.6 KB |
| CHANGELOG.mdexecutable | script | 1.7 KB |
| LICENSEexecutable | script | 1.0 KB |
| README.md | markdown | 15.7 KB |
| SKILL.mdexecutable | skill md | 9.2 KB |
| images/example_notebookchat.pngexecutable | binary | 134.3 KB |
| references/api_reference.mdexecutable | script | 7.5 KB |
| references/troubleshooting.mdexecutable | script | 8.8 KB |
| references/usage_patterns.mdexecutable | script | 9.3 KB |
| requirements.txtexecutable | manifest | 325 B |
| scripts/__init__.pyexecutable | script | 2.6 KB |
| scripts/ask_question.pyexecutable | script | 8.0 KB |
| scripts/auth_manager.pyexecutable | script | 11.3 KB |
| scripts/browser_session.pyexecutable | script | 8.5 KB |
| scripts/browser_utils.pyexecutable | script | 3.4 KB |
| scripts/cleanup_manager.pyexecutable | script | 9.5 KB |
| scripts/config.pyexecutable | script | 1.2 KB |
| scripts/notebook_manager.pyexecutable | script | 13.5 KB |
| scripts/run.pyexecutable | script | 2.9 KB |
| scripts/setup_environment.pyexecutable | script | 7.0 KB |
references/api_reference.md
View on GitHub# NotebookLM Skill API Reference
Complete API documentation for all NotebookLM skill modules.
## Important: Always Use run.py Wrapper
**All commands must use the `run.py` wrapper to ensure proper environment:**
```bash
# ✅ CORRECT:
python scripts/run.py [script_name].py [arguments]
# ❌ WRONG:
python scripts/[script_name].py [arguments] # Will fail without venv!
```
## Core Scripts
### ask_question.py
Query NotebookLM with automated browser interaction.
```bash
# Basic usage
python scripts/run.py ask_question.py --question "Your question"
# With specific notebook
python scripts/run.py ask_question.py --question "..." --notebook-id notebook-id
# With direct URL
python scripts/run.py ask_question.py --question "..." --notebook-url "https://..."
# Show browser (debugging)
python scripts/run.py ask_question.py --question "..." --show-browser
```
**Parameters:**
- `--question` (required): Question to ask
- `--notebook-id`: Use notebook from library
- `--notebook-url`: Use URL directly
- `--show-browser`: Make browser visible
**Returns:** Answer text with follow-up prompt appended
### notebook_manager.py
Manage notebook library with CRUD operations.
```bash
# Smart Add (discover content first)
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]"
# Then add with discovered info
python scripts/run.py notebook_manager.py add \
--url "https://notebooklm.google.com/notebook/..." \
--name "Name" \
--description "Description" \
--topics "topic1,topic2"
# Direct add (when you know the content)
python scripts/run.py notebook_manager.py add \
--url "https://notebooklm.google.com/notebook/..." \
--name "Name" \
--description "What it contains" \
--topics "topic1,topic2"
# List notebooks
python scripts/run.py notebook_manager.py list
# Search notebooks
python scripts/run.py notebook_manager.py search --query "keyword"
# Activate 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
# Show statistics
python scripts/run.py notebook_manager.py stats
```
**Commands:**
- `add`: Add notebook (requires --url, --name, --topics)
- `list`: Show all notebooks
- `search`: Find notebooks by keyword
- `activate`: Set default notebook
- `remove`: Delete from library
- `stats`: Display library statistics
### auth_manager.py
Handle Google authentication and browser state.
```bash
# Setup (browser visible for login)
python scripts/run.py auth_manager.py setup
# Check status
python scripts/run.py auth_manager.py status
# Re-authenticate
python scripts/run.py auth_manager.py reauth
# Clear authentication
python scripts/run.py auth_manager.py clear
```
**Commands:**
- `setup`: Initial authentication (browser MUST be visible)
- `status`: Check if authenticated
- `reauth`: Clear and re-setup
- `clear`: Remove all auth data
### cleanup_manager.py
Clean skill data with preservation options.
```bash
# Preview cleanup
python scripts/run.py cleanup_manager.py
# Execute cleanup
python scripts/run.py cleanup_manager.py --confirm
# Keep library
python scripts/run.py cleanup_manager.py --confirm --preserve-library
# Force without prompt
python scripts/run.py cleanup_manager.py --confirm --force
```
**Options:**
- `--confirm`: Actually perform cleanup
- `--preserve-library`: Keep notebook library
- `--force`: Skip confirmation prompt
### run.py
Script wrapper that handles environment setup.
```bash
# Usage
python scripts/run.py [script_name].py [arguments]
# Examples
python scripts/run.py auth_manager.py status
python scripts/run.py ask_question.py --question "..."
```
**Automatic actions:**
1. Creates `.venv` if missing
2. Installs dependencies
3. Activates environment
4. Executes target script
## Python API Usage
### Using subprocess with run.py
```python
import subprocess
import json
# Always use run.py wrapper
result = subprocess.run([
"python", "scripts/run.py", "ask_question.py",
"--question", "Your question",
"--notebook-id", "notebook-id"
], capture_output=True, text=True)
answer = result.stdout
```
### Direct imports (after venv exists)
```python
# Only works if venv is already created and activated
from notebook_manager import NotebookLibrary
from auth_manager import AuthManager
library = NotebookLibrary()
notebooks = library.list_notebooks()
auth = AuthManager()
is_auth = auth.is_authenticated()
```
## Data Storage
Location: `~/.claude/skills/notebooklm/data/`
```
data/
├── library.json # Notebook metadata
├── auth_info.json # Auth status
└── browser_state/ # Browser cookies
└── state.json
```
**Security:** Protected by `.gitignore`, never commit.
## Environment Variables
Optional `.env` file configuration:
```env
HEADLESS=false # Browser visibility
SHOW_BROWSER=false # Default display
STEALTH_ENABLED=true # Human behavior
TYPING_WPM_MIN=160 # Typing speed
TYPING_WPM_MAX=240
DEFAULT_NOTEBOOK_ID= # Default notebook
```
## Error Handling
Common patterns:
```python
# Using run.py prevents most errors
result = subprocess.run([
"python", "scripts/run.py", "ask_question.py",
"--question", "Question"
], capture_output=True, text=True)
if result.returncode != 0:
error = result.stderr
if "rate limit" in error.lower():
# Wait or switch accounts
pass
elif "not authenticated" in error.lower():
# Run auth setup
subprocess.run(["python", "scripts/run.py", "auth_manager.py", "setup"])
```
## Rate Limits
Free Google accounts: 50 queries/day
Solutions:
1. Wait for reset (midnight PST)
2. Switch accounts with `reauth`
3. Use multiple Google accounts
## Advanced Patterns
### Parallel Queries
```python
import concurrent.futures
import subprocess
def query(question, notebook_id):
result = subprocess.run([
"python", "scripts/run.py", "ask_question.py",
"--question", question,
"--notebook-id", notebook_id
], capture_output=True, text=True)
return result.stdout
# Run multiple queries simultaneously
with concurrent.futures.ThreadPoolExecutor(max_workers=3) as executor:
futures = [
executor.submit(query, q, nb)
for q, nb in zip(questions, notebooks)
]
results = [f.result() for f in futures]
```
### Batch Processing
```python
def batch_research(questions, notebook_id):
results = []
for question in questions:
result = subprocess.run([
"python", "scripts/run.py", "ask_question.py",
"--question", question,
"--notebook-id", notebook_id
], capture_output=True, text=True)
results.append(result.stdout)
time.sleep(2) # Avoid rate limits
return results
```
## Module Classes
### NotebookLibrary
- `add_notebook(url, name, topics)`
- `list_notebooks()`
- `search_notebooks(query)`
- `get_notebook(notebook_id)`
- `activate_notebook(notebook_id)`
- `remove_notebook(notebook_id)`
### AuthManager
- `is_authenticated()`
- `setup_auth(headless=False)`
- `get_auth_info()`
- `clear_auth()`
- `validate_auth()`
### BrowserSession (internal)
- Handles browser automation
- Manages stealth behavior
- Not intended for direct use
## Best Practices
1. **Always use run.py** - Ensures environment
2. **Check auth first** - Before operations
3. **Handle rate limits** - Implement retries
4. **Include context** - Questions are independent
5. **Clean sessions** - Use cleanup_managerRelated skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |