notebooklm-py for Claude Code and Codex: drive NotebookLM from the command line

notebooklm-py is an unofficial library and skill for working with NotebookLM through a CLI and Python. It lets Claude Code or Codex add sources to a notebook, ask questions about them, and download what NotebookLM generates. This post covers the problem it solves, who it suits, how to install it and start a first run, and the one risk to weigh before you build on it.

What problem it solves

When you have a stack of research PDFs, the slow part is reading them closely enough to answer a specific question and point to where the answer came from. NotebookLM already does that reading and attaches citations to the originals. The trouble is that it lives in a browser, so an agent working in your terminal cannot hand it a batch of documents and collect the results.

notebooklm-py closes that gap. It moves the heavy reading to the service and gives the agent commands for each step, from adding sources to retrieving answers. Generated outputs come back as files: data tables as CSV, mind maps as JSON, reports as Markdown, and quizzes as JSON or HTML. The README notes that NotebookLM has been renamed Gemini Notebook but remains the same service. It lists Claude Code, Codex, and OpenClaw as supported tools and ships a root SKILL.md along with an AGENTS.md for Codex.

Who it fits

The chapter rates four situations. Three are enough to decide.

Situation	Fit	Reason
Querying a collection of research PDFs	Good fit	Returns cited answers as JSON
Creating a document comparison table as CSV	Good fit	Tables can be downloaded
Modeling raw data tables	Poor fit	Focuses on document queries

Answering from internal documents sits in the middle, because the unofficial API may change underneath you.

Install and first run

Install the CLI, log in, check authentication, and then install the skill.

# Install the CLI, log in, and install the skill
uv tool install "notebooklm-py[browser]"
notebooklm login
notebooklm auth check --test --json
notebooklm skill install

The README says you can use pipx instead of uv tool, or pip install in a virtual environment. The first login may require browser components.

Once the skill is installed, ask for an answer grounded in a specific notebook.

Answer [question] based on the sources in [notebook ID]

For automation, SKILL.md specifies an explicit notebook ID and uses --json output by default. The sequence the README and skill describe has three steps. You create a notebook and add URLs or PDFs with source add. You wait for processing with source wait before querying, so the question does not hit sources that are still loading. Then you use ask for answers based on those sources and download reports or data tables when you need them as files.

What trips people up

The catch is that the project runs on unpublished Google APIs. It is a community project, not affiliated with Google, and its internal endpoints may change without notice, so a pipeline that works today can break on a day you did not choose. The authentication side deserves the same caution. The master token used for unattended runs relates to permissions across the whole account, so the chapter recommends a dedicated account and protected authentication files. notebooklm auth check --test --json tests your login status, and its output and the files behind it should never be printed into logs or committed to a repository.

Where this comes from

This post adapts part of chapter 03-03 of The Claude Code & Codex Skills Guidebook. The full chapter covers the command table for generating, downloading, and checking usage, including bulk downloads of one output type, and how to handle source limits that vary by account, and the book has 52 more skills like this one. Read the full chapter in The Claude Code & Codex Skills Guidebook on Gumroad.