📓 Gemini Notebook by Chryzalide (agy-gemini-notebook-plugin)

Invoke and pilot Gemini Notebooks (NotebookLM & NotebookLM Enterprise) from Google Antigravity 2, VS Code, Cursor, Claude Code, and the CLI.

In the Gemini web app, users can attach a Gemini Notebook (NotebookLM) to a conversation for grounded, source-backed context. Gemini Notebook by Chryzalide (agy-gemini-notebook-plugin) is an independent, open-source community plugin that brings first-class Gemini Notebook integration—plus autonomous notebook piloting, Fast & Deep Research, and Studio Artifact generation—directly into Google Antigravity 2, VS Code, and any MCP-compatible agent harness.

🎬 Visual Overview & Interactive Demo

1. Autonomous Deep Research $\rightarrow$ Local Project .md Synthesis (agy-gemini-notebook)

2. Google Antigravity 2 Auxiliary Pane Sidecar UI (sidecar://gemini-notebook/notebook_context_panel/ui.html)

Related MCP server: notebooklm-mcp

✨ Key Features

• 🎯 Invoke Notebooks by ID, Alias, or Fuzzy Title (notebook_invoke & notebook_query):

  • Attach a default notebook (plus named aliases) to your repository via .agents/notebook.json.

  • Invoke any notebook on the fly by ID, workspace alias, or fuzzy title match—with optional one-step grounded Q&A and inline source citations.

• 🔬 Autonomous Fast & Deep Research (notebook_research):

  • Pilot NotebookLM's Fast Research (mode="fast"), Deep Research (mode="deep"), and Source Discovery (mode="discover") across the Web or Google Drive, and automatically import verified sources into your notebook.

• 📝 Documentary Research $\rightarrow$ Local Markdown Synthesis:

  • Turn research findings and curated notebook Q&A directly into structured, source-cited .md decision records and technical briefs inside your local project workspace.

• 🏢 Engine 1 — Official Google Cloud API (v1alpha Discovery Engine):

  • 100% official OAuth 2.0 authentication via gcloud auth print-access-token (no browser cookies required).

  • Create/get/delete/share notebooks, upload local files (sources:uploadFile), ingest URLs/YouTube/Drive (sources:batchCreate), generate Audio Overviews, and run Enterprise Grounded Q&A (servingConfigs:answer).

• 💬 Engine 2 — Full RPC Bridge (notebooklm-py for Consumer & Enterprise):

  • Automatic Dual-Engine fallback when GCP_PROJECT_NUMBER is not set—giving personal Google accounts (notebooklm.google.com) full CRUD, file uploads, source search, grounded Q&A with inline citations, Deep Research, Notes, and Studio Artifacts (Audio Overviews, Briefing Docs, Study Guides, Mind Maps, Quizzes, Flashcards, Slide Decks).

• 🖥️ Multi-Environment Ready (Antigravity 2 + VS Code + Cursor + CLI):

  • Antigravity 2 Plugin: Native MCP Server + Skill + Grounding Rule + Auxiliary Pane Sidecar UI (Gemini Notebook by Chryzalide).

  • VS Code / Cursor / Claude Code: Portable scripts/run_mcp.sh wrapper + MCP Resources (notebook://active) & Prompts (invoke_notebook, deep_research_notebook) + --transport stdio|sse|streamable-http.

  • Standalone CLI (agy-gemini-notebook): Setup, authenticate, invoke, query, sync files, and launch Deep Research from any terminal or agent bash tool.

💡 Use Cases & Workflows

1. Documentary Research & Decision Support $\rightarrow$ Local Project .md Files (Primary Workflow)

When your project needs documentary research to support technical, architectural, or product decision-making, the coding agent pilots a complete end-to-end research-to-documentation loop:

flowchart LR
    A["1. Decision Need in Project"] --> B["2. Invoke Existing or Create New Gemini Notebook"]
    B --> C["3. Run Deep Research or Query Existing Sources"]
    C --> D["4. Synthesize Findings with Citations"]
    D --> E["5. Write Local .md Files in Repository (docs/research/, docs/adr/)"]

1. Open or Create a Notebook: The agent either invokes an existing curated Gemini Notebook (notebook_invoke(target="...")) or creates a dedicated notebook for the topic (notebook_create(title="...", attach_to_workspace=True)).

2. Research or Query:

   • New Documentary Research: The agent launches notebook_research(query="...", mode="deep", source="web", import_sources=True) to discover, verify, and ingest external web or Google Drive sources into the notebook.

   • Existing Corpus Q&A: Or the agent queries documents already curated inside the notebook via notebook_query and notebook_search_sources.

3. Generate Local Project Markdown Files: Using the grounded answers, synthesized research report, and source citations returned by the notebook, the agent writes structured .md files directly inside your local project (e.g., docs/research/vector-db-benchmark.md, docs/adr/004-auth-architecture.md, comparative matrices, or implementation plans) that are directly tailored to your codebase.

Example Agent Prompt in Antigravity 2 / VS Code:

"We need to choose between WebSockets, SSE, and WebTransport for our real-time notification pipeline. Open our 'System Architecture' Gemini Notebook (or create a new one if needed), run a documentary research comparing latency, proxy compatibility, and scaling trade-offs, query the sources for our constraints, and create docs/research/realtime-transport-decision.md in the local project with your cited recommendations."

2. Persistent Domain & Specification Grounding Across Coding Sessions

Bind your project's canonical Gemini Notebook (containing PRDs, API specifications, regulatory PDFs, and design docs) once via .agents/notebook.json. Whenever you ask the agent to implement a feature or verify business rules, it automatically queries notebook_query or notebook_search_sources before writing code—eliminating hallucinations and keeping every answer grounded with explicit [Notebook Title — Source Name] citations.

3. Bi-Directional Knowledge Sync (Local Repo $\leftrightarrow$ Gemini Notebook)

Keep your shared Gemini Notebook synchronized with your repository's latest architecture docs (README.md, AGENTS.md, docs/*.md, PDFs) using notebook_sync_files. What your engineering agent documents locally becomes immediately queryable in NotebookLM by product managers, researchers, and teammates.

4. Automated Briefings, Study Guides & Podcast Audio Overviews

After ingesting technical documentation or completing a Deep Research session, use notebook_generate_artifact (study_guide, briefing_doc, mind_map, quiz, slide_deck) or notebook_create_audio (deep-dive, brief, critique, debate) to produce executive summaries and onboarding materials directly from your workspace.

🏗️ Dual-Engine Architecture

flowchart LR
    subgraph Harnesses["Agent Harnesses & IDEs"]
        AGY["Antigravity 2 (Plugin + Sidecar)"]
        VSC["VS Code / Cursor / Claude Code"]
        CLI["agy-gemini-notebook CLI"]
    end

    subgraph Server["Gemini Notebook by Chryzalide"]
        MCP["FastMCP / MCPServer (21 Tools + Resources + Prompts)"]
    end

    subgraph GCP["Engine 1: Official GCP API (v1alpha REST)"]
        REST["discoveryengine.googleapis.com/v1alpha/.../notebooks"]
    end

    subgraph RPC["Engine 2: RPC Bridge (notebooklm-py)"]
        NLM["notebooklm.google.com (RAG, Deep Research, Studio)"]
    end

    AGY --> MCP
    VSC --> MCP
    CLI --> MCP
    MCP -->|"CRUD, Upload, Share, Audio, Answer (gcloud OAuth2)"| REST
    MCP -->|"Full CRUD, Grounded Q&A, Deep Research, Studio (RPC)"| NLM

⚖️ Google Terms of Service, OAuth Policy & Dual-Engine Compliance

Because this plugin bridges both Google Cloud Enterprise APIs and consumer Google NotebookLM, it is designed around strict separation of credentials and transparent compliance boundaries:

1. Zero Gemini CLI / Antigravity OAuth Siphoning:

   • This plugin never reads, extracts, or repurposes internal OAuth tokens belonging to Google Antigravity 2, Gemini CLI, or Cloud Code (cloudcode-pa.googleapis.com).

2. Zero Automated Browser Sign-In on accounts.google.com:

   • In accordance with Google Identity's OAuth 2.0 Policy ("Use Secure Browsers"), this plugin never launches a Playwright/Puppeteer/Selenium-controlled browser window on accounts.google.com and never uses stealth flags such as --disable-blink-features=AutomationControlled.

3. Engine 1 — Official Google Cloud NotebookLM Enterprise (v1alpha REST API) — 100% Official & Supported:

   • Uses standard Google Cloud OAuth 2.0 Bearer tokens (gcloud auth login / gcloud auth print-access-token) against https://{ENDPOINT_LOCATION}-discoveryengine.googleapis.com/v1alpha/projects/{PROJECT_NUMBER}/locations/{LOCATION}/notebooks.

   • Recommended for corporate, production, and strict-compliance environments.

🚀 Installation & Setup Workflow

To make installation and first-time onboarding effortless across Antigravity 2, VS Code, Cursor, and the CLI, Gemini Notebook by Chryzalide ships with a 5-step Setup Workflow (./scripts/setup.sh and agy-gemini-notebook setup).

flowchart LR
    S1["1. Clone & Python .venv"] --> S2["2. Cookie Reader Check (rookie-cookies)"]
    S2 --> S3["3. Register Plugin in Antigravity 2"]
    S3 --> S4["4. Connect Browser Session or gcloud OAuth"]
    S4 --> S5["5. Reload IDE & Attach Notebook"]

Option 1: Automated 1-Command Setup (Recommended)

Clone the repository and run ./scripts/setup.sh:

git clone https://github.com/Chryzalide/agy-gemini-notebook-plugin.git
cd agy-gemini-notebook-plugin
./scripts/setup.sh --login

What ./scripts/setup.sh does automatically:

1. [Step 1/5] Python Environment & Dependencies: Creates .venv (via uv or python3 -m venv) and installs agy-gemini-notebook-plugin[rpc,dev] (including notebooklm-py[cookies]).

2. [Step 2/5] Local Browser Session Reader Verification: Verifies rookie-cookies so the plugin can import your existing session in ~1 second without downloading a 300 MB Playwright Chromium binary or automating accounts.google.com.

3. [Step 3/5] Antigravity 2 Plugin Registration: Creates ~/.gemini/config/plugins/gemini-notebook and enables Gemini Notebook by Chryzalide via the Antigravity 2 Language Server if running.

4. [Step 4/5] 1-Second Session Connection:

   • Personal / Workspace Google Account (notebooklm.google.com — Engine 2): Imports your existing authenticated session from Chrome, Brave, Firefox, Edge, Chromium, Vivaldi, Arc, or Safari (--browser-cookies auto). You only need to be logged into https://notebooklm.google.com/ in your normal browser.

   • Google Cloud NotebookLM Enterprise (v1alpha REST — Engine 1): Checks GCP_PROJECT_NUMBER and gcloud auth login.

5. [Step 5/5] Health Verification: Runs agy-gemini-notebook status to confirm setup_ready: true.

Option 2: Step-by-Step Manual Setup Checklist

If you prefer to execute each setup action manually:

1. Install the Python environment:

   uv sync --all-extras

2. Register the plugin in Google Antigravity 2:

   mkdir -p ~/.gemini/config/plugins
   ln -s "$(pwd)" ~/.gemini/config/plugins/gemini-notebook

3. Authenticate your preferred engine:

   • Engine 1 (Official Google Cloud NotebookLM Enterprise — v1alpha REST API):

     export GCP_PROJECT_NUMBER="123456789012"
     export GCP_LOCATION="global"          # global, us, or eu
     export GCP_ENDPOINT_LOCATION="global" # global, us, or eu
     .venv/bin/agy-gemini-notebook login --gcloud

   • Engine 2 (Personal / Workspace Google Account — notebooklm.google.com, Grey Area): Make sure you are signed in to https://notebooklm.google.com/ in your regular browser, then import the session in 1 second:

     .venv/bin/agy-gemini-notebook login --browser-cookies auto
     # Or specify a browser explicitly: chrome, brave, firefox, edge, chromium, vivaldi, arc, safari

4. Verify readiness:

   .venv/bin/agy-gemini-notebook status

5. Reload Antigravity 2 and open the Sidecar UI:

   • Open Overview -> Plugins -> Gemini Notebook by Chryzalide in the top-right auxiliary pane menu, or click [Gemini Notebook by Chryzalide](sidecar://gemini-notebook/notebook_context_panel/ui.html) in chat.

Option 3: In-IDE Agent-Guided or 1-Click Sidecar Setup

Once the plugin is linked and Antigravity 2 (or VS Code / Cursor) is running:

• Via the Sidecar UI (Antigravity 2): Open the Gemini Notebook by Chryzalide panel, choose your browser (Auto-detect / Chrome / Brave / Firefox / etc.), and click "🔗 Connect Session from Browser" (or "☁️ Google Cloud Login (gcloud)" for Engine 1).

• Via Chat (Antigravity 2 / VS Code / Cursor): Ask the agent:

  "Run the Gemini Notebook setup and connect my browser session for this workspace"

The agent will automatically:

1. Call notebook_status to inspect your environment.

2. Call notebook_login(browser_cookies="auto") to import your active browser session in 1 second (or open https://notebooklm.google.com/ in your system browser if you aren't logged in yet) and display the Dual-Engine compliance notice.

3. List your notebooks (notebook_list) or create a new one (notebook_create) and bind it to .agents/notebook.json.

4. Surface the clickable [Gemini Notebook by Chryzalide](sidecar://gemini-notebook/notebook_context_panel/ui.html) sidecar pill link.

🔌 Multi-IDE & CLI Usage

VS Code (GitHub Copilot MCP / Cline / Roo Code) & Cursor

Add the server to your workspace .vscode/mcp.json (or .cursor/mcp.json). Because authentication is stored centrally in ~/.notebooklm/storage_state.json (or via gcloud), connecting your session once works simultaneously across Antigravity 2, VS Code, Cursor, and the CLI:

{
  "servers": {
    "gemini_notebook_mcp": {
      "type": "stdio",
      "command": "/path/to/agy-gemini-notebook-plugin/scripts/run_mcp.sh",
      "env": {
        "AGY_WORKSPACE_DIR": "${workspaceFolder}"
      }
    }
  }
}

Standalone CLI (agy-gemini-notebook)

Use the CLI from any terminal or agent shell tool:

# Run the guided setup & health check workflow (imports existing browser session)
agy-gemini-notebook setup --login

# Check engine auth, active workspace binding, and compliance notice
agy-gemini-notebook status

# Import Google NotebookLM session from your normal browser (auto, chrome, brave, firefox, etc.)
agy-gemini-notebook login --browser-cookies auto

# Or authenticate Official Engine 1 via Google Cloud SDK
agy-gemini-notebook login --gcloud

# Invoke a notebook by fuzzy title or alias and ask a grounded question
agy-gemini-notebook invoke "System Architecture" -q "What are the latency SLAs?"

# Create a notebook and run autonomous Deep Research with source auto-import
agy-gemini-notebook create "WebGPU Compute Patterns" --attach --alias webgpu
agy-gemini-notebook research "WebGPU subgroup operations performance" --mode deep

# Sync local markdown/PDF specs into the active notebook
agy-gemini-notebook sync README.md docs/architecture.md

🛠️ Exposed MCP Tools (gemini_notebook_mcp)

📦 Versioning & Changelog

This project follows strict, transparent versioning. Every version update and change made to the repository must be documented, explained, and recorded in this section of README.md (and kept synchronized across pyproject.toml, plugin.json, and src/agy_gemini_notebook/__init__.py).

v1.0.7 (2026-11-07) — Comprehensive Security Hardening (Cloudflare 6-Phase Security Audit Remediation)

• GCP Discovery Engine URL Authority & Path-Segment Allowlisting (src/agy_gemini_notebook/config.py, src/agy_gemini_notebook/engines/gcp_enterprise_rest.py, src/agy_gemini_notebook/mcp_server.py):

  • Why: Previously, gcp_endpoint_location, gcp_location, gcp_project_number, gcp_engine_id, notebook_id, and source_id read from .agents/notebook.json or tool arguments were interpolated directly into https://{endpoint_location}-discoveryengine.googleapis.com/v1alpha/projects/{project_number}/locations/{location}/notebooks/{notebook_id}. A malicious workspace binding setting gcp_endpoint_location to an attacker domain (attacker.example.com/collect#) could hijack the URL authority and exfiltrate the user's Authorization: Bearer <gcloud_token> OAuth 2.0 token (SSRF / credential exfiltration), while unencoded / or .. segments in resource IDs allowed REST path traversal.

  • How: Added strict allowlist and regex validators (validate_gcp_endpoint_location restricted to {"us", "eu", "global"}, validate_gcp_location, validate_gcp_project_number, and extract_and_validate_resource_id + _safe_segment with urllib.parse.quote(..., safe="")) enforced both on Pydantic WorkspaceNotebookBinding deserialization and inside GcpNotebookEnterpriseClient. Also stripped CR/LF control characters from X-Goog-Upload-File-Name.

• Untrusted Workspace Script Execution Prevention (mcp_config.json, scripts/run_mcp.sh):

  • Why: mcp_config.json previously iterated over "$(pwd)" before "$HOME/.gemini/config/plugins/gemini-notebook", meaning opening an untrusted repository containing a malicious scripts/run_mcp.sh would execute arbitrary shell commands on MCP server startup. In addition, scripts/run_mcp.sh exported PYTHONPATH="${PLUGIN_DIR}/src:${PYTHONPATH:-}", leaving a trailing colon (:) when PYTHONPATH was unset (which Python interprets as adding the current working directory to sys.path).

  • How: Removed "$(pwd)" from mcp_config.json so only trusted plugin installation directories ($HOME/.gemini/config/plugins/gemini-notebook and $HOME/.gemini/extensions/gemini-notebook) are searched, and updated scripts/run_mcp.sh to use export PYTHONPATH="${PLUGIN_DIR}/src${PYTHONPATH:+:${PYTHONPATH}}".

• Sidecar HTTP API Authentication, Loopback Origin Enforcement & Static File Lockdown (sidecars/notebook_context_panel/server.py):

  • Why: SidecarRequestHandler previously emitted Access-Control-Allow-Origin: *, did not verify X-Sidecar-Token on /api/* routes, accepted unbounded Content-Length bodies, fell back to SimpleHTTPRequestHandler.do_GET() (exposing SIDECAR_DIR files such as /server.py and /sidecar.json), and allowed query/body workspace_dir overrides to escape the server's bound workspace.

  • How: Added constant-time hmac.compare_digest verification of X-Sidecar-Token / ?token= (generating a 256-bit secrets.token_urlsafe(32) token in main() when not pre-set by the host IDE), restricted Origin / CORS headers exclusively to local loopback/webview origins (403 Forbidden on external cross-origin requests), added X-Content-Type-Options: nosniff, X-Frame-Options: SAMEORIGIN, and Content-Security-Policy headers, replaced the super().do_GET() fallback with an explicit 404 JSON response, bounded request bodies to 1 MiB (MAX_BODY_BYTES) and page_size to 1..200, and pinned _resolve_allowed_workspace() to prevent escaping a bound workspace_dir.

• Workspace File Containment & Sensitive-File Blocklist (src/agy_gemini_notebook/config.py, mcp_server.py, gcp_enterprise_rest.py, rpc_bridge.py, server.py):

  • Why: notebook_sync_files and POST /api/sync previously accepted arbitrary absolute paths (e.g. /etc/passwd, ~/.ssh/id_rsa) or ../ traversal sequences and read files of unbounded size into memory before uploading them to external NotebookLM notebooks.

  • How: Added validate_workspace_file_path() enforcing candidate.resolve().is_relative_to(ws_root), blocking dot-directories and sensitive credential filenames (.env, .git, .ssh, .aws, .gnupg, .notebooklm, .notebooklm-auth, storage_state.json, server_info.json, id_rsa, id_ed25519), and enforcing a 50 MiB (MAX_UPLOAD_BYTES) upload cap. Also hardened resolve_workspace_dir() and get_binding_path() to stop parent traversal before $HOME and /.

• CLI Option Injection Prevention & 0600 Session Cookie Permissions (src/agy_gemini_notebook/engines/rpc_bridge.py, scripts/setup.sh, rules/AGENTS.md, skills/gemini-notebook/SKILL.md):

  • Why: In notebooklm-py, --browser-cookies uses Click's is_flag=False, flag_value="auto"; passing a browser_cookies value starting with -- (such as --storage=/tmp/hijack.json) caused Click to interpret the argument as a separate CLI flag. Furthermore, .notebooklm-auth/storage_state.json and .agents/notebook.json were created with default umask permissions instead of owner-only 0600.

  • How: Restricted browser_cookies to ALLOWED_COOKIE_BROWSERS (auto, chrome, brave, firefox, edge, chromium, vivaldi, arc, safari), rejected leading dashes or control characters in account and profile, enforced 0o700 directory and 0o600 file permissions via _secure_storage_permissions() and save_workspace_binding(), updated scripts/setup.sh to prefer uv sync --locked --all-extras, and added explicit prompt-injection and cookie-import consent guardrails to rules/AGENTS.md and skills/gemini-notebook/SKILL.md.

v1.0.6 (2026-11-02) — Deep Research report_id Polling Fix & CLI --wait / --report-id Support

• Fix Deep Research Polling, Waiting & Source Import Identifier (src/agy_gemini_notebook/engines/rpc_bridge.py):

  • Why: In NotebookLM's START_DEEP_RESEARCH RPC response (client.research.start(..., mode="deep")), slot 0 (started.task_id) is a transient session ID (sessionId) that is never matched by POLL_RESEARCH, wait_for_completion, IMPORT_RESEARCH, or CANCEL_RESEARCH, whereas slot 1 (started.report_id) is the actual pollable and importable task identifier. Previously, NotebookRpcBridge.run_research() passed started.task_id instead of started.report_id to client.research.wait_for_completion(), causing research --mode deep (with wait=True) to poll an unmatchable ID (NOT_FOUND) until the wait timeout always expired—even when the Deep Research run had completed in ~10 minutes. Similarly, research --no-wait returned the non-pollable started.task_id in task_id, requiring users to manually pass --task-id <report_id> to research-status.

  • How: Updated NotebookRpcBridge.run_research() to select poll_task_id = report_id if (mode_norm == "deep" and report_id) else start_task_id and pass poll_task_id to client.research.wait_for_completion() and _import_task_sources(). When wait=False (--no-wait), task_id and poll_task_id now both expose the pollable identifier (report_id for Deep Research, start_task_id for Fast Research) alongside report_id and start_task_id.

• Explicit --wait on research and --report-id / --poll-task-id on research-status (src/agy_gemini_notebook/cli.py, src/agy_gemini_notebook/mcp_server.py, tests/test_rpc_bridge_and_mcp.py):

  • Why: Agent harnesses and CLI users frequently pass --wait explicitly to agy-gemini-notebook research (consistent with sync --wait, add-source --wait, research-status --wait, audio --wait, and generate --wait) or pass --report-id / --poll-task-id to research-status / notebook_research_status.

  • How: Added --wait to the research CLI subparser, added --report-id and --poll-task-id options to research-status and notebook_research_status, and added regression tests in tests/test_rpc_bridge_and_mcp.py verifying that Deep Research fails if polled with start_task_id and succeeds using report_id.

v1.0.5 (2026-10-22) — Visual Demonstration Suite (Animated Walkthrough GIF, Sidecar UI & CLI Deep Research Previews)

• Animated 4-Step Walkthrough GIF & High-DPI Previews (assets/demo.gif, assets/sidecar-preview.png, assets/cli-research-preview.png, README.md):

  • Why: Visitors, contributors, and community listings (GitHub, Reddit, Hacker News, LinkedIn, X/Twitter, and MCP directories) need an immediate, visual demonstration of how the Antigravity 2 Sidecar UI (sidecar://gemini-notebook/notebook_context_panel/ui.html) and the agy-gemini-notebook CLI work together across setup, grounded Q&A, autonomous Deep Research $\rightarrow$ local .md synthesis, and Studio artifact generation.

  • How: Rendered a 4-step animated walkthrough (assets/demo.gif) and standalone high-resolution previews (assets/sidecar-preview.png and assets/cli-research-preview.png) directly from the live Dark Mode sidecars/notebook_context_panel/ui.html layout and CLI output, and embedded them into a new ## 🎬 Visual Overview & Interactive Demo section at the top of README.md.

v1.0.4 (2026-10-22) — Google Sign-In Policy Compliance, 1-Click Local Browser Session Import & Explicit Grey-Area Alerts

• Elimination of Automated Playwright Sign-In on accounts.google.com (src/agy_gemini_notebook/engines/rpc_bridge.py, pyproject.toml, scripts/setup.sh):

  • Why: Previously, notebook_login invoked notebooklm login without --browser-cookies, which spawned a Playwright-controlled Chromium browser on accounts.google.com using --disable-blink-features=AutomationControlled and ignore_default_args=["--enable-automation"]. Automating Google's sign-in page with stealth flags contravenes Google Identity's OAuth 2.0 "Use Secure Browsers" policy and required a 300 MB Playwright Chromium download.

  • How: Switched pyproject.toml from notebooklm-py[browser] to notebooklm-py[cookies] (rookie-cookies) and refactored NotebookRpcBridge.login() so it never launches Playwright against accounts.google.com. Instead, it imports existing authenticated cookies from the user's real OS browser (--browser-cookies auto|chrome|brave|firefox|edge|chromium|vivaldi|arc|safari) in ~1 second, supports open_system_browser=True (via Python's webbrowser.open("https://notebooklm.google.com/")) so the user signs in exclusively inside their genuine system browser, and supports gcloud=True (gcloud auth login) for Engine 1.

• Explicit ToS & Grey-Area Compliance Notices Across UI, MCP, CLI & Docs (rpc_bridge.py, mcp_server.py, sidecars/notebook_context_panel/ui.html, README.md, SKILL.md, rules/AGENTS.md):

  • Why: While Engine 1 (discoveryengine.googleapis.com/v1alpha) is 100% official Google Cloud OAuth 2.0, consumer notebooklm.google.com does not yet offer a public OAuth API and relies on internal batchexecute web RPCs (a ToS grey area). Users need transparent, prominent warnings before choosing between Engine 1 and Engine 2.

  • How: Added COMPLIANCE_NOTICE to notebook_status, notebook_login, and auth_required MCP responses; added a dedicated ## ⚖️ Google Terms of Service, OAuth Policy & Dual-Engine Compliance section to README.md; and added a visible ⚠️ Compliance & Grey-Area Notice banner plus browser selector (#cookie-browser-select), "🔗 Connect Session from Browser", "🌐 Open notebooklm.google.com", and "☁️ Google Cloud Login (gcloud)" buttons to the Sidecar UI (ui.html), along with semantic <header>/<main> landmarks, explicit <label for> associations, and IME-safe Enter handling (!e.isComposing).

v1.0.3 (2026-10-22) — Sidecar Dark Mode Contrast Fix & Isolated .venv Sign-In Subprocess Resolution

• High-Contrast Dark Mode & Namespaced CSS Tokens (sidecars/notebook_context_panel/ui.html):

  • Why: In Antigravity 2 Dark Mode on Linux, section headers (h2) and secondary labels (color: var(--muted)) rendered as dark gray/black on dark #1e1f20 cards for two reasons: (1) Antigravity 2's sidecar host bridge (/preload.js) injects shadcn-style inline CSS custom properties onto <html style="--muted: #18191b; --card: #1e1f20; ..."> where --muted is a dark surface background rather than a foreground text color, overriding :root { --muted: ... }, and (2) @media (prefers-color-scheme: light) could match inside the Linux Electron webview even when the IDE shell was dark.

  • How: Replaced all generic CSS custom properties with collision-proof --nb-* tokens (--nb-bg, --nb-card, --nb-card-elevated, --nb-border, --nb-text: #f3f4f6, --nb-text-secondary: #cbd5e1, --nb-heading: #d2e3fc, --nb-accent: #8ab4f8), removed the @media (prefers-color-scheme: light) media query override, made high-contrast Dark Mode the default (:root, [data-theme="dark"]), and added syncHostTheme() to inspect --background luminance on document.documentElement when switching themes.

• Isolated .venv Python Resolution for Browser Sign-In (src/agy_gemini_notebook/engines/rpc_bridge.py, sidecars/notebook_context_panel/server.py, sidecars/notebook_context_panel/notebooklm.py):

  • Why: Clicking "🔑 Sign In to Google NotebookLM" in the Sidecar UI failed with /usr/bin/python3: No module named notebooklm because sidecar.json launches server.py using the system python3 (/usr/bin/python3). Although server.py added .venv/lib/python*/site-packages to sys.path in-memory, NotebookRpcBridge.login() spawned [sys.executable, "-m", "notebooklm", "login"] in a child process where sys.executable was still /usr/bin/python3.

  • How: Added NotebookRpcBridge._resolve_python_executable() to resolve PLUGIN_ROOT / ".venv" / "bin" / "python" (and inject .venv PYTHONPATH/PATH), updated server.py to point sys.executable to .venv/bin/python, and added a sidecars/notebook_context_panel/notebooklm.py launcher shim that transparently execves .venv/bin/notebooklm even if an already-running server.py process invokes /usr/bin/python3 -m notebooklm.

v1.0.2 (2026-10-22) — Rebranding to "Gemini Notebook by Chryzalide", Antigravity 2 Sidecar SDK Protocol Fix & Automated 5-Step Setup Workflow

• Rebranding to Gemini Notebook by Chryzalide (plugin.json, sidecars/notebook_context_panel/sidecar.json, ui.html, README.md):

  • Why: Using the bare name "Gemini Notebook" in the Antigravity 2 Overview -> Plugins menu and plugin manifest could cause ambiguity with official first-party Google plugins or branding.

  • How: Renamed displayName in plugin.json and display_name / ui_config.views[0].title in sidecars/notebook_context_panel/sidecar.json and ui.html to Gemini Notebook by Chryzalide.

• Antigravity 2 Sidecar SDK Protocol Compliance (sidecars/notebook_context_panel/server.py, sidecar.json, ui.html):

  • Why: Clicking the plugin inside Overview -> Plugins or clicking the sidecar pill link did nothing for three reasons: (1) Antigravity 2 assigns a dynamic port to sidecars via ANTIGRAVITY_SIDECAR_WEB_PORT, whereas server.py only checked PORT (defaulting to 8765), (2) Antigravity 2 expects the sidecar to write server_info.json (host, port, token, pid) into ANTIGRAVITY_EXECUTABLE_DATA_DIR / ~/.gemini/antigravity/sidecar_data/.../data/server_info.json and serve /preload.js, and (3) the sidecar pill link was missing /ui.html (sidecar://gemini-notebook/notebook_context_panel/ui.html).

  • How: Updated server.py to bind ANTIGRAVITY_SIDECAR_WEB_PORT (falling back to PORT or 8000), write and clean up server_info.json, serve /preload.js and /shell.css, support X-Sidecar-Token CORS/query injection, and use "command": "python3", "args": ["server.py"] in sidecar.json. Updated all sidecar pill links to [Gemini Notebook by Chryzalide](sidecar://gemini-notebook/notebook_context_panel/ui.html).

• Automated 5-Step Setup & Onboarding Workflow (scripts/setup.sh, src/agy_gemini_notebook/cli.py, skills/gemini-notebook/SKILL.md, README.md):

  • Why & How: Added ./scripts/setup.sh and agy-gemini-notebook setup [--login] plus Workflow 0 in SKILL.md and a complete visual Installation & Setup Workflow guide in README.md to walk users through environment creation, Playwright Chromium verification, Antigravity 2 plugin registration, Engine 1/2 authentication, and IDE reload verification.

v1.0.1 (2026-10-22) — Interactive Authentication, Graceful Auth Diagnostics & Cross-Workspace Plugin Launchers

• Interactive Login Tool, CLI & Sidecar Sign-In (mcp_server.py, rpc_bridge.py, cli.py, sidecars/notebook_context_panel/):

  • Why: When calling notebook_create (or any Engine 2 RPC tool) before authenticating a Google NotebookLM session or Google Cloud v1alpha project, notebooklm-py raised an unhandled FileNotFoundError: Storage file not found, which Antigravity 2's MCP client masked behind a generic Encountered error in tool execution: Error executing tool notebook_create message with no direct way to log in from the IDE.

  • How: Added NotebookAuthRequiredError and wrapped MCP tool handlers to return structured, actionable diagnostics (status: "auth_required") instead of crashing tool execution. Added the notebook_login MCP tool (21 tools total), the agy-gemini-notebook login CLI subcommand, and a "🔑 Sign In to Google NotebookLM" button (POST /api/login) in the Sidecar UI panel. Also added automatic Playwright Chromium revision bridging (_prepare_playwright_browsers_env) and sandbox-compatible session storage fallback (.notebooklm-auth/storage_state.json).

• Cross-Workspace Plugin Command Resolution (mcp_config.json, sidecars/notebook_context_panel/sidecar.json):

  • Why & How: Replaced relative command paths (scripts/run_mcp.sh and sidecars/notebook_context_panel/server.py) with dynamic $HOME/.gemini/config/plugins/gemini-notebook resolution while preserving AGY_WORKSPACE_DIR=$(pwd), ensuring the MCP server and Sidecar UI launch reliably from any workspace opened in Antigravity 2 without hardcoding machine-specific paths.

v1.0 (2026-10-22) — Initial Stable Release

• Dual-Engine Architecture (src/agy_gemini_notebook/engines/):

  • Why & How: Unifies official Google Cloud Enterprise provisioning (gcp_enterprise_rest.py, Discovery Engine v1alpha REST API authenticated via gcloud auth print-access-token) with the community RPC bridge (rpc_bridge.py, powered by notebooklm-py for consumer and enterprise notebooklm.google.com accounts). Automatically falls back to Engine 2 when GCP_PROJECT_NUMBER is not configured, ensuring zero-friction operation for both personal Google accounts and GCP organizations.

• Complete 20-Tool MCP Server, Resources & Prompts (src/agy_gemini_notebook/mcp_server.py):

  • Why & How: Exposes the full lifecycle of a Gemini Notebook to any MCP client: workspace binding & invocation (notebook_status, notebook_attach, notebook_invoke), CRUD & sharing (notebook_list, notebook_get, notebook_create, notebook_delete, notebook_rename, notebook_share), local file synchronization & source management (notebook_sync_files, notebook_add_source, notebook_delete_sources, notebook_search_sources, notebook_get_source_text), grounded Q&A & autonomous research (notebook_query, notebook_research, notebook_research_status), and Studio deliverables & persistent notes (notebook_create_audio, notebook_generate_artifact, notebook_notes). Also registers MCP resources (notebook://active, notebook://aliases) and reusable MCP prompts (invoke_notebook, deep_research_notebook, sync_workspace_docs).

• Documentary Research for Decision Support $\rightarrow$ Local .md Synthesis (skills/gemini-notebook/SKILL.md, rules/AGENTS.md):

  • Why & How: Enables the primary decision-support workflow where the agent opens an existing Gemini Notebook or creates a new one, runs documentary research (notebook_research) or queries curated notebook sources (notebook_query), and synthesizes the source-cited findings into structured local Markdown files (docs/research/*.md, ADRs, decision matrices) inside the active project workspace.

• Interactive Antigravity 2 Sidecar Panel (sidecars/notebook_context_panel/):

  • Why & How: Provides an Auxiliary Pane web UI (ui.html) backed by a local HTTP server (server.py) with /api/status, /api/notebooks, /api/attach, /api/toggle_source, and /api/create_notebook endpoints—allowing 1-click notebook switching, source-level grounding filters, and inline notebook creation.

• Standalone CLI & Multi-IDE Transport (src/agy_gemini_notebook/cli.py, scripts/run_mcp.sh):

  • Why & How: Adds the agy-gemini-notebook CLI (status, list, invoke, attach, create, query, research, sync, audio, artifact) and a portable MCP launcher supporting stdio, sse, and streamable-http transports across Google Antigravity 2, VS Code, Cursor, and Claude Code.

• Automated Test Suite (tests/):

  • Why & How: Includes 16 comprehensive unit, mocked Dual-Engine, Sidecar HTTP API, and live MCP stdio handshake test suites verified with pytest and ruff.

👤 Author

Souryan Augé

• 🌐 Website: https://souryan-auge.fr/

• 💻 GitHub: @Chryzalide

📄 License

Distributed under the MIT License. Contributions are welcome!