English | δΈζ
nblm
Your AI Coding Agent's Gateway to NotebookLM
π§ Zero Hallucinations β Answers grounded exclusively in your documents
β‘ Zero Context Switching β Ask, upload, generate podcasts & slides from your editor
π Infinite Sources β Z-Library today, arXiv / Notion / Confluence tomorrow
Works with Claude Code Β· Cursor Β· Windsurf Β· Codex Β· and any Agent Skills compatible agent
Installation Β· Quick Start Β· Commands Β· Architecture
Installation
Recommended: Using add-skill CLI
npx add-skill magicseek/nblm
This works with any supported agent. To install for a specific agent:
# Claude Code only
npx add-skill magicseek/nblm -a claude-code
# Global installation (available across all projects)
npx add-skill magicseek/nblm --global
# Multiple agents
npx add-skill magicseek/nblm -a claude-code -a cursor -a opencode
Alternative: Platform-specific initialization
If symlinks created by add-skill don't work well in your environment (e.g., Cursor, Windows), you can generate platform-specific files directly:
macOS / Linux:
# Clone the repo
git clone https://github.com/magicseek/nblm ~/.nblm
# Initialize for your AI assistant (run from your project directory)
python ~/.nblm/scripts/run.py init --ai cursor # Cursor
python ~/.nblm/scripts/run.py init --ai claude # Claude Code
python ~/.nblm/scripts/run.py init --ai codex # Codex CLI
python ~/.nblm/scripts/run.py init --ai antigravity # Antigravity
python ~/.nblm/scripts/run.py init --ai windsurf # Windsurf
python ~/.nblm/scripts/run.py init --ai copilot # GitHub Copilot
python ~/.nblm/scripts/run.py init --ai all # All platforms
# List available platforms
python ~/.nblm/scripts/run.py init --list
Windows (PowerShell):
# Clone the repo
git clone https://github.com/magicseek/nblm $env:USERPROFILE\.nblm
# Initialize for your AI assistant (run from your project directory)
python $env:USERPROFILE\.nblm\scripts\run.py init --ai cursor # Cursor
python $env:USERPROFILE\.nblm\scripts\run.py init --ai claude # Claude Code
python $env:USERPROFILE\.nblm\scripts\run.py init --ai codex # Codex CLI
python $env:USERPROFILE\.nblm\scripts\run.py init --ai antigravity # Antigravity
python $env:USERPROFILE\.nblm\scripts\run.py init --ai windsurf # Windsurf
python $env:USERPROFILE\.nblm\scripts\run.py init --ai copilot # GitHub Copilot
python $env:USERPROFILE\.nblm\scripts\run.py init --ai all # All platforms
# List available platforms
python $env:USERPROFILE\.nblm\scripts\run.py init --list
This generates the appropriate skill/command files in your project directory (e.g., .cursor/commands/nblm.md).
First Run
On first use, nblm automatically:
- Creates an isolated Python environment (
.venv) - Installs Python and Node.js dependencies
- Starts the agent-browser daemon as needed
No manual setup required. If Playwright browsers are missing, run npm run install-browsers in the skill folder.
Quick Start
1. Authenticate with Google (one-time)
/nblm login
A browser window opens for Google login. This is required once.
2. Add a notebook to your library
Go to notebooklm.google.com β Create notebook β Upload your docs β Share with "Anyone with link"
/nblm add <notebook-url-or-id>
nblm automatically queries the notebook to discover its content and metadata.
3. Ask questions
/nblm ask "What does the documentation say about authentication?"
Answers are source-grounded with citations from your uploaded documents.
4. Manage your notebooks
/nblm local # List notebooks in your library
/nblm remote # List all notebooks from NotebookLM API
/nblm status # Show auth and library status
5. Upload sources
/nblm upload ./document.pdf # Local file
/nblm upload-url https://example.com # Web URL
/nblm upload-zlib <z-library-url> # Z-Library book
Commands
π Notebook Management
| Command | Description |
|---|---|
/nblm login | Authenticate with Google |
/nblm accounts | List all Google accounts |
/nblm accounts add | Add a new Google account |
/nblm accounts switch <id> | Switch active account (by index or email) |
/nblm accounts remove <id> | Remove an account |
/nblm status | Show auth and library status |
/nblm local | List notebooks in local library |
/nblm remote | List all notebooks from NotebookLM API |
/nblm create <name> | Create a new notebook |
/nblm delete [--id ID] | Delete a notebook |
/nblm rename <name> [--id ID] | Rename a notebook |
/nblm summary [--id ID] | Get AI-generated summary |
/nblm describe [--id ID] | Get description and suggested topics |
/nblm add <url-or-id> | Add notebook to local library |
/nblm activate <id> | Set active notebook |
π Source Management
| Command | Description |
|---|---|
/nblm sources [--id ID] | List sources in notebook |
/nblm upload <file> | Upload local file (PDF, TXT, MD, DOCX) |
/nblm upload-zlib <url> | Download from Z-Library and upload |
/nblm upload-url <url> | Add URL as source |
/nblm upload-youtube <url> | Add YouTube video as source |
/nblm upload-text <title> [--content TEXT] | Add text as source |
/nblm source-text <source-id> | Get full indexed text |
/nblm source-guide <source-id> | Get AI summary and keywords |
/nblm source-rename <source-id> <name> | Rename a source |
/nblm source-refresh <source-id> | Re-fetch URL content |
/nblm source-delete <source-id> | Delete a source |
π¬ Chat & Query
| Command | Description |
|---|---|
/nblm ask <question> | Query NotebookLM |
ποΈ Media Generation
| Command | Description |
|---|---|
/nblm podcast [--instructions TEXT] | Generate audio podcast (deep-dive) |
/nblm podcast-status <task-id> | Check podcast generation status |
/nblm podcast-download [output-path] | Download latest podcast |
/nblm briefing [--instructions TEXT] | Generate brief audio summary |
/nblm debate [--instructions TEXT] | Generate debate-style audio |
/nblm slides [--instructions TEXT] | Generate slide deck |
/nblm slides-download [output-path] | Download slide deck as PDF |
/nblm infographic [--instructions TEXT] | Generate infographic |
/nblm infographic-download [output-path] | Download infographic |
/nblm media-list [--type TYPE] | List generated media |
/nblm media-delete <id> | Delete a generated media item |
Media generation options:
| Option | Values |
|---|---|
--length | SHORT, DEFAULT, LONG |
--instructions | Custom instructions for content |
--wait | Wait for generation to complete |
--output | Download path (requires --wait) |
Architecture
nblm uses a hybrid approach combining API-first operations with browser automation fallback:
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Your Agent β
β (Claude Code / Cursor / OpenCode) β
βββββββββββββββββββββββ¬ββββββββββββββββββββββββββββββββββββββββ
β /nblm commands
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β nblm β
βββββββββββββββββββββββ¬ββββββββββββββββββββββββββββββββββββββββ€
β notebooklm-py β agent-browser β
β (API operations) β (browser automation) β
β β β
β β’ Create notebooks β β’ Google authentication β
β β’ Add sources β β’ File uploads (fallback) β
β β’ Chat queries β β’ Z-Library downloads β
β β’ Generate media β β’ Future non-API sources β
βββββββββββββββββββββββ΄ββββββββββββββββββββββββββββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Google NotebookLM β
β (Gemini-powered document Q&A) β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Key components:
| Component | Role |
|---|---|
| notebooklm-py | Async Python client for NotebookLM API operations |
| agent-browser | Headless browser daemon for auth and non-API sources |
| scripts/run.py | Entry point that auto-manages venv and dependencies |
Data storage (in data/):
library.jsonβ Your notebook metadata (with account associations)auth/google/β Multi-account Google authenticationindex.jsonβ Account index and active account<n>-<email>.jsonβ Per-account credentials
auth/zlibrary.jsonβ Z-Library authentication state
Troubleshooting
| Problem | Solution |
|---|---|
| Skill not found | Verify installation: ls ~/.claude/skills/nblm/ |
ModuleNotFoundError | Always use /nblm commands β they auto-manage the environment |
| Authentication fails | Run /nblm login with a visible browser |
DAEMON_UNAVAILABLE | Ensure Node.js is installed, then run npm install in the skill folder |
| Rate limit (50/day) | Wait 24 hours or use a different Google account |
| Browser crashes | Run python scripts/run.py cleanup_manager.py --preserve-library |
For more details, see references/troubleshooting.md.
Acknowledgments
nblm builds upon the excellent work of these projects:
- notebooklm-skill by PleasePrompto β The original Claude Code skill for NotebookLM integration with browser automation
- zlibrary-to-notebooklm by zstmfhy β Z-Library to NotebookLM pipeline
- notebooklm-py by teng-lin β Async Python API client for NotebookLM
Additional dependencies:
- agent-browser β Headless browser daemon for AI agents
- add-skill β Universal skill installer for AI coding agents
Limitations
- Rate limits β Free tier allows ~50 queries/day per Google account (use multiple accounts to increase limits)
- No session persistence β Each query is independent (no "previous answer" context)
- Manual notebook creation β You must create notebooks and upload docs via notebooklm.google.com
License
MIT
nblm β Source-grounded answers from your documents, directly in your coding agent.