Skip to content
Back to search

notebooklm

Install, authenticate, troubleshoot, and operate Gemini Notebook through the notebooklm-py CLI or typed async Python API. Use for notebook and source management, grounded chat and research, and artifact generation or download when the user mentions Gemini Notebook, notebooklm-py, the notebooklm CLI, or its Python API. Do not use for the generic Gemini API or unrelated content creation.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026. Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/teng-lin/notebooklm-py with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/teng-lin/notebooklm-py'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/teng-lin-notebooklm-py/badge.svg)](/listings/teng-lin-notebooklm-py)

HTML

<a href="/listings/teng-lin-notebooklm-py"><img src="/api/listings/teng-lin-notebooklm-py/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

The full install guide — six personas (agent, end-user, library, headless, contributor, power-user), optional extras matrix, platform notes — lives in **[docs/installation.md](docs/installation.md)**.

**Quickest start** (CLI users and AI agents) — install the CLI with `uv tool` (recommended) or `pipx`:

uv tool install "notebooklm-py[browser]"   # or: pipx install "notebooklm-py[browser]"
notebooklm login                           # first run auto-downloads Chromium (~170 MB), then Google sign-in
notebooklm auth check --test --json        # verify: expect "status": "ok"

**Why `uv tool` / `pipx`?** They install the CLI into its own isolated environment and put `notebooklm` on your `PATH` — no dependency clashes with other tools, a one-line upgrade (`uv tool upgrade notebooklm-py`) or uninstall, and, crucially, they work on modern macOS (Homebrew Python) and Debian/Ubuntu where a system-wide `pip install` is blocked with `error: externally-managed-environment` ([PEP 668](https://peps.python.org/pep-0668/)). No `uv` yet? `curl -LsSf https://astral.sh/uv/install.sh | sh` (or `brew install uv` / `winget install astral-sh.uv`).

**Prefer plain `pip`?** It works the same **inside a virtualenv** (and directly on Windows, where Python isn't externally-managed):

python3 -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install "notebooklm-py[browser]"

**As a library** (embedded in your app — no Playwright, no Chromium):

uv add notebooklm-py                    # or, inside a virtualenv: pip install notebooklm-py

If `playwright install chromium` fails on Linux with `TypeError: onExit is not a function`, see the [Linux workaround](docs/troubleshooting.md#linux). **Contributors:** see [CONTRIBUTING.md](CONTRIBUTING.md).

Authentication & Access

Flexible auth for local dev, headless servers, and multi-tenant setups:

- **Three ways to get cookies** - Interactive Playwright login (default), import from an already-signed-in browser (`login --browser-cookies chrome`, no Playwright), or a durable **master token**. - **Master-token auth** - Mints fresh web cookies **on demand** with no per-session browser (`login --master-token --account you@example.com`), so it self-heals expired sessions unattended — the auth model for servers, CI, and the remote MCP connector (claude.ai / ChatGPT). - **Multi-account profiles** - Switch between Google accounts without re-authenticating.

Agent Setup

**Option 1 — CLI install**:

notebooklm skill install

Installs the skill into `~/.claude/skills/notebooklm` and `~/.agents/skills/notebooklm`.

**Option 2 — `npx` install** (via the open skills ecosystem):

npx skills add teng-lin/notebooklm-py

Fetches the canonical [SKILL.md](SKILL.md) directly from GitHub.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 315 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. ---
  2. name: notebooklm
  3. description: Install, authenticate, troubleshoot, and operate Gemini Notebook through the notebooklm-py CLI or typed async Python API. Use for notebook and source management, grounded chat and research, and artifact generation or download when the user mentions Gemini Notebook, notebooklm-py, the notebooklm CLI, or its Python API. Do not use for the generic Gemini API or unrelated content creation.
  4. ---
  5. # Gemini Notebook Automation
  6. Use the `notebooklm` CLI for agent workflows. Prefer `--json` and explicit IDs so every
  7. operation is inspectable and safe under concurrency. Use the typed async Python API only when the
  8. user requests application code or the CLI cannot express the workflow. The readiness, identity,
  9. authorization, and credential-handling rules below apply to both interfaces.
  10. ## Setup and Authentication
  11. Requires Python 3.10+. Install the package in the user's existing environment; do not create a
  12. separate environment unless requested:
  13. ```bash
  14. pip install "notebooklm-py[browser]"
  15. pip install "notebooklm-py[cookies]" # optional browser-cookie extraction
  16. ```
  17. If system `pip` reports `externally-managed-environment`, do not use `--break-system-packages`.
  18. For CLI-only use, offer `uv tool install "notebooklm-py[browser]"` or the equivalent `pipx`
  19. command; for application code, use the user's active project environment.
  20. For unattended or headless work, prefer durable profile-backed master-token auth over a copied
  21. cookie snapshot. Install `pip install "notebooklm-py[headless]"`; the one-time automatic OAuth
  22. capture also needs `[browser]`. On a trusted workstation run
  23. `notebooklm login --master-token --account <email>`, then deploy `master_token.json`, not
  24. `storage_state.json`, to the selected profile. `NOTEBOOKLM_HOME` selects the private base directory
  25. and `NOTEBOOKLM_PROFILE` selects its profile; defaults resolve to
  26. `~/.notebooklm/profiles/default/master_token.json`.
  27. In CI, `NOTEBOOKLM_MASTER_TOKEN_JSON` is a secret-transport convention, not an environment variable
  28. the package reads directly. Write its exact value to the selected profile's `master_token.json`
  29. with mode `0600`, unset it, then run `notebooklm auth refresh` to mint `storage_state.json`. A
  30. sibling master token can automatically re-mint expired file-backed cookies. Inline
  31. `NOTEBOOKLM_AUTH_JSON` is only a short-lived fallback; it bypasses this recovery path.
  32. Use PyPI or a release tag, not an unreleased `main` checkout. When available, consult the
  33. [installation guide](https://github.com/teng-lin/notebooklm-py/blob/main/docs/installation.md).
  34. Before a workflow, verify real authentication rather than merely parsing the cookie file:
  35. ```bash
  36. notebooklm auth check --test --json
  37. ```
  38. Require `.status == "ok"` and `.checks.token_fetch == true`. If validation fails:
  39. - With a display, run `notebooklm login` and validate again.
  40. - In a headless environment, install `[cookies]` and use
  41. `notebooklm login --browser-cookies <browser>`. Use
  42. `notebooklm auth inspect --browser <browser>` first when account selection is unclear.
  43. - If previously valid cookies became stale, try `notebooklm auth refresh`; use
  44. `notebooklm auth refresh --browser-cookies <browser>` after signing back into the browser.
  45. The normal `--test` preflight may heal and persist refreshed cookies. Add `--passive` when the
  46. check must be strictly read-only, including the failure-diagnosis workflow below.
  47. `notebooklm status` reports selected-notebook context, not authentication.
  48. Treat both auth files as bearer credentials: never print, log, or commit them. A master token is a
  49. durable full-account credential that survives password changes; use a dedicated account, protect
  50. it in a secret store and as `0600` on disk, and explicitly revoke it if exposed.
  51. ## Operating Invariants
  52. 1. Use `--json` for discovery and mutations, then retain the returned full UUIDs. Important
  53. envelopes are `.notebook.id` from `create`, `.source.id` from `source add`, and `.task_id` from
  54. asynchronous generators. `generate mind-map` instead returns `mind_map`, `note_id`, and `kind`;
  55. both kinds return a finished result with no task ID or separate `artifact wait` step.
  56. 2. Pass `-n/--notebook <id>` on every notebook-scoped command in automation or concurrent work.
  57. Do not rely on `notebooklm use`. For every concurrent run, also set a unique
  58. `NOTEBOOKLM_PROFILE=agent-<id>` so context and profile writes are isolated. A new profile has no
  59. credentials: put a `master_token.json` copy in that profile and mint its storage before use.
  60. Never share one writable `storage_state.json` across agents.
  61. 3. After adding sources, retain every `.source.id`, then run `source wait` for each before chat or
  62. generation. The add envelope has no status. Require wait exit 0 and `status == "ready"`; let the
  63. waiter handle media-specific transient `error` rows.
  64. 4. After an asynchronous generator returns a task/artifact ID, pass it positionally to
  65. `artifact wait` with `-n <notebook_id>`. Download that exact artifact with
  66. `-a <artifact_id> -n <notebook_id>`; never select the latest visible artifact. Mind-map generation
  67. returns its completed result directly and does not need `artifact wait`.
  68. 5. For overlapping research runs, always pass `--run-id <research_run_id>`.
  69. 6. Use a host's background facility only when it actually exists. Keep wait and dependent download
  70. commands in one sequential job, and download only after the wait exits 0. Otherwise run in the
  71. foreground or return exact ID-pinned commands to the user.
  72. ## Authorization Boundaries
  73. Safe inspection and explicitly requested creation, source addition, chat, and prompt suggestion can
  74. run directly. Diagnose failures with read-only commands before attempting recovery.
  75. Obtain confirmation immediately before an action when it was not already clearly authorized:
  76. - destructive commands such as notebook/source/note/artifact/label/profile deletion, sharing
  77. removal, logout, clear, research cancellation, and `ask --new`;
  78. - `language set`, because the default mode changes the account-global output language (prefer a
  79. generation command's `--language` override);
  80. - generation or long foreground waits, which can take minutes and be rate-limited;
  81. - downloads, which write files;
  82. - `research wait --import-all`, which imports sources;
  83. - `ask --save-as-note` and `history --save`, which create notes.
  84. User intent, not the presence of a CLI prompt, is the authorization boundary. After authorization,
  85. pass `--yes`/`-y` where supported. Most destructive JSON commands refuse to prompt without it, but
  86. some, including `ask --new --json` and `share remove --json`, execute without prompting. Never
  87. treat prompt absence as consent.
  88. `research cancel` is fire-and-forget. After an authorized cancellation, verify the exact run with
  89. `notebooklm research status -n <notebook_id> --run-id <research_run_id> --json`.
  90. ## Command Discovery
  91. Use the installed CLI's help as the version-matched source of truth instead of guessing flags:
  92. ```bash
  93. notebooklm --help
  94. notebooklm source --help
  95. notebooklm research --help
  96. notebooklm generate --help
  97. notebooklm artifact --help
  98. notebooklm download --help
  99. ```
  100. Also inspect `notebooklm --version` and drill down to the exact command, such as
  101. `notebooklm generate audio --help`, whenever its help differs from this skill.
  102. Common operations:
  103. | Goal | Command |
  104. |---|---|
  105. | Check compute usage | `notebooklm usage --json`; `notebooklm usage --categories` for category availability and estimated costs |
  106. | List or create notebooks | `notebooklm list --json`; `notebooklm create "Title" --json` |
  107. | Add and wait for a source | `notebooklm source add <input> -n <nb> --json`; `notebooklm source wait <src> -n <nb>` |
  108. | URL recovery | `notebooklm source add <url> --fallback-fetch` |
  109. | Chat | `notebooklm ask "question" -n <nb> --json` |
  110. | Research | `notebooklm source add-research "query" -n <nb> --mode fast --json` (`deep` is also supported) |
  111. | List or wait for artifacts | `notebooklm artifact list -n <nb> --json`; `notebooklm artifact wait <id> -n <nb>` |
  112. | Generate | `notebooklm generate <type> ... -n <nb> --json` |
  113. | Download | `notebooklm download <type> <path> -n <nb> -a <artifact>` |
  114. For the full surface, consult the installed command help or, when available, the
  115. [CLI reference](https://github.com/teng-lin/notebooklm-py/blob/main/docs/cli-reference.md).
  116. For application code, use the baseline below and, when available, the
  117. [Python API guide](https://github.com/teng-lin/notebooklm-py/blob/main/docs/python-api.md).
  118. ## Canonical Source-to-Artifact Workflow
  119. Keep `{notebook_id}`, every `{source_id}`, and `{artifact_id}` from JSON output:
  120. An explicit request for this completed workflow authorizes its normal prerequisite waits, requested
  121. generation, and requested output file. Confirm only work not already authorized by that request.
  122. 1. `notebooklm create "Research: topic" --json`
  123. 2. `notebooklm source add <input> -n {notebook_id} --json` for each input.
  124. 3. Once the foreground wait is authorized, run
  125. `notebooklm source wait {source_id} -n {notebook_id} --timeout 600` for every captured source.
  126. 4. Once generation is authorized, generate the requested type. For audio:
  127. `notebooklm generate audio "instructions" -n {notebook_id} -s {source_id} --json`.
  128. Repeat `-s` for each selected source and capture `.task_id` as `{artifact_id}`.
  129. 5. Once the foreground wait is authorized, run
  130. `notebooklm artifact wait {artifact_id} -n {notebook_id} --timeout 1200`.
  131. 6. Once the output write is authorized, run
  132. `notebooklm download audio ./podcast.m4a -a {artifact_id} -n {notebook_id}`.
  133. For analysis without generation, replace steps 4-6 with an ID-pinned chat command only after every
  134. source is ready:
  135. ```bash
  136. notebooklm ask "Summarize the key arguments" -n {notebook_id} --json
  137. ```
  138. ## Deep Research
  139. Deep research can take 15-30+ minutes. Start it non-blocking and retain
  140. `.poll_task_id // .task_id` as `{research_run_id}`:
  141. ```bash
  142. notebooklm source add-research "query" -n {notebook_id} --mode deep --no-wait --json
  143. ```
  144. Import only after explicit authorization, pinning both IDs:
  145. ```bash
  146. notebooklm research wait -n {notebook_id} --run-id {research_run_id} \
  147. --import-all --timeout 1800 --json
  148. ```
  149. With `--import-all`, `--timeout` is a per-phase budget for polling and import retry, so this example
  150. can consume roughly 3600 seconds of host wall time.
  151. Retain newly created source IDs from `.imported_sources[].id` and wait for readiness before later
  152. chat or generation.
  153. ## Python API Baseline
  154. When the full API guide is unavailable, use the installed typed API and its docstrings; do not guess
  155. method names. Keep the same IDs and readiness gates as the CLI workflow:
  156. ```python
  157. import asyncio
  158. from notebooklm import NotebookLMClient
  159. async def main(url: str) -> None:
  160. async with NotebookLMClient.from_storage() as client:
  161. notebook = await client.notebooks.create("Research: topic")
  162. source = await client.sources.add_url(notebook.id, url)
  163. await client.sources.wait_until_ready(notebook.id, source.id, timeout=600)
  164. answer = await client.chat.ask(
  165. notebook.id, "Summarize the key arguments", source_ids=[source.id]
  166. )
  167. print(answer.answer)
  168. task = await client.artifacts.generate_audio(
  169. notebook.id,
  170. source_ids=[source.id],
  171. instructions="Focus on the key arguments",
  172. )
  173. final = await client.artifacts.wait_for_completion(notebook.id, task.task_id, timeout=1200)
  174. if not final.is_complete:
  175. raise RuntimeError(f"Generation ended with {final.status}: {final.error}")
  176. await client.artifacts.download_audio(
  177. notebook.id, "./podcast.m4a", artifact_id=task.task_id
  178. )
  179. asyncio.run(main("https://example.com"))
  180. ```
  181. `NotebookLMClient.from_storage()` is an async context manager and is not awaited. A client is
  182. re-entrant on one event loop but is not thread-safe; create one client per loop. Public namespaces
  183. include `notebooks`, `sources`, `chat`, `research`, `artifacts`, `mind_maps`, `notes`, `settings`,
  184. `sharing`, `labels`, and `collections`. Apply the authorization boundaries above before running
  185. state-changing, long-running, or file-writing calls.
  186. ## Generation Notes
  187. Available generators include `audio`, `video`, `slide-deck`, `infographic`, `report`, `mind-map`,
  188. `data-table`, `quiz`, and `flashcards`. Inspect `notebooklm generate <type> --help` because formats,
  189. styles, source selection, language, and retry support vary by type.
  190. Keep these non-obvious distinctions:
  191. - Mind map (`--kind interactive`, default) is an asynchronous studio artifact internally, but the
  192. CLI polls it to completion and returns `{mind_map, note_id, kind}`; do not run `artifact wait`.
  193. - Mind map (`--kind note-backed`) is server-synchronous. Both kinds accept `--instructions`;
  194. interactive applies it reliably, while the server may ignore it for note-backed maps.
  195. - `generate video --format cinematic` ignores `--style`, requires Google AI Ultra, and can take
  196. roughly 30-40 minutes.
  197. - Slide-deck has no orientation flag. Request portrait output in the description (for example,
  198. `9:16 portrait`); slide revision cannot change the deck's orientation.
  199. - For a custom report, pass the prompt as the positional description with `--format custom`;
  200. `--append` applies only to built-in report formats.
  201. For prompts too long or awkward for shell quoting, use `--prompt-file PATH` on `ask`,
  202. `source add-research`, and supported generators. It contains prompt text; upload source documents
  203. with `source add` instead.
  204. ## Output and Citations
  205. Use JSON structurally rather than parsing human output. Common lifecycle values are:
  206. - sources: `unknown`/`preparing`/`processing` -> `ready` or `error`; proceed only on `ready`;
  207. - artifacts: `pending`/`in_progress` -> `completed`, `failed`, or `removed`; `not_found` may be a
  208. brief listing lag. Proceed or download only on `completed`.
  209. Chat JSON includes `answer`, `conversation_id`, and `references[].source_id`. A reference's
  210. `start_char`/`end_char` are UTF-16 offsets into the structured source document, not flat
  211. `SourceFulltext.content`. In Python, use
  212. `from notebooklm import resolve_chat_reference_passage`, then call
  213. `await resolve_chat_reference_passage(client, notebook_id, reference)`; it uses the exact document
  214. range and falls back to `find_citation_context()` when necessary.
  215. ## Failure Handling
  216. On failure, run safe read-only diagnosis first:
  217. ```bash
  218. notebooklm auth check --test --passive --json
  219. notebooklm list --json
  220. notebooklm source list -n {notebook_id} --json
  221. notebooklm artifact list -n {notebook_id} --json
  222. notebooklm research status -n {notebook_id} --run-id {research_run_id} --json
  223. ```
  224. Inspect only the commands relevant to the failed workflow. Do not mutate state during diagnosis.
  225. - Exit 0 means success. Expected command failures use exit 1. A `source wait` timeout uses exit 2;
  226. `artifact wait` and `research wait` timeouts use exit 1.
  227. - Branch on exit code first. Ordinary handled JSON failures use `{error, code, message}`, while wait
  228. commands return domain envelopes such as `{"status": "timeout", "error": "..."}`.
  229. - On auth failure, revalidate `checks.token_fetch`; log in only if it is not `true`.
  230. - On a wait timeout, report it and inspect the exact source, artifact, or research run.
  231. - Generation is rate-limited by Google. Preserve the task ID, inspect status, and retry only when the
  232. user authorizes it; do not loop indefinitely. For an existing failed Studio artifact, inspect
  233. `notebooklm artifact retry <artifact_id> -n {notebook_id} --help` before retrying in place.
  234. - On a protocol error, record the installed version, exact command, relevant IDs, and redacted
  235. error. Check the project's issue tracker when network access exists; do not invent a workaround
  236. when it does not.
  237. Keep progress updates brief and include the relevant returned ID. Never expose credential contents.
  238. ## Skill Installation
  239. If this file is already inside an agent skill directory, the skill itself is installed. Otherwise:
  240. - `notebooklm skill install` installs or updates supported local skill targets.
  241. - `notebooklm skill package` builds an uploadable archive for sandboxed agent environments.
  242. - `notebooklm skill status --json` reports installed versions and `content_mismatch`.
README.md · README · 355 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # notebooklm-py
  2. <p align="left">
  3. <img src="https://raw.githubusercontent.com/teng-lin/notebooklm-py/main/notebooklm-py.png" alt="notebooklm-py logo" width="128">
  4. </p>
  5. **A Comprehensive Google Gemini Notebook Skill & Unofficial Python API.** Full programmatic access to NotebookLM's features—including capabilities the web UI doesn't expose—via Python, CLI, and AI agents like Claude Code, Codex, and OpenClaw.
  6. > **Note (July 2026):** Google rebranded **NotebookLM** to **[Gemini Notebook](https://blog.google/innovation-and-ai/products/gemini-notebook/notebooklm-gemini-notebook/)**. It remains the same standalone product (now also reachable inside the Gemini app), existing links redirect automatically, and this library drives the same underlying service and works unchanged. The package keeps the `notebooklm-py` name.
  7. [![PyPI version](https://img.shields.io/pypi/v/notebooklm-py.svg)](https://pypi.org/project/notebooklm-py/)
  8. [![Python Version](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14%20%7C%203.15-blue)](https://pypi.org/project/notebooklm-py/)
  9. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  10. [![Tests](https://github.com/teng-lin/notebooklm-py/actions/workflows/test.yml/badge.svg)](https://github.com/teng-lin/notebooklm-py/actions/workflows/test.yml)
  11. <p>
  12. <a href="https://trendshift.io/repositories/19116" target="_blank"><img src="https://trendshift.io/api/badge/repositories/19116" alt="teng-lin%2Fnotebooklm-py | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
  13. </p>
  14. **Source & Development**: <https://github.com/teng-lin/notebooklm-py>
  15. > **⚠️ Unofficial Library - Use at Your Own Risk**
  16. >
  17. > This library uses **undocumented Google APIs** that can change without notice.
  18. >
  19. > - **Not affiliated with Google** - This is a community project
  20. > - **APIs may break** - Google can change internal endpoints anytime
  21. > - **Rate limits apply** - Heavy usage may be throttled
  22. >
  23. > Best for prototypes, research, and personal projects. See [Troubleshooting](docs/troubleshooting.md) for debugging tips.
  24. ## What You Can Build
  25. 🤖 **AI Agent Tools** - Integrate NotebookLM into Claude Code, Codex, and other LLM agents. Ships with a root [NotebookLM skill](SKILL.md) for GitHub and `npx skills add` discovery, local `notebooklm skill install` support for Claude Code and `.agents` skill directories, and repo-level Codex guidance in [`AGENTS.md`](AGENTS.md).
  26. 📚 **Research Automation** - Bulk-import sources (URLs, PDFs, YouTube, Google Drive), run web/Drive research queries with auto-import, and extract insights programmatically. Build repeatable research pipelines.
  27. 🎙️ **Content Generation** - Generate Audio Overviews (podcasts), videos, slide decks, quizzes, flashcards, infographics, data tables, mind maps, and study guides. Full control over formats, styles, and output.
  28. 📥 **Downloads & Export** - Download all generated artifacts locally (MP3, MP4, PDF, PNG, CSV, JSON, Markdown). Export to Google Docs/Sheets. **Features the web UI doesn't offer**: batch downloads, quiz/flashcard export in multiple formats, mind map JSON extraction.
  29. ## Use Cases & Recipes
  30. NotebookLM is a **grounded** engine: Gemini does the heavy reading and answers from *your* sources with citations. The winning pattern is to let it do the expensive analysis while your agent (Claude Code, Codex, …) orchestrates and handles the final mile — using NotebookLM as a **zero-token synthesis + memory layer an agent drives in a loop**, and pulling structured artifacts **out** in bulk and in richer, scriptable formats. Recipes people build on top of this library, grouped by what they use NotebookLM *as*:
  31. **Spend fewer tokens** — let NotebookLM do the expensive thinking:
  32. - **🪙 Zero-token research offload** — Throw 30 documents into a notebook, let Gemini do the heavy analysis, and have your agent spend tokens only on the final polish. The agent just orchestrates (`create` → `source add` → `ask`); the reasoning happens server-side. *In the wild: [a four-workflow guide to stop Claude Code burning tokens on NotebookLM](https://x.com/hooeem/status/2042293751805329445).*
  33. - **🧠 Knowledge distillation → a permanent skill** — Run [Deep Research](docs/cli-reference.md#source-add-research) (`source add-research "your topic" --mode deep`) or load a doc corpus, let NotebookLM's Gemini condense it, and bake the result into a `SKILL.md` your agent loads at startup — **build once, reuse with zero runtime tokens or network calls**, git-versioned and immune to UI drift. A packaged domain expert without hand-curating sources. (Dumping raw docs into a skill flattens the hierarchy; NotebookLM condensing first is what makes it work.)
  34. - **✅ Self-validating skills** — Have NotebookLM generate the *eval set* — a quiz straight from your sources — to grade an agent skill against ground truth instead of test questions you'd bias yourself. Build the skill, run it against the NotebookLM-authored evals, iterate to a pass. *In the wild: [a skill that scored 4/10 on the first pass and 10/10 after one iteration, graded by a NotebookLM-generated quiz](https://x.com/nurijanian/status/2037136490157986277).*
  35. **Give your agent memory** — persistent, grounded recall:
  36. - **💾 Persistent cross-session memory** — Keep a "Master Brain" notebook; a wrap-up step appends each session's decisions and fixes as notes (`note create` / `ask --save-as-note`), and a line in your `CLAUDE.md` queries it (`ask`) at the start of the next session. Storage and recall live on Google's infrastructure.
  37. - **🧩 Grounded memory for coding agents** — Expose a notebook of your internal docs/RFCs/architecture over the [MCP server](docs/mcp-guide.md) (or plain `ask`) so an agent answers from *your* code with citations rather than plausible-sounding guesses — a zero-infra alternative to standing up your own vector DB and embedding pipeline. *In the wild: [turning a notebook into the source-grounded "project brain" a coding agent consults before it writes code](https://medium.com/@pradeep00271/every-software-project-needs-a-project-brain-5cbc33917160).*
  38. - **🪞 Query your own notes / journal** — Load years of daily notes, meeting logs, or a journal and `ask` for **cited** answers *across your own history* — surfacing long-term patterns a keyword search can't (e.g. a weekly summary synthesized from 282 daily notes, every claim linked back to the entry it came from). *In the wild: [chatting with a year of daily notes as a cited knowledge base](https://artemxtech.substack.com/p/notebooklm-has-a-knowledge-graph).*
  39. **Turn your sources into answers & artifacts** — cited responses, generated media, and exports:
  40. - **📞 Grounded knowledge base / troubleshooting oracle (RAG)** — Load product docs, FAQs, RFCs, and past tickets, then `ask --json` for **source-grounded, cited** answers for support, on-call, or internal Q&A. Or have an agent point it at an entire fast-moving tool's docs — more than the agent can hold in context — as a **troubleshooting oracle** it queries the moment it hits an error. *In the wild: [OpenClaw drove the library to scrape all 524 pages of `docs.openclaw.ai`, dedupe the duplicate translations, and audit it down to 269 clean sources (missing/extra/duplicate = 0)](https://x.com/onenewbite/status/2024819940327379286).*
  41. - **🔁 Multi-format content repurposing** — One source set, every format: `generate audio` (podcast), `generate video`, `generate slide-deck`, plus a `generate report` blog draft, `generate quiz`, and `generate flashcards` — fan a single notebook out across channels.
  42. - **📤 Bulk, scriptable exports** — Pull mind maps as JSON, flashcards/quizzes as JSON/Markdown/HTML, data tables as CSV, and reports as Markdown — **in bulk, to local files, straight into Anki, your mind-mapping tool, or a repo** (`download <type>` / `download <type> --all`). The programmatic "get data *out*" half of the library, not just "put sources in."
  43. - **🕸️ Obsidian / knowledge-graph sync** — Run the CLI from your vault root so downloaded artifacts (reports, mind-map JSON, transcripts) land as files in your knowledge graph; community skills built on this library even resolve NotebookLM's citation markers into Obsidian `[[wikilinks]]`. Pair with a podcast overview for an audio digest of your notes. *In the wild: ["Claude Code + NotebookLM + Obsidian = GOD MODE"](https://www.youtube.com/watch?v=kU3qYQ7ACMA).*
  44. **Run it unattended, at scale, or on the go** — scheduled, headless, and remote:
  45. - **🚨 Incident runbook generator** — On an alert, spin up a notebook of the relevant docs, ask targeted diagnostic questions, and generate a briefing-doc report (`generate report --format briefing-doc --wait`, then `download report`) as an automated runbook.
  46. - **📚 Curriculum / study-set builder** — Scrape a syllabus or developer roadmap, create one notebook per topic (with deliberate pacing to dodge rate limits), and bulk-generate podcasts, quizzes, and flashcards for each.
  47. - **📰 Scheduled audio briefings** — Pair `auth refresh --quiet` (cron/launchd/systemd) with `generate audio` to publish a fresh personalized briefing to a podcast feed on a schedule.
  48. - **📱 NotebookLM from your phone, agent-driven** — Self-host the [remote MCP connector](docs/mcp-guide.md#remote-deployment-docker--a-tunnel) behind a Cloudflare/Tailscale tunnel and add it as a custom connector **on the web** (claude.ai Connectors, or ChatGPT with Developer Mode). Then drive the full toolset — deep research, source ingestion, studio generation, cited Q&A — from the **claude.ai mobile app** on the go (ChatGPT's MCP connectors are web-only), chained with your other MCP tools, instead of app-hopping.
  49. These combine ordinary library primitives — see the [CLI Reference](docs/cli-reference.md) and [Python API](docs/python-api.md). The agent-side glue (skills, scheduling, vault layout) lives in your own setup, not this package. Per-notebook source counts depend on your Google account tier — split across notebooks if you hit a cap.
  50. **New here?** Start with a walkthrough: [Claude Code + NotebookLM = CHEAT CODE (video)](https://www.youtube.com/watch?v=usTeU4Uh0iM) · [5 demos + 50 use cases, with prompts](https://aiblewmymind.substack.com/p/notebooklm-claude-code-use-cases).
  51. ## Ways to Use
  52. | Method | Best For |
  53. |--------|----------|
  54. | **Python API** | Application integration, async workflows, custom pipelines |
  55. | **CLI** | Shell scripts, quick tasks, CI/CD automation |
  56. | **MCP Server** | Claude Desktop/Code, Codex, etc. — locally via stdio, or as a self-hosted remote connector (behind a Cloudflare/Tailscale tunnel) reachable from claude.ai and ChatGPT, mobile included. |
  57. | **REST Server** | Local automation over guarded HTTP routes without spawning a CLI process per call |
  58. | **Agent Integration** | Claude Code, Codex, LLM agents, natural language automation |
  59. REST and MCP servers support multiple profiles on either backend with `--profiles`
  60. (see the [MCP guide](docs/mcp-guide.md)). URL ingestion can optionally recover
  61. failed web pages with `source add --fallback-fetch`; install the `impersonate` and
  62. `markdown` extras and see the [CLI reference](docs/cli-reference.md#opt-in-url-recovery).
  63. ### API backends
  64. The default backend is the established Web (`batchexecute`) transport. This
  65. release also provides an opt-in Android backend that uses NotebookLM's mobile
  66. gRPC service and bearer authentication. Select it for the CLI with
  67. `--backend android` (or `NOTEBOOKLM_BACKEND=android`), or for the Python API
  68. with `NotebookLMClient.from_storage(backend="android")` / `NotebookLMClient(...,
  69. backend="android")`.
  70. Install the Android runtime explicitly; it is intentionally not included in
  71. the `all` extra:
  72. ```bash
  73. pip install "notebooklm-py[android,browser]"
  74. notebooklm login --master-token --account you@example.com
  75. notebooklm --backend android list --json
  76. ```
  77. Android reads `master_token.json` from the selected profile and mints
  78. short-lived mobile bearer tokens as needed, so typed namespace calls do not
  79. depend on a browser-cookie session, Web build labels, or Web RPC IDs. All
  80. eleven public namespaces are available without falling back to the Web
  81. transport. Because the durable master token is a powerful full-account
  82. credential, use a dedicated account and protect the profile carefully. See the
  83. [Android backend guide](docs/android/README.md) for setup and protocol details.
  84. ## Features
  85. ### Complete NotebookLM Coverage
  86. | Category | Capabilities |
  87. |----------|--------------|
  88. | **Notebooks** | Create, copy (including sources and Studio artifacts), list, rename, delete |
  89. | **Sources** | URLs, YouTube, files (PDF, text, Markdown, Word, EPUB, audio, video, images), Google Drive, pasted text; refresh, get guide/fulltext |
  90. | **Chat** | Questions, conversation history, custom personas, suggested starter prompts |
  91. | **Notes** | Create, list, rename, delete, save chat answers, save conversation history |
  92. | **Source Labels** | AI-generated or manual topic labels; add/remove source membership; filter sources by label |
  93. | **Research** | Web and Drive research agents (fast/deep modes) with auto-import |
  94. | **Sharing** | Public/private links, user permissions (viewer/editor), view level control |
  95. ### Content Generation (All Artifact Types)
  96. | Type | Options | Download Format |
  97. |------|---------|-----------------|
  98. | **Audio Overview** | 4 formats (deep-dive, brief, critique, debate), 3 lengths, 50+ languages | MP3 |
  99. | **Video Overview** | 4 formats (explainer, brief, cinematic, short), 8 visual styles (+ auto/custom), plus a dedicated `cinematic-video` CLI alias | MP4 |
  100. | **Slide Deck** | Detailed or presenter format, adjustable length; individual slide revision | PDF, PPTX |
  101. | **Infographic** | 3 orientations, 3 detail levels | PNG |
  102. | **Quiz** | Configurable quantity and difficulty | JSON, Markdown, HTML |
  103. | **Flashcards** | Configurable quantity and difficulty | JSON, Markdown, HTML |
  104. | **Report** | Briefing doc, study guide, blog post, or custom prompt | Markdown |
  105. | **Data Table** | Custom structure via natural language | CSV |
  106. | **Mind Map** | Hierarchical node tree — **two kinds**: note-backed JSON or the newer interactive studio map (`--kind` / `MindMapKind`) | JSON |
  107. ### Beyond the Web UI
  108. Programmatic, batch, and local-file capabilities the API/CLI make easy — several in richer formats, or at a scale, than clicking through the web app:
  109. - **Batch downloads** - Download all artifacts of a type at once
  110. - **Quiz/Flashcard export** - Get structured JSON, Markdown, or HTML files
  111. - **Mind map data extraction** - Export hierarchical JSON for visualization tools
  112. - **Data table CSV export** - Download structured tables as spreadsheets
  113. - **Slide deck as PPTX or PDF** - Download editable PowerPoint or PDF files
  114. - **Slide revision** - Modify individual slides with natural-language prompts
  115. - **Report template customization** - Append extra instructions to built-in format templates
  116. - **Save chat history to notes** - Persist a whole Q&A conversation (not just a single answer) as a notebook note
  117. - **Source fulltext access** - Retrieve the indexed text content of any source
  118. - **Programmatic sharing** - Manage permissions without the UI
  119. ## Installation
  120. The full install guide — six personas (agent, end-user, library, headless, contributor, power-user), optional extras matrix, platform notes — lives in **[docs/installation.md](docs/installation.md)**.
  121. **Quickest start** (CLI users and AI agents) — install the CLI with `uv tool` (recommended) or `pipx`:
  122. ```bash
  123. uv tool install "notebooklm-py[browser]" # or: pipx install "notebooklm-py[browser]"
  124. notebooklm login # first run auto-downloads Chromium (~170 MB), then Google sign-in
  125. notebooklm auth check --test --json # verify: expect "status": "ok"
  126. ```
  127. **Why `uv tool` / `pipx`?** They install the CLI into its own isolated environment and put `notebooklm` on your `PATH` — no dependency clashes with other tools, a one-line upgrade (`uv tool upgrade notebooklm-py`) or uninstall, and, crucially, they work on modern macOS (Homebrew Python) and Debian/Ubuntu where a system-wide `pip install` is blocked with `error: externally-managed-environment` ([PEP 668](https://peps.python.org/pep-0668/)). No `uv` yet? `curl -LsSf https://astral.sh/uv/install.sh | sh` (or `brew install uv` / `winget install astral-sh.uv`).
  128. **Prefer plain `pip`?** It works the same **inside a virtualenv** (and directly on Windows, where Python isn't externally-managed):
  129. ```bash
  130. python3 -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
  131. pip install "notebooklm-py[browser]"
  132. ```
  133. **As a library** (embedded in your app — no Playwright, no Chromium):
  134. ```bash
  135. uv add notebooklm-py # or, inside a virtualenv: pip install notebooklm-py
  136. ```
  137. If `playwright install chromium` fails on Linux with `TypeError: onExit is not a function`, see the [Linux workaround](docs/troubleshooting.md#linux). **Contributors:** see [CONTRIBUTING.md](CONTRIBUTING.md).
  138. ### Authentication & Access
  139. Flexible auth for local dev, headless servers, and multi-tenant setups:
  140. - **Three ways to get cookies** - Interactive Playwright login (default), import from an already-signed-in browser (`login --browser-cookies chrome`, no Playwright), or a durable **master token**.
  141. - **Master-token auth** - Mints fresh web cookies **on demand** with no per-session browser (`login --master-token --account you@example.com`), so it self-heals expired sessions unattended — the auth model for servers, CI, and the remote MCP connector (claude.ai / ChatGPT).
  142. - **Multi-account profiles** - Switch between Google accounts without re-authenticating.
  143. ### Agent Setup
  144. **Option 1 — CLI install**:
  145. ```bash
  146. notebooklm skill install
  147. ```
  148. Installs the skill into `~/.claude/skills/notebooklm` and `~/.agents/skills/notebooklm`.
  149. **Option 2 — `npx` install** (via the open skills ecosystem):
  150. ```bash
  151. npx skills add teng-lin/notebooklm-py
  152. ```
  153. Fetches the canonical [SKILL.md](SKILL.md) directly from GitHub.
  154. ## Quick Start
  155. <p align="center">
  156. <a href="https://asciinema.org/a/767284" target="_blank"><img src="https://raw.githubusercontent.com/teng-lin/notebooklm-py/main/docs/demo.png" alt="NotebookLM Session Demo" width="600" /></a>
  157. <br>
  158. <em>16-minute session compressed to 30 seconds</em>
  159. </p>
  160. ### CLI
  161. ```bash
  162. # 1. Authenticate (opens browser)
  163. notebooklm login
  164. # Or use Microsoft Edge (for orgs that require Edge for SSO)
  165. # notebooklm login --browser msedge
  166. # Or reuse cookies from an already-logged-in browser session
  167. # notebooklm login --browser-cookies chrome
  168. # notebooklm login --browser-cookies 'chrome::Profile 1' # one Chromium profile
  169. # (combine with --profile to populate a specific profile;
  170. # use --account / --all-accounts after auth inspect when several
  171. # Google accounts are signed in)
  172. # 2. Create a notebook and add sources
  173. notebooklm create "My Research"
  174. notebooklm use <notebook_id>
  175. notebooklm source add "https://en.wikipedia.org/wiki/Artificial_intelligence"
  176. notebooklm source add "./paper.pdf"
  177. # 3. Chat with your sources
  178. notebooklm ask "What are the key themes?"
  179. notebooklm ask --prompt-file ./long_question.txt # Read question from file
  180. # 4. Generate content (use --prompt-file for long prompts)
  181. notebooklm generate audio "make it engaging" --wait
  182. notebooklm generate video --style whiteboard --wait
  183. notebooklm generate cinematic-video "documentary-style summary" --wait
  184. notebooklm generate quiz --difficulty hard
  185. notebooklm generate flashcards --quantity more
  186. notebooklm generate slide-deck
  187. notebooklm generate infographic --orientation portrait
  188. notebooklm generate mind-map # interactive studio map (default); --kind note-backed for the JSON tree
  189. notebooklm generate data-table "compare key concepts"
  190. # 5. Download artifacts
  191. notebooklm download audio ./podcast.m4a
  192. notebooklm download video ./overview.mp4
  193. notebooklm download cinematic-video ./documentary.mp4
  194. notebooklm download quiz --format markdown ./quiz.md
  195. notebooklm download flashcards --format json ./cards.json
  196. notebooklm download slide-deck ./slides.pdf
  197. notebooklm download infographic ./infographic.png
  198. notebooklm download mind-map ./mindmap.json
  199. notebooklm download data-table ./data.csv
  200. ```
  201. Other useful CLI commands:
  202. ```bash
  203. notebooklm auth check --test # Diagnose auth/cookie issues
  204. notebooklm auth refresh --quiet # One-shot cookie keepalive (for cron / launchd / systemd)
  205. notebooklm auth refresh --browser-cookies chrome # Re-extract and repair account routing
  206. notebooklm auth inspect --browser 'chrome::Profile 1' # Preview one Chromium profile
  207. notebooklm agent show codex # Print bundled Codex instructions
  208. notebooklm agent show claude # Print bundled Claude Code skill template
  209. notebooklm language list # List supported output languages
  210. notebooklm metadata --json # Export notebook metadata and sources
  211. notebooklm usage # Show live compute usage and reset times
  212. notebooklm usage --json # Export the full usage snapshot, including categories
  213. notebooklm share status # Inspect sharing state
  214. notebooklm source add-research "AI" --import-all # web research + import found sources
  215. notebooklm skill status # Check local agent skill installation
  216. notebooklm profile list # List all Google account profiles
  217. notebooklm profile switch work # Switch active account profile
  218. ```
  219. Use `--prompt-file PATH` with `ask`, prompt-based `generate` commands, and `source add-research` when the text is too long for the shell command line. This reads prompt/query text from a file and is separate from `source add ./file.pdf`, which still uploads that file as a NotebookLM source.
  220. ### Python API
  221. ```python
  222. import asyncio
  223. from notebooklm import NotebookLMClient, MindMapKind
  224. async def main():
  225. async with NotebookLMClient.from_storage() as client:
  226. # Create notebook and add sources
  227. nb = await client.notebooks.create("Research")
  228. await client.sources.add_url(nb.id, "https://example.com", wait=True)
  229. # Chat with your sources
  230. result = await client.chat.ask(nb.id, "Summarize this")
  231. print(result.answer)
  232. # Generate content (podcast, video, quiz, etc.)
  233. status = await client.artifacts.generate_audio(nb.id, instructions="make it fun")
  234. await client.artifacts.wait_for_completion(nb.id, status.task_id)
  235. await client.artifacts.download_audio(nb.id, "podcast.m4a")
  236. # Generate quiz and download as JSON
  237. status = await client.artifacts.generate_quiz(nb.id)
  238. await client.artifacts.wait_for_completion(nb.id, status.task_id)
  239. await client.artifacts.download_quiz(nb.id, "quiz.json", output_format="json")
  240. # Generate a mind map via the unified client.mind_maps API (issue #1256) —
  241. # two kinds: the newer MindMapKind.INTERACTIVE studio map (shown; polled to
  242. # completion by default) or MindMapKind.NOTE_BACKED JSON. Both export via:
  243. mm = await client.mind_maps.generate(nb.id, kind=MindMapKind.INTERACTIVE)
  244. await client.artifacts.download_mind_map(nb.id, "mindmap.json", mm.id)
  245. asyncio.run(main())
  246. ```
  247. ## Documentation
  248. - **[Installation](docs/installation.md)** - Environment, extras, login, and deployment setup
  249. - **[Android Backend](docs/android/README.md)** - Mobile gRPC setup, credentials, and protocol notes
  250. - **[CLI Reference](docs/cli-reference.md)** - Complete command documentation
  251. - **[Python API](docs/python-api.md)** - Full API reference
  252. - **[MCP Guide](docs/mcp-guide.md)** - MCP server setup, transports, and tool reference
  253. - **[REST API Server](docs/installation.md#rest-api-server)** - Experimental localhost FastAPI server
  254. - **[Configuration](docs/configuration.md)** - Storage and settings
  255. - **[Quota & Tier Limits](docs/quota-limits.md)** - Per-tier notebook/source/studio limits and how they map to `AccountLimits.tier`
  256. - **[Release Guide](docs/releasing.md)** - Release checklist and packaging verification
  257. - **[Troubleshooting](docs/troubleshooting.md)** - Common issues and solutions
  258. - **[Credential Security](docs/security.md)** - Secret handling and trust boundaries
  259. - **[API Stability](docs/stability.md)** - Versioning policy and stability guarantees
  260. - **[Upgrading to v0.8.0](docs/upgrading-to-0.8.0.md)** - Breaking-change migration guide for the v0.8.0 error-and-return contract
  261. ### For Contributors
  262. - **[Architecture](docs/architecture.md)** - Architectural overview and design principles
  263. - **[Development Guide](docs/development.md)** - Architecture, testing, and releasing
  264. - **[RPC Development](docs/rpc-development.md)** - Protocol capture and debugging
  265. - **[RPC Reference](docs/rpc-reference.md)** - Payload structures
  266. - **[Changelog](CHANGELOG.md)** - Version history and release notes
  267. - **[Security](SECURITY.md)** - Security policy and credential handling
  268. ## License
  269. MIT License. See [LICENSE](LICENSE) for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.