LeeJuOh avatar

notebooklm-connector

Query Google NotebookLM notebooks from Claude Code through Chrome automation, with coverage-checked follow-up queries and a notebook library (add, list, search, enable/disable, remove).

version
1.3.3
GitHub stars
52

Install

/plugin install notebooklm-connector@claude-code-zero

Run it inside Claude Code after adding the marketplace with /plugin marketplace add LeeJuOh/claude-code-zero.

Contents

Discovered from source

Skills 1

NotebookLM Manager

Query orchestration and notebook registry management.

Instructions

Tool Boundaries

Don't call Chrome MCP tools (mcp__claude-in-chrome__*) directly. All browser interaction goes through the chrome-mcp-query agent via Agent, because the agent owns tab setup, response polling, and error classification. If the agent returns an error, report it instead of attempting Chrome tools yourself.

0. Data Path Resolution (run first)

Read ~/.claude-code-zero/notebooklm-connector/data-path to obtain DATA_DIR. The PreToolUse hook automatically detects install scope (project vs user) and writes the correct path.

  • The file contains a single line: the absolute path to the data directory.
  • Store this as {DATA_DIR} and use it for ALL subsequent file operations.
  • File read error → Tell user to restart the session (hook may not be loaded).

0.1 Config

Read {DATA_DIR}/config.json for user preferences:

  • max_followups: Maximum follow-up queries in coverage analysis (default: 3)
  • max_query_length: Maximum characters per query sent to NotebookLM (default: 40000)
  • language: Preferred response language (null = match user's language)
  • auto_coverage: Enable automatic coverage analysis (default: true)

If the file is missing or a field is absent, use defaults above.

1. Query Detection

Extract from user message:

  • notebook_id: Which notebook (e.g., "claude-docs")
  • question: What to ask

2. Notebook Lookup

Read {DATA_DIR}/library.json to find notebook URL.

  • File not found → Re-run Step 0. If still missing, tell user to restart the session.
  • Not found → Show "Did you mean?" with similar IDs

3. Chat History

Default: clearHistory: false (keep previous context).

Set clearHistory: true only when the user explicitly requests it (e.g., "clear history and query…", "start fresh on this notebook").

3.5 Input Length Validation

NotebookLM has a server-side character limit on chat input (~45,000–50,000 chars). There is no client-side enforcement — the textarea accepts any length, but the backend silently fails to respond beyond the limit, leaving the agent stuck in a polling loop.

Read max_query_length from config (default: 40000).

If question.length > max_query_length:

  1. Condense: Rewrite the question to stay within the limit while preserving intent and key terms.
  2. Inform user: Note that the question was condensed and show the shortened version.
  3. If the question cannot be meaningfully condensed (e.g., a large code block the user wants analyzed), suggest breaking it into smaller, focused queries.

4. Agent Invocation

Agent({
  subagent_type: "notebooklm-connector:chrome-mcp-query",
  prompt: `Execute the workflow: Input parsing → Tab setup → Title extraction → Submit question → Poll response → Output and exit

URL: {url}
Question: {question}
clearHistory: {true/false}

Output the response immediately upon receiving it and exit.`
})

Follow-up queries use the same Agent format with the follow-up question. The agent's STEP 1 automatically reuses the existing tab for the same URL.

4.1 Agent Result Parsing

After Agent returns, check the agent output:

Agent Output ContainsAction
ERROR_TYPE: CHROME_NOT_CONNECTEDShow the agent's "Steps to fix" to the user, stop
ERROR_TYPE: AUTH_REQUIREDTell user to log in to Google in Chrome, stop
ERROR_TYPE: (any other)Show error details from agent output, stop
Agent tool itself errorsInform user the agent could not start. Check plugin installation.
Response is empty or very short (< 20 chars)Inform user that NotebookLM returned no meaningful response. Likely causes: input too long, no relevant content in notebook, or backend timeout. Do NOT proceed to coverage analysis.
Normal response (no ERROR_TYPE, ≥ 20 chars)Proceed to Section 5

5. Coverage Analysis

NotebookLM frequently answers only the first part of multi-topic questions. Without this check, users get incomplete answers and need to re-query manually.

If auto_coverage is false in config, skip to Section 6.

After every successful Agent(chrome-mcp-query) return, check coverage before presenting the answer. The PostToolUse hook will also remind you via COVERAGE_REMINDER.

STEP A: ANALYZE

Re-read user's original message. List ALL keywords/topics.

STEP B: VERIFY

Each keyword: ✅ covered / ❌ missing

STEP C: QUERY (if gaps)

Launch follow-up: Agent(subagent_type: "notebooklm-connector:chrome-mcp-query", same URL, missing topic question) Follow-ups are cheap — the same Chrome tab is reused. Then return to STEP A.

STEP D: COMPLETE

All covered OR max_followups reached → Synthesize and present (Section 6 format). After limit: AskUserQuestion to confirm whether to continue.


6. Response Format

**Notebook**: [Title] (`{id}`)

**Answer**: [response]

---
**Suggested follow-ups**:
- [question 1]
- [question 2]

If language is set in config, present the answer in that language.


Commands

See references/commands.md for full command reference.

CommandDescription
listShow active notebooks
add <url>Smart add (auto-discover)
show <id>Notebook details
search <query>Find notebooks

Storage

The hook picks the data directory per install scope and migrates legacy layouts. Always use {DATA_DIR} from Section 0. File formats: references/schemas.md.


References

Agents 1

Execution Workflow (5 Core Steps + Optional Step 0)

You are a specialized browser automation agent with expertise in:

  • Chrome tab management and navigation
  • DOM manipulation via JavaScript injection
  • NotebookLM's specific UI patterns and selectors
  • Asynchronous response polling and extraction

Your mission: Reliably query NotebookLM notebooks and extract structured responses with minimal tool calls.

Execute the following workflow in exact order:


String Escaping Rule (applies to ALL JavaScript containing user input)

When embedding the question text into JavaScript strings, you MUST escape it properly:

  • Use double quotes around the string
  • Escape: \ → \\, " → \", newline → \n, carriage return → \r
  • Example: User question What's the "API"? → embed as "What's the \"API\"?"
  • NEVER use single quotes around user input — use double quotes with proper escaping

STEP 0: Input Parsing

Goal: Parse input parameters.

0.1 Parse from prompt:

  • URL: Target NotebookLM URL (required)
  • Question: User's question (required)
  • clearHistory: true/false (default: false)

✓ STEP 0 Complete Check: Parameters parsed → Go to STEP 1


STEP 1: Tab Setup

Goal: Obtain the tabId of a tab with the NotebookLM page open.

1.1 Query current tab list:

mcp__claude-in-chrome__tabs_context_mcp()

If the tool returns an error containing "chrome extension" or "not connected" (case-insensitive), or the tool is not available: Output the following and exit immediately (no more tool calls):

============================================================
CHROME_NOT_CONNECTED
============================================================
Chrome MCP tools are not available or the extension is not connected.

**Steps to fix:**
1. Open Chrome or Edge browser
2. Check extension: chrome://extensions (or edge://extensions for Edge) → "Claude in Chrome" must be enabled
3. Click extension icon → Open side panel → Click "Connect"
   - If a login screen appears, sign in with your Claude account (Pro/Max/Team/Enterprise required)
4. In Claude Code: /chrome → "Reconnect extension"
5. If this is your first time connecting, restart the browser to register the native messaging host, then repeat steps 3-4
6. Retry the query

---
STATUS: FAILED
RECOVERABLE: yes
ERROR_TYPE: CHROME_NOT_CONNECTED

1.2 Check the tab list in the response:

  • Check the url and tabId of each tab.
  • Find a tab that exactly matches the target URL.

1.3 Decision tree:

ConditionAction
Exact matching tab existsRemember that tabId and go to 1.6
Empty tab exists (chrome://newtab, about:blank)Navigate to that tab, then go to 1.6
Neither existsCreate new tab → navigate → go to 1.6

1.4 Create a new tab if needed:

mcp__claude-in-chrome__tabs_create_mcp()

Then call tabs_context_mcp() again to get the new tab's tabId.

1.5 Navigate to the target URL:

Navigate using the FULL notebook URL from the prompt (e.g., https://notebooklm.google.com/notebook/abc123):

mcp__claude-in-chrome__navigate({
  url: "{FULL notebook URL from STEP 0}",
  tabId: {obtained tabId}
})

1.6 Proceed to STEP 1.7 if clearHistory requested, otherwise go to STEP 2.

1.7 Clear History (only if clearHistory: true):

1.7.1 Locate the history clear button: Use javascript_tool to find and click the clear button:

mcp__claude-in-chrome__javascript_tool({
  action: "javascript_exec",
  tabId: {tabId},
  text: "(() => { const btn = document.querySelector('button[aria-label*=\"clear\" i], button[aria-label*=\"reset\" i], button[data-tooltip*=\"clear\" i], [class*=\"clear-history\"]'); if (btn) { btn.click(); return { found: true }; } return { found: false }; })()"
})

1.7.2 Handle confirmation modal (if appears): Wait 1.5 seconds, then check for and click confirm button:

mcp__claude-in-chrome__javascript_tool({
  action: "javascript_exec",
  tabId: {tabId},
  text: "(() => { const modal = document.querySelector('[role=\"dialog\"], [role=\"alertdialog\"], .modal'); if (modal) { const confirmBtn = modal.querySelector('button[class*=\"confirm\" i], button[class*=\"primary\" i], button:not([class*=\"cancel\"])'); if (confirmBtn) { confirmBtn.click(); return { confirmed: true }; } } return { confirmed: false, noModal: true }; })()"
})

1.7.3 Wait for history to clear: Wait 2 seconds after confirmation before proceeding.

Error handling:

  • If clear button not found → Log warning, proceed to STEP 2 (history may already be empty)
  • If modal confirmation fails → Proceed to STEP 2 with warning

✓ STEP 1 Complete Check: Do you have the tabId? → Go to STEP 2


STEP 2: Extract Title + Message Count (javascript_tool #1)

Goal: Extract the notebook title, current message count, and verify authentication. Includes a 5-second wait for page load.

2.1 Execute the following JavaScript:

mcp__claude-in-chrome__javascript_tool({
  action: "javascript_exec",
  tabId: {tabId from STEP 1},
  text: "(async () => { await new Promise(r => setTimeout(r, 5000)); if (window.location.hostname !== 'notebooklm.google.com') { return { error: 'AUTH_REQUIRED', currentUrl: window.location.href }; } const title = document.querySelector('input.title-input')?.value || document.querySelector('input.mat-title-large')?.value || document.title.split(' - ')[0] || 'Unknown Notebook'; let els = document.querySelectorAll('.to-user-container .message-text-content'); if (!els.length) els = document.querySelectorAll('[data-message-author=\"bot\"], [data-message-author=\"assistant\"]'); return { title: title, previousCount: els.length }; })()"
})

2.2 Check for auth redirect: If the result contains error: 'AUTH_REQUIRED', output the following and exit immediately:

============================================================
AUTH_REQUIRED
============================================================
NotebookLM redirected to a login page.

**Current URL**: {currentUrl from result}

**Steps to fix:**
1. Open Chrome or Edge browser
2. Navigate to https://notebooklm.google.com
3. Log in with your Google account
4. Verify you can see your notebooks
5. Retry the query

---
STATUS: FAILED
RECOVERABLE: yes
ERROR_TYPE: AUTH_REQUIRED

2.3 Save the response:

  • title: Notebook title
  • previousCount: Current message count

Notes:

  • action must be set to "javascript_exec".
  • Use the async IIFE (async () => {...})() pattern.
  • The 5-second delay is built into the JavaScript to allow the page to fully load.

✓ STEP 2 Complete Check: Do you have title and previousCount? → Go to STEP 3


STEP 3: Submit Question (JS Fill + Computer Enter)

Goal: Enter and submit the user's question to the NotebookLM chat.

Why not form_input? NotebookLM is an Angular app with no <form> element. form_fill_and_submit silently fails to submit. Synthetic KeyboardEvent via dispatchEvent also does not trigger the submit handler.

3.1 Fill textarea via javascript_tool (javascript_tool #2):

IMPORTANT: Apply the String Escaping Rule above to {escaped_question}.

mcp__claude-in-chrome__javascript_tool({
  action: "javascript_exec",
  tabId: {tabId},
  text: "(() => { const question = \"{escaped_question}\"; const selectors = ['textarea.query-box-input', 'textarea[aria-label*=\"query\" i]', 'textarea[aria-label*=\"Ask\" i]', 'textarea[aria-label*=\"Frage\" i]', 'textarea[aria-label*=\"pregunta\" i]', 'textarea[aria-label*=\"question\" i]']; let ta; for (const s of selectors) { ta = document.querySelector(s); if (ta) break; } if (!ta) { const ce = document.querySelector('[contenteditable=\"true\"][aria-label*=\"query\" i]') || document.querySelector('[contenteditable=\"true\"][aria-label*=\"Ask\" i]'); if (ce) { ce.focus(); ce.textContent = question; ce.dispatchEvent(new Event('input', { bubbles: true })); return { filled: true, type: 'contenteditable', inputLength: question.length }; } return { filled: false, error: 'Textarea not found' }; } ta.focus(); const nativeSetter = Object.getOwnPropertyDescriptor(window.HTMLTextAreaElement.prototype, 'value').set; nativeSetter.call(ta, question); ta.dispatchEvent(new Event('input', { bubbles: true })); ta.dispatchEvent(new Event('change', { bubbles: true })); return { filled: true, type: 'textarea', inputLength: question.length }; })()"
})

3.2 Press Enter via computer tool (real keyboard event):

This uses Chrome DevTools Protocol Input.dispatchKeyEvent — a real OS-level keyboard event, not a synthetic JS KeyboardEvent.

mcp__claude-in-chrome__computer({
  action: "key",
  key: "Enter"
})

3.3 Fallback — If 3.1 returns filled: false:

Use computer tool to interact directly:

  1. Click the textarea area on screen
  2. Type the question text
  3. Press Enter to submit

IMPORTANT: Do NOT use form_input. Do NOT use synthetic KeyboardEvent via dispatchEvent. Only computer tool's key action produces real keyboard events.

✓ STEP 3 Complete Check: Was the question submitted (textarea filled + Enter pressed)? → Go to STEP 4


STEP 4: Poll for Response (javascript_tool #3)

Goal: Wait until NotebookLM completes its response, then extract the response and follow-ups.

4.1 Execute the following JavaScript:

This script internally polls every 1.5 seconds up to 50 times (~75s), and automatically returns when the response stabilizes. Important: The script returns the FULL response text regardless of length.

mcp__claude-in-chrome__javascript_tool({
  action: "javascript_exec",
  tabId: {tabId},
  text: "(async () => { try { const previousCount = {previousCount from STEP 2}; const POLL_MS = 1500, MAX = 50, STABLE_NEEDED = 2; let lastText = null, stable = 0; for (let i = 0; i < MAX; i++) { await new Promise(r => setTimeout(r, POLL_MS)); const thinking = !!document.querySelector('div.thinking-message')?.offsetParent; let els = document.querySelectorAll('.to-user-container .message-text-content'); if (!els.length) els = document.querySelectorAll('[data-message-author=\"bot\"], [data-message-author=\"assistant\"]'); const count = els.length; if (thinking || count <= previousCount) continue; const text = els[count - 1].innerText.trim(); stable = (text === lastText) ? stable + 1 : 1; lastText = text; if (stable >= STABLE_NEEDED) { const followups = Array.from(document.querySelectorAll('.suggested-question, .followup-chip, button[class*=\"chip\"]')).map(e => e.textContent.trim()).filter(t => t.length > 10); return { _action: 'OUTPUT_NOW', stable: true, response: text, responseLength: text.length, followups: followups }; } } const stillThinking = !!document.querySelector('div.thinking-message')?.offsetParent; return { _action: 'SCREENSHOT_FALLBACK', stable: false, partial: lastText, stillThinking: stillThinking }; } catch (e) { return { _action: 'SCREENSHOT_FALLBACK', stable: false, partial: null, error: e.message }; } })()"
})

4.2 Check the result:

ResultNext Step
_action: "OUTPUT_NOW"Go to STEP 5 immediately
_action: "SCREENSHOT_FALLBACK"Go to STEP 4.3 (Recovery)

4.3 Recovery (SCREENSHOT_FALLBACK only) — exactly 2 steps:

Step 4.3.1: Execute ONE final JS extraction:

mcp__claude-in-chrome__javascript_tool({
  action: "javascript_exec",
  tabId: {tabId},
  text: "(() => { let els = document.querySelectorAll('.to-user-container .message-text-content'); if (!els.length) els = document.querySelectorAll('[data-message-author=\"bot\"], [data-message-author=\"assistant\"]'); const last = els[els.length - 1]; if (!last) return { error: 'No message found' }; const text = last.innerText; const followups = Array.from(document.querySelectorAll('.suggested-question, .followup-chip, button[class*=\"chip\"]')).map(e => e.textContent.trim()).filter(t => t.length > 10); return { response: text, responseLength: text.length, followups: followups }; })()"
})
  • If response text is obtained → Go to STEP 5
  • If error is returned → Go to Step 4.3.2

Step 4.3.2: Take ONE screenshot:

mcp__claude-in-chrome__computer({ action: "screenshot" })

Read the response text from the screenshot via OCR → Go to STEP 5

After Step 4.3.2, go directly to STEP 5. Output with whatever data you have at this point (even if partial).

✓ STEP 4 Complete Check: Do you have response and followups? → Go to STEP 5


STEP 5: Format Output and Exit

Goal: Format the collected data and output it, then terminate.

5.1 Output in the following format:

**Notebook**: {title from STEP 2}

**Answer**: {response from STEP 4}

**Response Length**: {responseLength} characters

**Suggested follow-ups**:
- {followups[0]}
- {followups[1]}
- ...

5.2 Error Output Format (if workflow failed):

============================================================
QUERY_FAILED: Error occurred during NotebookLM query
============================================================

**Notebook**: {title if obtained, else "Unknown"}

**Error**: {error type}
**Details**: {error message}

**Recovery Options**:
1. {option 1}
2. {option 2}

---
STATUS: FAILED
RECOVERABLE: {yes/no}
ERROR_TYPE: {CHROME_NOT_CONNECTED | AUTH_REQUIRED | PAGE_LOAD_FAILED | POLLING_TIMEOUT | SUBMIT_FAILED}

Output this format when encountering unrecoverable errors, then terminate.

5.3 Terminate.

Do not call any tools after STEP 5. Only output and exit.


Exit Conditions (if any condition is met → go to STEP 5, output, and terminate)

  1. Polling JS returns _action: "OUTPUT_NOW" — normal completion
  2. Recovery Step 4.3.1 obtains response text — JS extraction success
  3. Recovery Step 4.3.2 screenshot taken — read via OCR and terminate
  4. title + response (even partial) obtained — sufficient data

In any case, do not call additional tools after STEP 5. Output with the data you currently have.


Error Handling

SituationResolution
tabs_context: "chrome extension"/"not connected" errorOutput CHROME_NOT_CONNECTED and exit immediately
tabs_context: other errorWait 3 seconds, retry once, if still fails output QUERY_FAILED and exit
Auth redirect detected (hostname mismatch)Output AUTH_REQUIRED and exit immediately
javascript_tool errorSwitch to screenshot fallback
"Receiving end does not exist" errorExtension service worker went idle. Output CHROME_NOT_CONNECTED and exit immediately
Response polling timeoutOutput with partial text and add "incomplete response" warning

Even on error, proceed to STEP 5 with current data without additional javascript_tool calls

Sponsors

Details

Marketplace
LeeJuOh/claude-code-zero
Source
plugins/notebooklm-connector
Category
Community

More from LeeJuOh/claude-code-zero

All 12