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 |
AUTHENTICATION.md
View on GitHub# Authentication Architecture
## Overview
This skill uses a **hybrid authentication approach** that combines the best of both worlds:
1. **Persistent Browser Profile** (`user_data_dir`) for consistent browser fingerprinting
2. **Manual Cookie Injection** from `state.json` for reliable session cookie persistence
## Why This Approach?
### The Problem
Playwright/Patchright has a known bug ([#36139](https://github.com/microsoft/playwright/issues/36139)) where **session cookies** (cookies without an `Expires` attribute) do not persist correctly when using `launch_persistent_context()` with `user_data_dir`.
**What happens:**
- ✅ Persistent cookies (with `Expires` date) → Saved correctly to browser profile
- ❌ Session cookies (without `Expires`) → **Lost after browser restarts**
**Impact:**
- Some Google auth cookies are session cookies
- Users experience random authentication failures
- "Works on my machine" syndrome (depends on which cookies Google uses)
### TypeScript vs Python
The **MCP Server** (TypeScript) can work around this by passing `storage_state` as a parameter:
```typescript
// TypeScript - works!
const context = await chromium.launchPersistentContext(userDataDir, {
storageState: "state.json", // ← Loads cookies including session cookies
channel: "chrome"
});
```
But **Python's Playwright API doesn't support this** ([#14949](https://github.com/microsoft/playwright/issues/14949)):
```python
# Python - NOT SUPPORTED!
context = playwright.chromium.launch_persistent_context(
user_data_dir=profile_dir,
storage_state="state.json", # ← Parameter not available in Python!
channel="chrome"
)
```
## Our Solution: Hybrid Approach
We use a **two-phase authentication system**:
### Phase 1: Setup (`auth_manager.py setup`)
1. Launch persistent context with `user_data_dir`
2. User logs in manually
3. **Save state to TWO places:**
- Browser profile directory (automatic, for fingerprint + persistent cookies)
- `state.json` file (explicit save, for session cookies)
```python
context = playwright.chromium.launch_persistent_context(
user_data_dir="browser_profile/",
channel="chrome"
)
# User logs in...
context.storage_state(path="state.json") # Save all cookies
```
### Phase 2: Runtime (`ask_question.py`)
1. Launch persistent context with `user_data_dir` (loads fingerprint + persistent cookies)
2. **Manually inject cookies** from `state.json` (adds session cookies)
```python
# Step 1: Launch with browser profile
context = playwright.chromium.launch_persistent_context(
user_data_dir="browser_profile/",
channel="chrome"
)
# Step 2: Manually inject cookies from state.json
with open("state.json", 'r') as f:
state = json.load(f)
context.add_cookies(state['cookies']) # ← Workaround for session cookies!
```
## Benefits
| Feature | Our Approach | Pure `user_data_dir` | Pure `storage_state` |
|---------|--------------|----------------------|----------------------|
| **Browser Fingerprint Consistency** | ✅ Same across restarts | ✅ Same | ❌ Changes each time |
| **Session Cookie Persistence** | ✅ Manual injection | ❌ Lost (bug) | ✅ Native support |
| **Persistent Cookie Persistence** | ✅ Automatic | ✅ Automatic | ✅ Native support |
| **Google Trust** | ✅ High (same browser) | ✅ High | ❌ Low (new browser) |
| **Cross-platform Reliability** | ✅ Chrome required | ⚠️ Chromium issues | ✅ Portable |
| **Cache Performance** | ✅ Keeps cache | ✅ Keeps cache | ❌ No cache |
## File Structure
```
~/.claude/skills/notebooklm/data/
├── auth_info.json # Metadata about authentication
├── browser_state/
│ ├── state.json # Cookies + localStorage (for manual injection)
│ └── browser_profile/ # Chrome user profile (for fingerprint + cache)
│ ├── Default/
│ │ ├── Cookies # Persistent cookies only (session cookies missing!)
│ │ ├── Local Storage/
│ │ └── Cache/
│ └── ...
```
## Why `state.json` is Critical
Even though we use `user_data_dir`, we **still need `state.json`** because:
1. **Session cookies** are not saved to the browser profile (Playwright bug)
2. **Manual injection** is the only reliable way to load session cookies
3. **Validation** - we can check if cookies are expired before launching
## Code References
**Setup:** `scripts/auth_manager.py:94-120`
- Lines 100-113: Launch persistent context with `channel="chrome"`
- Line 167: Save to `state.json` via `context.storage_state()`
**Runtime:** `scripts/ask_question.py:77-118`
- Lines 86-99: Launch persistent context
- Lines 101-118: Manual cookie injection workaround
**Validation:** `scripts/auth_manager.py:236-298`
- Lines 262-275: Launch persistent context
- Lines 277-287: Manual cookie injection for validation
## Related Issues
- [microsoft/playwright#36139](https://github.com/microsoft/playwright/issues/36139) - Session cookies not persisting
- [microsoft/playwright#14949](https://github.com/microsoft/playwright/issues/14949) - Storage state with persistent context
- [StackOverflow Question](https://stackoverflow.com/questions/79641481/) - Session cookie persistence issue
## Future Improvements
If Playwright adds support for `storage_state` parameter in Python's `launch_persistent_context()`, we can simplify to:
```python
# Future (when Python API supports it):
context = playwright.chromium.launch_persistent_context(
user_data_dir="browser_profile/",
storage_state="state.json", # ← Would handle everything automatically!
channel="chrome"
)
```
Until then, our hybrid approach is the most reliable solution.
Related 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 |