# platdrag/notebooklm-claude-skill architecture

> Architecture diagram of the GitHub repository platdrag/notebooklm-claude-skill, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/platdrag/notebooklm-claude-skill
- Repository: https://github.com/platdrag/notebooklm-claude-skill

## Overview

1. **What this repo is**
   - This is not a standalone application; it is a **Claude Code plugin package**.
   - The repository mainly contains **plugin metadata, two Claude skills, and a config template** that together enable NotebookLM-backed querying from inside Claude Code.

2. **Top-level architecture**
   - The repo has three functional areas:
     - **Plugin packaging** in `.claude-plugin/`
     - **Operational skills** in `skills/setup` and `skills/query`
     - **Project configuration template** in `templates/`
   - There is no backend service in this repo; the runtime work happens locally through Claude Code and an external Python CLI.

3. **Plugin distribution boundary**
   - `.claude-plugin/plugin.json` defines the plugin for Claude Code.
   - `.claude-plugin/marketplace.json` exposes it through a marketplace flow, so it can be installed via `/plugin install`.
   - This boundary matters because it separates **distribution/installation concerns** from the skill logic itself.

4. **User-facing command surface**
   - The repo exposes two slash commands:
     - `/notebooklm:setup`
     - `/notebooklm:query`
   - These map directly to the two skill folders under `skills/`.
   - Architecturally, these are the entry points into the system.

5. **Setup subsystem**
   - `skills/setup/SKILL.md` defines the interactive bootstrap flow.
   - Its responsibility is to prepare the local project for NotebookLM usage:
     - install the `notebooklm-py` CLI
     - authenticate with Google
     - discover available notebooks
     - write per-project configuration
   - This skill is the **configuration and onboarding boundary** between the user’s project and NotebookLM.

6. **Query subsystem**
   - `skills/query/SKILL.md` defines the retrieval flow for asking questions.
   - It consumes the project config created by setup and uses the configured notebook selection to route requests.
   - Its output is described as **structured JSON with inline citations and source passages**, which is the main data contract for downstream use inside Claude Code.

7. **Local project state**
   - The repository includes `templates/notebooklm-config.json`, which serves as a starter shape for the project-local config file.
   - The actual generated file lives at `<project>/.claude/notebooklm-config.json`.
   - This means notebook selection and query behavior are **per-project stateful**, not global.

8. **External runtime dependency**
   - The repo depends on the external Python CLI **`notebooklm-py`**.
   - That CLI is the execution bridge to Google NotebookLM, which is the actual source of grounded answers.
   - So the live architecture is: **Claude Code → skill logic → notebooklm-py CLI → Google NotebookLM**.

9. **Data flow**
   - The setup flow discovers notebooks and stores notebook IDs plus metadata in the project config.
   - The query flow reads that config, resolves the target notebook, and submits the user question.
   - NotebookLM returns cited source-grounded content, which the skill formats for Claude Code.
   - The key data boundary is the **config file**, which links human-friendly notebook names to NotebookLM notebook IDs.

10. **Operational characteristics**
   - The solution is intentionally **local and user-controlled**: no service account, no hosted API in this repo, and no repo-managed server.
   - Cross-platform behavior is explicitly supported for macOS, Linux, and Windows.
   - The setup skill also accounts for environment differences such as Windows UTF-8 handling.

11. **Repository structure and maintainability**
   - The codebase is small and declarative, optimized for distribution rather than heavy implementation.
   - Most behavior is encoded in skill documentation rather than traditional source files.
   - For diagramming purposes, treat this repo as a **Claude Code extension package with local config plus an external NotebookLM integration**, not as a conventional app stack.

Main entry points: [`skills/query/SKILL.md`](https://github.com/platdrag/notebooklm-claude-skill/blob/master/skills/query/SKILL.md) (Query skill), [`skills/setup/SKILL.md`](https://github.com/platdrag/notebooklm-claude-skill/blob/master/skills/setup/SKILL.md) (Setup skill), [`.claude-plugin/plugin.json`](https://github.com/platdrag/notebooklm-claude-skill/blob/master/.claude-plugin/plugin.json) (plugin.json), [`templates/notebooklm-config.json`](https://github.com/platdrag/notebooklm-claude-skill/blob/master/templates/notebooklm-config.json) (Config template)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_distribution["Distribution"]
  node_plugin_json["plugin.json<br/>plugin manifest<br/>[plugin.json]"]
  node_marketplace_json["marketplace.json<br/>marketplace metadata<br/>[marketplace.json]"]
end

subgraph group_entrypoints["Commands"]
  node_setup_cmd["/notebooklm:setup<br/>slash command"]
  node_query_cmd["/notebooklm:query<br/>slash command"]
end

subgraph group_skills["Skills"]
  node_setup_skill["Setup skill<br/>bootstrap flow<br/>[SKILL.md]"]
  node_query_skill["Query skill<br/>retrieval flow<br/>[SKILL.md]"]
end

subgraph group_state["Project State"]
  node_config_template["Config template<br/>starter config"]
  node_project_config["Project config<br/>local state"]
end

subgraph group_external["External Runtime"]
  node_notebooklm_py["notebooklm-py<br/>python CLI"]
  node_google_notebooklm[("NotebookLM<br/>external service")]
end

node_claude_code["Claude Code<br/>host runtime"]

node_claude_code -->|"loads"| node_plugin_json
node_claude_code -->|"installs via"| node_marketplace_json
node_plugin_json -->|"exposes"| node_setup_cmd
node_plugin_json -->|"exposes"| node_query_cmd
node_setup_cmd -->|"invokes"| node_setup_skill
node_query_cmd -->|"invokes"| node_query_skill
node_setup_skill -->|"uses"| node_notebooklm_py
node_setup_skill -->|"starts from"| node_config_template
node_setup_skill -->|"writes"| node_project_config
node_config_template -->|"materializes as"| node_project_config
node_query_skill -->|"reads"| node_project_config
node_query_skill -->|"uses"| node_notebooklm_py
node_notebooklm_py -->|"queries"| node_google_notebooklm
node_project_config -.->|"selects notebook"| node_query_skill
node_query_skill -->|"returns cited JSON"| node_claude_code

click node_plugin_json "https://github.com/platdrag/notebooklm-claude-skill/blob/master/.claude-plugin/plugin.json"
click node_marketplace_json "https://github.com/platdrag/notebooklm-claude-skill/blob/master/.claude-plugin/marketplace.json"
click node_setup_skill "https://github.com/platdrag/notebooklm-claude-skill/blob/master/skills/setup/SKILL.md"
click node_query_skill "https://github.com/platdrag/notebooklm-claude-skill/blob/master/skills/query/SKILL.md"
click node_config_template "https://github.com/platdrag/notebooklm-claude-skill/blob/master/templates/notebooklm-config.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_plugin_json,node_marketplace_json toneBlue
class node_setup_cmd,node_query_cmd toneAmber
class node_setup_skill,node_query_skill toneMint
class node_config_template,node_project_config toneRose
class node_notebooklm_py,node_google_notebooklm toneIndigo
class node_claude_code toneNeutral
```

## Components

### Distribution

Plugin packaging and marketplace metadata for Claude Code installation.

- [plugin.json](https://github.com/platdrag/notebooklm-claude-skill/blob/master/.claude-plugin/plugin.json): plugin manifest · Defines the Claude Code plugin package. · `.claude-plugin/plugin.json`
- [marketplace.json](https://github.com/platdrag/notebooklm-claude-skill/blob/master/.claude-plugin/marketplace.json): marketplace metadata · Publishes the plugin for install flow support. · `.claude-plugin/marketplace.json`

### Commands

User-facing slash commands that enter the skills.

- **/notebooklm:setup**: slash command · Entry point for bootstrapping local NotebookLM access.
- **/notebooklm:query**: slash command · Entry point for asking questions against a selected notebook.

### Skills

Operational flows for setup and querying.

- [Setup skill](https://github.com/platdrag/notebooklm-claude-skill/blob/master/skills/setup/SKILL.md): bootstrap flow · Interactive onboarding that installs, authenticates, discovers notebooks, and writes config. · `skills/setup/SKILL.md`
- [Query skill](https://github.com/platdrag/notebooklm-claude-skill/blob/master/skills/query/SKILL.md): retrieval flow · Reads project config, routes the question, and formats cited results. · `skills/query/SKILL.md`

### Project State

Per-project NotebookLM configuration created by setup and consumed by query.

- [Config template](https://github.com/platdrag/notebooklm-claude-skill/blob/master/templates/notebooklm-config.json): starter config · Template for the per-project NotebookLM configuration. · `templates/notebooklm-config.json`
- **Project config**: local state · Generated notebook selection and metadata stored under the project.

### External Runtime

Local CLI bridge and the NotebookLM service it reaches.

- **notebooklm-py**: python CLI · Local execution bridge between Claude Code and Google NotebookLM.
- **NotebookLM**: external service · The upstream source of grounded notebook answers and citations.

### Other components

- **Claude Code**: host runtime · The environment that loads the plugin and runs the slash commands.

## Connections

- Claude Code → plugin.json: loads · Claude Code consumes the plugin manifest to register the extension.
- Claude Code → marketplace.json: installs via · Marketplace metadata enables plugin installation flow.
- plugin.json → /notebooklm:setup: exposes · The plugin publishes the setup command surface.
- plugin.json → /notebooklm:query: exposes · The plugin publishes the query command surface.
- /notebooklm:setup → Setup skill: invokes · Setup command enters the onboarding skill.
- /notebooklm:query → Query skill: invokes · Query command enters the retrieval skill.
- Setup skill → notebooklm-py: uses · Setup delegates installation, auth, and notebook discovery to the CLI bridge.
- Setup skill → Config template: starts from · The template provides the expected config shape.
- Setup skill → Project config: writes · Setup creates or updates the project-local NotebookLM config.
- Config template → Project config: materializes as · Template content becomes the generated project configuration.
- Query skill → Project config: reads · Query resolves the selected notebook from project-local state.
- Query skill → notebooklm-py: uses · Query delegates the actual NotebookLM request to the CLI bridge.
- notebooklm-py → NotebookLM: queries · The local CLI reaches Google NotebookLM for grounded answers.
- Project config → Query skill: selects notebook · Stored notebook IDs and metadata determine which notebook is queried.
- Query skill → Claude Code: returns cited JSON · The skill formats structured answers for Claude Code consumption.