"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/
Python
feat: add notebooklm agent harness scaffold
liuche173d84ea2799
diff --git a/.gitignore b/.gitignoreindex 8a8e23618..5dc592593 100644--- a/.gitignore+++ b/.gitignore@@ -15,6 +15,7 @@!/README.md!/assets/!/.claude-plugin/+!/docs/# Step 3: Allow cli-anything-plugin, codex-skill, and skill_generation tests!/cli-anything-plugin/@@ -99,4 +100,7 @@ assets/gen_typing_gif.py!README_CN.md!opencode-commands/!/qoder-plugin/-+!/notebooklm/+/notebooklm/*+/notebooklm/.*+!/notebooklm/agent-harness/diff --git a/docs/plans/2026-03-17-notebooklm-harness-scaffold.md b/docs/plans/2026-03-17-notebooklm-harness-scaffold.mdnew file mode 100644index 000000000..5d38a7faa--- /dev/null+++ b/docs/plans/2026-03-17-notebooklm-harness-scaffold.md@@ -0,0 +1,192 @@+# NotebookLM Harness Scaffold Implementation Plan++> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.++**Goal:** Add an experimental `cli-anything-notebooklm` scaffold that wraps an installed `notebooklm` CLI, includes attribution files, and establishes the first round of tests and docs.++**Architecture:** Create a service-style harness under `notebooklm/agent-harness/` that mirrors the existing CLI-Anything package layout. The backend adapter will shell out to the installed `notebooklm` command, sanitize sensitive errors, and keep notebook context in a lightweight session file for REPL use.++**Tech Stack:** Python 3.10+, Click, prompt-toolkit, pytest, subprocess-based backend wrapper++### Task 1: Establish the tracked scaffold area++**Files:**+- Modify: `.gitignore`+- Create: `docs/plans/2026-03-17-notebooklm-harness-scaffold.md`++**Step 1: Write the failing test**++No behavior test for this task. It is repository plumbing needed to track the new harness path and plan document.++**Step 2: Run test to verify it fails**++Not applicable.++**Step 3: Write minimal implementation**++- Allow `docs/`+- Allow `notebooklm/`+- Allow `notebooklm/agent-harness/`++**Step 4: Run test to verify it passes**++Run: `git status --short`+Expected: new scaffold files are visible to git++**Step 5: Commit**++```bash+git add .gitignore docs/plans/2026-03-17-notebooklm-harness-scaffold.md+git commit -m "chore: prepare notebooklm harness scaffold"+```++### Task 2: Write the first failing backend tests++**Files:**+- Create: `notebooklm/agent-harness/cli_anything/notebooklm/tests/test_core.py`+- Test: `notebooklm/agent-harness/cli_anything/notebooklm/tests/test_core.py`++**Step 1: Write the failing test**++Cover:+- backend finds `notebooklm` on PATH+- backend raises clear install guidance if missing+- backend builds explicit commands with `-n <id>`+- backend sanitizes secret-bearing auth path output+- session file stores current notebook context++**Step 2: Run test to verify it fails**++Run: `cd notebooklm/agent-harness && python3 -m pytest cli_anything/notebooklm/tests/test_core.py -q`+Expected: FAIL with import errors because the package does not exist yet++**Step 3: Write minimal implementation**++Create:+- `cli_anything/notebooklm/utils/notebooklm_backend.py`+- `cli_anything/notebooklm/core/session.py`++**Step 4: Run test to verify it passes**++Run: `cd notebooklm/agent-harness && python3 -m pytest cli_anything/notebooklm/tests/test_core.py -q`+Expected: PASS++**Step 5: Commit**++```bash+git add notebooklm/agent-harness/cli_anything/notebooklm+git commit -m "feat: add notebooklm backend scaffold"+```++### Task 3: Write the first failing CLI tests++**Files:**+- Create: `notebooklm/agent-harness/cli_anything/notebooklm/tests/test_cli_smoke.py`+- Test: `notebooklm/agent-harness/cli_anything/notebooklm/tests/test_cli_smoke.py`++**Step 1: Write the failing test**++Cover:+- root `--help` shows experimental NotebookLM wording+- root `--help` exposes command groups+- `auth status --help` and `notebook list --help` execute++**Step 2: Run test to verify it fails**++Run: `cd notebooklm/agent-harness && python3 -m pytest cli_anything/notebooklm/tests/test_cli_smoke.py -q`+Expected: FAIL because `notebooklm_cli.py` is missing++**Step 3: Write minimal implementation**++Create:+- `cli_anything/notebooklm/notebooklm_cli.py`+- `cli_anything/notebooklm/__init__.py`+- `cli_anything/notebooklm/__main__.py`++Use placeholder command handlers that route through the backend wrapper.++**Step 4: Run test to verify it passes**++Run: `cd notebooklm/agent-harness && python3 -m pytest cli_anything/notebooklm/tests/test_cli_smoke.py -q`+Expected: PASS++**Step 5: Commit**++```bash+git add notebooklm/agent-harness/cli_anything/notebooklm/notebooklm_cli.py+git commit -m "feat: add notebooklm cli skeleton"+```++### Task 4: Add packaging and attribution docs++**Files:**+- Create: `notebooklm/agent-harness/setup.py`+- Create: `notebooklm/agent-harness/NOTEBOOKLM.md`+- Create: `notebooklm/agent-harness/ATTRIBUTION.md`+- Create: `notebooklm/agent-harness/THIRD_PARTY_NOTICES.md`+- Create: `notebooklm/agent-harness/cli_anything/notebooklm/README.md`+- Create: `notebooklm/agent-harness/cli_anything/notebooklm/skills/SKILL.md`+- Create: `notebooklm/agent-harness/cli_anything/notebooklm/tests/TEST.md`+- Create: `notebooklm/agent-harness/cli_anything/notebooklm/tests/test_manual_e2e.md`++**Step 1: Write the failing test**++Add assertions that:+- `setup.py` exposes `cli-anything-notebooklm`+- skill file exists+- README includes acknowledgement text++**Step 2: Run test to verify it fails**++Run: `cd notebooklm/agent-harness && python3 -m pytest cli_anything/notebooklm/tests/test_core.py -q`+Expected: FAIL on missing files and packaging metadata++**Step 3: Write minimal implementation**++Create all packaging and documentation files with explicit attribution and experimental disclaimers.++**Step 4: Run test to verify it passes**++Run: `cd notebooklm/agent-harness && python3 -m pytest cli_anything/notebooklm/tests/test_core.py cli_anything/notebooklm/tests/test_cli_smoke.py -q`+Expected: PASS++**Step 5: Commit**++```bash+git add notebooklm/agent-harness+git commit -m "docs: add notebooklm harness attribution and packaging"+```++### Task 5: Verify the scaffold end to end++**Files:**+- Modify: `notebooklm/agent-harness/cli_anything/notebooklm/tests/TEST.md`++**Step 1: Write the failing test**++No new behavior. This task is verification and documentation.++**Step 2: Run test to verify it fails**++Not applicable.++**Step 3: Write minimal implementation**++Run:+- `cd notebooklm/agent-harness && python3 -m pytest cli_anything/notebooklm/tests/test_core.py cli_anything/notebooklm/tests/test_cli_smoke.py -q`+- `cd notebooklm/agent-harness && python3 -m cli_anything.notebooklm.notebooklm_cli --help`++Append the verification notes to `TEST.md`.++**Step 4: Run test to verify it passes**++Expected:+- targeted tests PASS+- CLI help exits 0++**Step 5: Commit**++```bash+git add notebooklm/agent-harness/cli_anything/notebooklm/tests/TEST.md+git commit -m "test: verify notebooklm harness scaffold"+```diff --git a/docs/plans/2026-03-17-notebooklm-pr-polish.md b/docs/plans/2026-03-17-notebooklm-pr-polish.mdnew file mode 100644index 000000000..3b2f0d536--- /dev/null+++ b/docs/plans/2026-03-17-notebooklm-pr-polish.md@@ -0,0 +1,116 @@+# NotebookLM PR Polish Implementation Plan++> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.++**Goal:** Tighten the experimental NotebookLM harness into a more upstream-ready contribution with stronger docs, explicit attribution, and subprocess-level CLI smoke coverage.++**Architecture:** Keep the current service-style wrapper architecture intact. Improve PR readiness by expanding package-facing documentation and adding lightweight subprocess tests that verify the packaged CLI interface without requiring a live authenticated NotebookLM session.++**Tech Stack:** Python 3, Click, pytest, subprocess, Markdown docs++### Task 1: Add failing tests for PR-facing expectations++**Files:**+- Modify: `notebooklm/agent-harness/cli_anything/notebooklm/tests/test_core.py`+- Modify: `notebooklm/agent-harness/cli_anything/notebooklm/tests/test_cli_smoke.py`++**Step 1: Write the failing test**++Add tests that require:+- README to document installation, test execution, safety boundaries, and references+- SKILL.md to include installation, usage, and explicit unofficial guidance+- subprocess CLI help to render through a resolved `cli-anything-notebooklm` entry path++**Step 2: Run test to verify it fails**++Run: `cd notebooklm/agent-harness && python3 -m pytest cli_anything/notebooklm/tests/test_core.py cli_anything/notebooklm/tests/test_cli_smoke.py -q`++Expected: FAIL on missing README/SKILL sections or missing subprocess helper behavior++**Step 3: Write minimal implementation**++Expand documentation and add the smallest test helper needed for subprocess smoke coverage.++**Step 4: Run test to verify it passes**++Run: `cd notebooklm/agent-harness && python3 -m pytest cli_anything/notebooklm/tests/test_core.py cli_anything/notebooklm/tests/test_cli_smoke.py -q`++Expected: PASS++**Step 5: Commit**++```bash+git add notebooklm/agent-harness/cli_anything/notebooklm/tests notebooklm/agent-harness/cli_anything/notebooklm/README.md notebooklm/agent-harness/cli_anything/notebooklm/skills/SKILL.md+git commit -m "test: harden notebooklm harness smoke coverage"+```++### Task 2: Improve docs for upstream review++**Files:**+- Modify: `notebooklm/agent-harness/cli_anything/notebooklm/README.md`+- Modify: `notebooklm/agent-harness/cli_anything/notebooklm/skills/SKILL.md`+- Modify: `notebooklm/agent-harness/NOTEBOOKLM.md`++**Step 1: Write the failing test**++Covered by Task 1 doc assertions.++**Step 2: Run test to verify it fails**++Covered by Task 1.++**Step 3: Write minimal implementation**++Document:+- installation and local prerequisites+- run and test commands+- command group overview+- agent guidance and safe-by-default behavior+- explicit references and unofficial attribution boundary++**Step 4: Run test to verify it passes**++Run: `cd notebooklm/agent-harness && python3 -m pytest cli_anything/notebooklm/tests/test_core.py cli_anything/notebooklm/tests/test_cli_smoke.py -q`++Expected: PASS++**Step 5: Commit**++```bash+git add notebooklm/agent-harness/NOTEBOOKLM.md notebooklm/agent-harness/cli_anything/notebooklm/README.md notebooklm/agent-harness/cli_anything/notebooklm/skills/SKILL.md+git commit -m "docs: polish notebooklm harness contribution docs"+```++### Task 3: Verify and record final state++**Files:**+- Modify: `notebooklm/agent-harness/cli_anything/notebooklm/tests/TEST.md`++**Step 1: Write the failing test**++No new behavior test. This task records verification evidence.++**Step 2: Run test to verify it fails**++Not applicable.++**Step 3: Write minimal implementation**++Run:+- `cd notebooklm/agent-harness && python3 -m pytest cli_anything/notebooklm/tests -q`+- `cd notebooklm/agent-harness && python3 -m cli_anything.notebooklm.notebooklm_cli --help`++Append fresh results to `TEST.md`.++**Step 4: Run test to verify it passes**++Expected:+- all NotebookLM scaffold tests PASS+- module help exits 0 and prints command groups++**Step 5: Commit**++```bash+git add notebooklm/agent-harness/cli_anything/notebooklm/tests/TEST.md+git commit -m "test: record notebooklm harness verification"+```diff --git a/notebooklm/agent-harness/ATTRIBUTION.md b/notebooklm/agent-harness/ATTRIBUTION.mdnew file mode 100644index 000000000..bb27d4bcb--- /dev/null+++ b/notebooklm/agent-harness/ATTRIBUTION.md@@ -0,0 +1,29 @@+# Attribution++This harness adapts the CLI-Anything methodology for NotebookLM.++## Acknowledgements++- **CLI-Anything**+ - Project: https://github.com/HKUDS/CLI-Anything+ - Methodology: https://github.com/HKUDS/CLI-Anything/blob/main/cli-anything-plugin/HARNESS.md+ - We follow its agent-native CLI conventions, including REPL-first design, JSON output, package layout, and test documentation patterns.++- **notebooklm-py**+ - Project: https://github.com/teng-lin/notebooklm-py+ - PyPI: https://pypi.org/project/notebooklm-py/+ - This harness is designed to interoperate with the installed `notebooklm` CLI distributed by notebooklm-py.++- **Google NotebookLM**+ - Product help: https://support.google.com/notebooklm/answer/16206563+ - NotebookLM is a Google product. This harness is unofficial and not affiliated with or endorsed by Google.++## Design Boundary++This project prefers composition over copying:++- wrap the installed `notebooklm` CLI+- document upstream dependencies and policies+- avoid vendoring third-party NotebookLM implementation code into this repository++If you extend this harness, preserve these acknowledgements and keep the unofficial / experimental disclaimer intact.diff --git a/notebooklm/agent-harness/NOTEBOOKLM.md b/notebooklm/agent-harness/NOTEBOOKLM.mdnew file mode 100644index 000000000..c53731dab--- /dev/null+++ b/notebooklm/agent-harness/NOTEBOOKLM.md@@ -0,0 +1,44 @@+# NotebookLM: Project-Specific Analysis & SOP++## Architecture Summary++NotebookLM is a hosted Google research and content-generation product. Unlike the+local GUI applications that CLI-Anything usually targets, this harness wraps an+installed `notebooklm` command-line client that already manages authentication,+source ingestion, chat, artifact generation, and downloads.++This harness therefore behaves as a **service-style CLI wrapper**:++1. Resolve the local `notebooklm` executable.+2. Build explicit commands with notebook context where needed.+3. Sanitize sensitive auth-related error output.+4. Persist lightweight local session state for REPL convenience.++## Backend Strategy++- Prefer the installed `notebooklm` CLI over reimplementing NotebookLM internals.+- Keep credentials outside the repository and outside test fixtures.+- Treat this integration as experimental and unofficial.+- Require explicit confirmation for destructive or high-impact operations.+- Preserve clear attribution to CLI-Anything, notebooklm-py, and Google NotebookLM documentation.++## Contribution Boundary++This harness is designed to be safe for an upstream contribution review:++- it wraps an installed community CLI instead of vendoring third-party NotebookLM code+- it documents copyright and service-boundary concerns instead of implying official support+- it limits automated verification to non-destructive smoke coverage unless a local authenticated session is intentionally used+- it keeps end-to-end authenticated testing manual so secrets and account state stay out of CI and fixtures++## Constraints++- Depends on a valid local Google-authenticated NotebookLM session.+- Depends on behavior provided by the installed `notebooklm` CLI.+- Full authenticated end-to-end tests are manual by design.++## References++- CLI-Anything methodology: https://github.com/HKUDS/CLI-Anything+- notebooklm-py project: https://github.com/teng-lin/notebooklm-py+- Google NotebookLM help: https://support.google.com/notebooklm/answer/16206563diff --git a/notebooklm/agent-harness/THIRD_PARTY_NOTICES.md b/notebooklm/agent-harness/THIRD_PARTY_NOTICES.mdnew file mode 100644index 000000000..dea35669f--- /dev/null+++ b/notebooklm/agent-harness/THIRD_PARTY_NOTICES.md@@ -0,0 +1,26 @@+# Third-Party Notices++## notebooklm-py++- Homepage: https://github.com/teng-lin/notebooklm-py+- PyPI: https://pypi.org/project/notebooklm-py/+- License: MIT++This harness is intended to work with the `notebooklm` CLI provided by notebooklm-py.++## Click++Used for CLI command structure.++## prompt-toolkit++Used for REPL interaction helpers.++## Important Boundary++Google NotebookLM is a third-party online service. This harness is an unofficial+integration layer and is not affiliated with Google. Users are responsible for:++- complying with Google terms and product restrictions+- protecting their own credentials and local auth state+- respecting copyright for imported sourcesdiff --git a/notebooklm/agent-harness/cli_anything/notebooklm/README.md b/notebooklm/agent-harness/cli_anything/notebooklm/README.mdnew file mode 100644index 000000000..2751f83d8--- /dev/null+++ b/notebooklm/agent-harness/cli_anything/notebooklm/README.md@@ -0,0 +1,112 @@+# CLI-Anything NotebookLM Harness++Experimental NotebookLM harness for CLI-Anything.++This package wraps an installed `notebooklm` CLI and exposes a CLI-Anything-style+interface for authentication checks, notebook selection, source management, chat,+artifact generation, downloads, and sharing.++## Status++- Experimental+- Community-maintained+- Unofficial and not affiliated with Google++## Requirements++- Python 3.10++- An installed `notebooklm` command+- A valid local NotebookLM login session++## Install++```bash+cd notebooklm/agent-harness+python3 -m pip install -e .+```++If the upstream NotebookLM CLI is not installed yet:++```bash+python3 -m pip install --user 'notebooklm-py[browser]'+python3 -m playwright install chromium+```++## Run++```bash+# Show help+cli-anything-notebooklm --help++# Check auth state+cli-anything-notebooklm auth status++# List notebooks+cli-anything-notebooklm notebook list+```++## Run Tests++```bash+cd notebooklm/agent-harness+python3 -m pytest cli_anything/notebooklm/tests -q+python3 -m cli_anything.notebooklm.notebooklm_cli --help+```++## Command Groups++| Group | Purpose |+| --- | --- |+| `auth` | login, auth status, and lightweight auth checks |+| `notebook` | list, create, and summarize notebooks |+| `source` | inspect sources and add URL sources |+| `chat` | ask questions and inspect history |+| `artifact` | list artifacts and generate reports |+| `download` | download generated artifacts |+| `share` | inspect sharing status |++## Common Workflows++```bash+cli-anything-notebooklm auth status+cli-anything-notebooklm notebook list+cli-anything-notebooklm source list --notebook nb_123+cli-anything-notebooklm chat ask "Summarize the current notebook"+cli-anything-notebooklm artifact generate-report --notebook nb_123+```++## For AI Agents++- Prefer explicit notebook IDs with `--notebook` instead of relying on ambient state.+- Use `--json` whenever the command supports machine-readable output.+- Treat NotebookLM auth state as sensitive local data and never print cookie or storage files.+- Treat this harness as a thin wrapper around `notebooklm`, not a reimplementation of NotebookLM.++## Acknowledgements++This harness is inspired by the CLI-Anything methodology:+https://github.com/HKUDS/CLI-Anything++It is designed to work with the community-maintained `notebooklm` CLI from `notebooklm-py`:+https://github.com/teng-lin/notebooklm-py++NotebookLM is a Google product:+https://support.google.com/notebooklm/answer/16206563++This project is unofficial and not affiliated with Google.++## Safety Notes++- Do not commit local auth state into the repository.+- Do not upload sensitive content without permission.+- Respect copyright and service terms for imported sources.+- Prefer review-oriented or read-only commands first when working inside a live notebook.+- Treat sharing and artifact generation as user-impacting operations that deserve explicit intent.++## References++- CLI-Anything: https://github.com/HKUDS/CLI-Anything+- CLI-Anything HARNESS.md: https://github.com/HKUDS/CLI-Anything/blob/main/cli-anything-plugin/HARNESS.md+- notebooklm-py: https://github.com/teng-lin/notebooklm-py+- notebooklm-py on PyPI: https://pypi.org/project/notebooklm-py/+- Google NotebookLM help: https://support.google.com/notebooklm/answer/16206563diff --git a/notebooklm/agent-harness/cli_anything/notebooklm/__init__.py b/notebooklm/agent-harness/cli_anything/notebooklm/__init__.pynew file mode 100644index 000000000..c8601e771--- /dev/null+++ b/notebooklm/agent-harness/cli_anything/notebooklm/__init__.py@@ -0,0 +1,3 @@+"""NotebookLM harness package."""++__version__ = "0.1.0"diff --git a/notebooklm/agent-harness/cli_anything/notebooklm/__main__.py b/notebooklm/agent-harness/cli_anything/notebooklm/__main__.pynew file mode 100644index 000000000..fd1753810--- /dev/null+++ b/notebooklm/agent-harness/cli_anything/notebooklm/__main__.py@@ -0,0 +1,7 @@+"""Module entry point for cli-anything-notebooklm."""++from cli_anything.notebooklm.notebooklm_cli import main+++if __name__ == "__main__":+ main()diff --git a/notebooklm/agent-harness/cli_anything/notebooklm/core/__init__.py b/notebooklm/agent-harness/cli_anything/notebooklm/core/__init__.pynew file mode 100644index 000000000..2c7cef76d--- /dev/null+++ b/notebooklm/agent-harness/cli_anything/notebooklm/core/__init__.py@@ -0,0 +1 @@+"""Core modules for the NotebookLM harness."""diff --git a/notebooklm/agent-harness/cli_anything/notebooklm/core/session.py b/notebooklm/agent-harness/cli_anything/notebooklm/core/session.pynew file mode 100644index 000000000..995e6b01c--- /dev/null+++ b/notebooklm/agent-harness/cli_anything/notebooklm/core/session.py@@ -0,0 +1,42 @@+"""Session persistence helpers for NotebookLM CLI context."""++from __future__ import annotations++import json+from pathlib import Path+++class Session:+ """Persist the active notebook for REPL and one-shot commands."""++ def __init__(self, session_file: str | Path | None = None):+ if session_file is None:+ session_file = Path.home() / ".cli-anything-notebooklm" / "session.json"+ self.session_file = Path(session_file)+ self.session_file.parent.mkdir(parents=True, exist_ok=True)+ self._data = self._load()++ def _load(self) -> dict:+ if not self.session_file.exists():+ return {"active_notebook": None}+ try:+ return json.loads(self.session_file.read_text(encoding="utf-8"))+ except json.JSONDecodeError:+ return {"active_notebook": None}++ def _save(self):+ self.session_file.write_text(+ json.dumps(self._data, indent=2, ensure_ascii=True),+ encoding="utf-8",+ )++ def get_active_notebook(self) -> str | None:+ return self._data.get("active_notebook")++ def set_active_notebook(self, notebook_id: str):+ self._data["active_notebook"] = notebook_id+ self._save()++ def clear_active_notebook(self):+ self._data["active_notebook"] = None+ self._save()diff --git a/notebooklm/agent-harness/cli_anything/notebooklm/notebooklm_cli.py b/notebooklm/agent-harness/cli_anything/notebooklm/notebooklm_cli.pynew file mode 100644index 000000000..53640752b--- /dev/null+++ b/notebooklm/agent-harness/cli_anything/notebooklm/notebooklm_cli.py@@ -0,0 +1,282 @@+#!/usr/bin/env python3+"""NotebookLM CLI — Experimental NotebookLM wrapper for AI agents."""++from __future__ import annotations++import json+import sys++import click++from cli_anything.notebooklm import __version__+from cli_anything.notebooklm.core.session import Session+from cli_anything.notebooklm.utils.notebooklm_backend import run_notebooklm++_json_output = False+_session: Session | None = None+++def get_session() -> Session:+ global _session+ if _session is None:+ _session = Session()+ return _session+++def emit(data, message: str = ""):+ if _json_output:+ click.echo(json.dumps(data, indent=2, default=str))+ elif message:+ click.echo(message)+ elif isinstance(data, str):+ click.echo(data)+ else:+ click.echo(json.dumps(data, indent=2, default=str))+++def handle_error(func):+ def wrapper(*args, **kwargs):+ try:+ return func(*args, **kwargs)+ except Exception as exc: # pragma: no cover - scaffold behavior+ if _json_output:+ click.echo(json.dumps({"error": str(exc), "type": type(exc).__name__}))+ else:+ click.echo(f"Error: {exc}", err=True)+ sys.exit(1)++ wrapper.__name__ = func.__name__+ wrapper.__doc__ = func.__doc__+ return wrapper+++def resolve_notebook_id(notebook_id: str | None) -> str | None:+ return notebook_id or get_session().get_active_notebook()++[email protected](invoke_without_command=True)[email protected]("--json", "use_json", is_flag=True, help="Output as JSON")[email protected]("--notebook", "notebook_id", default=None, help="Active notebook ID")[email protected]_context+def cli(ctx, use_json, notebook_id):+ """NotebookLM CLI — Experimental NotebookLM wrapper for AI agents."""+ global _json_output+ _json_output = use_json+ if notebook_id:+ get_session().set_active_notebook(notebook_id)+ if ctx.invoked_subcommand is None:+ ctx.invoke(repl)+++def repl():+ """Start a minimal REPL placeholder."""+ click.echo(f"cli-anything-notebooklm v{__version__}")+ click.echo("Experimental harness scaffold. Use --help to inspect command groups.")+++def auth():+ """Authentication and login helpers."""++[email protected]("status")+@handle_error+def auth_status():+ """Check authentication status."""+ emit(run_notebooklm(["status"], json_output=_json_output))++[email protected]("login")+@handle_error+def auth_login():+ """Open the browser login flow."""+ emit(run_notebooklm(["login"], json_output=_json_output))++[email protected]("check")+@handle_error+def auth_check():+ """Run a lightweight authentication check."""+ emit(run_notebooklm(["auth", "check"], json_output=_json_output))+++def notebook():+ """Notebook management commands."""++[email protected]("list")+@handle_error+def notebook_list():+ """List notebooks."""+ emit(run_notebooklm(["list"], json_output=_json_output))++[email protected]("create")[email protected]("name")+@handle_error+def notebook_create(name):+ """Create a notebook."""+ emit(run_notebooklm(["create", name], json_output=_json_output))++[email protected]("summary")+@handle_error+def notebook_summary():+ """Summarize the active notebook."""+ emit(+ run_notebooklm(+ ["summary"],+ notebook_id=resolve_notebook_id(None),+ json_output=_json_output,+ )+ )+++def source():+ """Source ingestion and inspection commands."""++[email protected]("list")[email protected]("--notebook", "notebook_id", default=None, help="Notebook ID")+@handle_error+def source_list(notebook_id):+ """List sources for a notebook."""+ emit(+ run_notebooklm(+ ["source", "list"],+ notebook_id=resolve_notebook_id(notebook_id),+ json_output=_json_output,+ )+ )++[email protected]("add-url")[email protected]("url")[email protected]("--notebook", "notebook_id", default=None, help="Notebook ID")+@handle_error+def source_add_url(url, notebook_id):+ """Add a URL source."""+ emit(+ run_notebooklm(+ ["source", "add", url],+ notebook_id=resolve_notebook_id(notebook_id),+ json_output=_json_output,+ )+ )+++def chat():+ """Chat and history commands."""++[email protected]("ask")[email protected]("prompt")[email protected]("--notebook", "notebook_id", default=None, help="Notebook ID")+@handle_error+def chat_ask(prompt, notebook_id):+ """Ask a question against a notebook."""+ emit(+ run_notebooklm(+ ["ask", prompt],+ notebook_id=resolve_notebook_id(notebook_id),+ json_output=_json_output,+ )+ )++[email protected]("history")[email protected]("--notebook", "notebook_id", default=None, help="Notebook ID")+@handle_error+def chat_history(notebook_id):+ """Show chat history."""+ emit(+ run_notebooklm(+ ["history"],+ notebook_id=resolve_notebook_id(notebook_id),+ json_output=_json_output,+ )+ )+++def artifact():+ """Artifact generation and inspection commands."""++[email protected]("list")[email protected]("--notebook", "notebook_id", default=None, help="Notebook ID")+@handle_error+def artifact_list(notebook_id):+ """List notebook artifacts."""+ emit(+ run_notebooklm(+ ["artifact", "list"],+ notebook_id=resolve_notebook_id(notebook_id),+ json_output=_json_output,+ )+ )++[email protected]("generate-report")[email protected]("--notebook", "notebook_id", default=None, help="Notebook ID")+@handle_error+def artifact_generate_report(notebook_id):+ """Generate a report artifact."""+ emit(+ run_notebooklm(+ ["generate", "report", "--wait"],+ notebook_id=resolve_notebook_id(notebook_id),+ json_output=_json_output,+ )+ )+++def download():+ """Artifact download helpers."""++[email protected]("report")[email protected]("output_path")[email protected]("--notebook", "notebook_id", default=None, help="Notebook ID")+@handle_error+def download_report(output_path, notebook_id):+ """Download the latest report artifact."""+ emit(+ run_notebooklm(+ ["download", "report", output_path],+ notebook_id=resolve_notebook_id(notebook_id),+ json_output=_json_output,+ )+ )+++def share():+ """Sharing and access control commands."""++[email protected]("status")[email protected]("--notebook", "notebook_id", default=None, help="Notebook ID")+@handle_error+def share_status(notebook_id):+ """Inspect notebook sharing state."""+ emit(+ run_notebooklm(+ ["share", "status"],+ notebook_id=resolve_notebook_id(notebook_id),+ json_output=_json_output,+ )+ )+++def main():+ cli()+++if __name__ == "__main__":+ main()diff --git a/notebooklm/agent-harness/cli_anything/notebooklm/skills/SKILL.md b/notebooklm/agent-harness/cli_anything/notebooklm/skills/SKILL.mdnew file mode 100644index 000000000..9a8c6b514--- /dev/null+++ b/notebooklm/agent-harness/cli_anything/notebooklm/skills/SKILL.md@@ -0,0 +1,78 @@+---+name: cli-anything-notebooklm+description: Experimental NotebookLM harness for listing notebooks, managing sources, asking questions, generating artifacts, and downloading outputs through an installed notebooklm CLI.+---++# cli-anything-notebooklm++Experimental NotebookLM harness for CLI-Anything.++## Installation++This package is intended to be installed from the harness directory:++```bash+cd notebooklm/agent-harness+python3 -m pip install -e .+```++Install the upstream NotebookLM CLI if needed:++```bash+python3 -m pip install --user 'notebooklm-py[browser]'+python3 -m playwright install chromium+```++## Requirements++- `notebooklm` command installed locally+- Valid local NotebookLM login session++## Usage++### Basic Commands++```bash+# Show help+cli-anything-notebooklm --help++# Start with a notebook context+cli-anything-notebooklm --notebook nb_123 source list++# Prefer JSON for agent use+cli-anything-notebooklm --json notebook list+```++## Command Groups++| Group | Purpose |+| --- | --- |+| `auth` | login and auth status |+| `notebook` | notebook list, create, summary |+| `source` | source listing and URL add |+| `chat` | ask questions and inspect history |+| `artifact` | list and generate artifacts |+| `download` | fetch generated outputs |+| `share` | inspect sharing state |++## Agent Workflow++1. Check auth with `cli-anything-notebooklm auth status`+2. Discover notebook IDs with `cli-anything-notebooklm --json notebook list`+3. Use explicit `--notebook` for follow-up commands+4. Prefer `--json` for list and inspection commands++## Agent Guidance++- Prefer explicit notebook IDs with `--notebook`.+- Use `--json` for machine-readable output.+- Treat this harness as experimental and unofficial.+- Do not expose auth files or cookies in logs.+- NotebookLM is a Google product; this harness is unofficial and not affiliated with Google.++## References++- CLI-Anything: https://github.com/HKUDS/CLI-Anything+- CLI-Anything HARNESS.md: https://github.com/HKUDS/CLI-Anything/blob/main/cli-anything-plugin/HARNESS.md+- notebooklm-py: https://github.com/teng-lin/notebooklm-py+- Google NotebookLM help: https://support.google.com/notebooklm/answer/16206563diff --git a/notebooklm/agent-harness/cli_anything/notebooklm/tests/TEST.md b/notebooklm/agent-harness/cli_anything/notebooklm/tests/TEST.mdnew file mode 100644index 000000000..26a3afe23--- /dev/null+++ b/notebooklm/agent-harness/cli_anything/notebooklm/tests/TEST.md@@ -0,0 +1,64 @@+# NotebookLM Harness - Test Documentation++## Test Inventory++| File | Focus |+| --- | --- |+| `test_core.py` | backend discovery, command building, session persistence, packaging fixtures |+| `test_cli_smoke.py` | help output and command group exposure |+| `test_manual_e2e.md` | authenticated local smoke-test checklist |++## Coverage Notes++This harness has three validation layers:++- unit tests for backend helpers and session state+- smoke tests for CLI help and command registration+- manual authenticated end-to-end verification++Because NotebookLM depends on a live Google account session and an installed+community CLI, full authenticated E2E coverage is not run in public CI.++## Local Verification++Verified on 2026-03-17 in the notebooklm harness worktree.++### Commands Run++```bash+python3 -m pytest cli_anything/notebooklm/tests/test_core.py -q+python3 -m pytest cli_anything/notebooklm/tests/test_cli_smoke.py -q+python3 -m cli_anything.notebooklm.notebooklm_cli --help+```++### Results++- `test_core.py`: 9 passed+- `test_cli_smoke.py`: 5 passed+- `python3 -m cli_anything.notebooklm.notebooklm_cli --help`: exit code 0, help text rendered correctly++### Notes++- Added a regression test for module execution so `python -m cli_anything.notebooklm.notebooklm_cli --help` is covered, not just Click's in-process `CliRunner`.+- The authenticated `notebooklm` backend remains intentionally manual for end-to-end verification because it depends on a local Google session.++## PR Polish Verification++Verified on 2026-03-17 after README, SKILL, and subprocess smoke coverage upgrades.++### Commands Run++```bash+python3 -m pytest cli_anything/notebooklm/tests -q+python3 -m cli_anything.notebooklm.notebooklm_cli --help+```++### Results++- Full NotebookLM harness suite: 17 passed+- Module help command: exit code 0, rendered command groups correctly++### Notes++- Added doc-level assertions so the package README and skill file now explicitly cover installation, tests, safety boundaries, and unofficial Google attribution.+- Added `_resolve_cli`-style subprocess smoke coverage so the CLI can be exercised through a resolved command path, not only through Click's in-process test runner.diff --git a/notebooklm/agent-harness/cli_anything/notebooklm/tests/__init__.py b/notebooklm/agent-harness/cli_anything/notebooklm/tests/__init__.pynew file mode 100644index 000000000..9eb399dd0--- /dev/null+++ b/notebooklm/agent-harness/cli_anything/notebooklm/tests/__init__.py@@ -0,0 +1 @@+"""Tests for the NotebookLM harness."""diff --git a/notebooklm/agent-harness/cli_anything/notebooklm/tests/test_cli_smoke.py b/notebooklm/agent-harness/cli_anything/notebooklm/tests/test_cli_smoke.pynew file mode 100644index 000000000..e9c440f64--- /dev/null+++ b/notebooklm/agent-harness/cli_anything/notebooklm/tests/test_cli_smoke.py@@ -0,0 +1,86 @@+"""CLI smoke tests for the NotebookLM harness scaffold."""++import os+from pathlib import Path+import shutil+import subprocess+import sys++from click.testing import CliRunner++from cli_anything.notebooklm.notebooklm_cli import cli+++def _resolve_cli(name):+ """Resolve installed CLI command; fall back to python -m for local dev."""+ force = os.environ.get("CLI_ANYTHING_FORCE_INSTALLED", "").strip() == "1"+ path = shutil.which(name)+ if path:+ return [path], None+ if force:+ raise RuntimeError(f"{name} not found in PATH. Install with: pip install -e .")++ module = "cli_anything.notebooklm.notebooklm_cli"+ package_root = Path(__file__).resolve().parents[3]+ env = os.environ.copy()+ current = env.get("PYTHONPATH", "")+ env["PYTHONPATH"] = (+ f"{package_root}{os.pathsep}{current}" if current else str(package_root)+ )+ return [sys.executable, "-m", module], env+++class TestRootHelp:+ def test_root_help_shows_experimental_notebooklm(self):+ result = CliRunner().invoke(cli, ["--help"])+ assert result.exit_code == 0+ assert "NotebookLM CLI" in result.output+ assert "Experimental" in result.output++ def test_root_help_lists_command_groups(self):+ result = CliRunner().invoke(cli, ["--help"])+ assert result.exit_code == 0+ for group in ["auth", "notebook", "source", "chat", "artifact", "download", "share"]:+ assert group in result.output+++class TestSubcommandHelp:+ def test_auth_status_help(self):+ result = CliRunner().invoke(cli, ["auth", "status", "--help"])+ assert result.exit_code == 0+ assert "Check authentication status" in result.output++ def test_notebook_list_help(self):+ result = CliRunner().invoke(cli, ["notebook", "list", "--help"])+ assert result.exit_code == 0+ assert "List notebooks" in result.output+++class TestModuleExecution:+ def test_python_m_module_help_emits_output(self):+ result = subprocess.run(+ [+ sys.executable,+ "-m",+ "cli_anything.notebooklm.notebooklm_cli",+ "--help",+ ],+ capture_output=True,+ text=True,+ check=False,+ )+ assert result.returncode == 0+ assert "NotebookLM CLI" in result.stdout++ def test_resolved_cli_help_emits_output(self):+ command, env = _resolve_cli("cli-anything-notebooklm")+ result = subprocess.run(+ command + ["--help"],+ capture_output=True,+ text=True,+ check=False,+ env=env,+ )+ assert result.returncode == 0+ assert "NotebookLM CLI" in result.stdout+ assert "auth" in result.stdoutdiff --git a/notebooklm/agent-harness/cli_anything/notebooklm/tests/test_core.py b/notebooklm/agent-harness/cli_anything/notebooklm/tests/test_core.pynew file mode 100644index 000000000..7ef1a4889--- /dev/null+++ b/notebooklm/agent-harness/cli_anything/notebooklm/tests/test_core.py@@ -0,0 +1,96 @@+"""Unit tests for NotebookLM harness scaffold."""++import json+from pathlib import Path+from unittest.mock import patch++import pytest++from cli_anything.notebooklm.core.session import Session+from cli_anything.notebooklm.utils.notebooklm_backend import (+ build_command,+ require_notebooklm,+ sanitize_error,+)+++class TestBackendDiscovery:+ def test_require_notebooklm_returns_path(self):+ with patch("cli_anything.notebooklm.utils.notebooklm_backend.shutil.which", return_value="/usr/local/bin/notebooklm"):+ assert require_notebooklm() == "/usr/local/bin/notebooklm"++ def test_require_notebooklm_raises_with_install_guidance(self):+ with patch("cli_anything.notebooklm.utils.notebooklm_backend.shutil.which", return_value=None):+ with pytest.raises(RuntimeError, match="notebooklm command not found"):+ require_notebooklm()+++class TestCommandBuilder:+ def test_build_command_with_notebook_id_and_json(self):+ command = build_command(+ ["source", "list"],+ notebook_id="nb_123",+ json_output=True,+ )+ assert command == [+ "notebooklm",+ "source",+ "list",+ "-n",+ "nb_123",+ "--json",+ ]++ def test_build_command_without_notebook_id(self):+ command = build_command(["list"])+ assert command == ["notebooklm", "list"]+++class TestErrorSanitization:+ def test_sanitize_error_redacts_storage_state_path(self):+ raw = "Failed to open /Users/tester/.notebooklm/storage_state.json because auth expired"+ assert "storage_state.json" not in sanitize_error(raw)+ assert "[redacted-auth-path]" in sanitize_error(raw)+++class TestSession:+ def test_session_persists_active_notebook(self, tmp_path):+ session_file = tmp_path / "session.json"+ session = Session(session_file=session_file)+ session.set_active_notebook("nb_abc")++ reloaded = Session(session_file=session_file)+ assert reloaded.get_active_notebook() == "nb_abc"++ def test_session_clear_active_notebook(self, tmp_path):+ session_file = tmp_path / "session.json"+ session = Session(session_file=session_file)+ session.set_active_notebook("nb_abc")+ session.clear_active_notebook()++ data = json.loads(Path(session_file).read_text())+ assert data["active_notebook"] is None+++class TestPackagingFixtures:+ def test_acknowledgements_reference_external_projects(self):+ readme = Path("cli_anything/notebooklm/README.md").read_text(encoding="utf-8")+ assert "CLI-Anything" in readme+ assert "notebooklm-py" in readme++ def test_readme_documents_install_test_and_safety_sections(self):+ readme = Path("cli_anything/notebooklm/README.md").read_text(encoding="utf-8")+ assert "## Install" in readme+ assert "## Run Tests" in readme+ assert "## Safety Notes" in readme+ assert "Google NotebookLM" in readme++ def test_skill_file_contains_usage_and_boundary_guidance(self):+ skill = Path("cli_anything/notebooklm/skills/SKILL.md").read_text(encoding="utf-8")+ assert "## Installation" in skill+ assert "## Usage" in skill+ assert "unofficial" in skill.lower()+ assert "not affiliated with Google" in skill++ def test_skill_file_exists(self):+ assert Path("cli_anything/notebooklm/skills/SKILL.md").is_file()diff --git a/notebooklm/agent-harness/cli_anything/notebooklm/tests/test_manual_e2e.md b/notebooklm/agent-harness/cli_anything/notebooklm/tests/test_manual_e2e.mdnew file mode 100644index 000000000..c0b943dd9--- /dev/null+++ b/notebooklm/agent-harness/cli_anything/notebooklm/tests/test_manual_e2e.md@@ -0,0 +1,11 @@+# Manual E2E Checklist++1. Run `notebooklm login`.+2. Run `cli-anything-notebooklm auth status`.+3. Run `cli-anything-notebooklm notebook list`.+4. Create a temporary notebook with `cli-anything-notebooklm notebook create "CLI Anything Smoke Test"`.+5. Add a simple text or URL source.+6. Run `cli-anything-notebooklm chat ask "Summarize the notebook."`.+7. Generate one artifact, such as a report.+8. Download the artifact to a temporary local path.+9. Delete the temporary notebook manually after verification.diff --git a/notebooklm/agent-harness/cli_anything/notebooklm/utils/__init__.py b/notebooklm/agent-harness/cli_anything/notebooklm/utils/__init__.pynew file mode 100644index 000000000..2f7adc5be--- /dev/null+++ b/notebooklm/agent-harness/cli_anything/notebooklm/utils/__init__.py@@ -0,0 +1 @@+"""Utility modules for the NotebookLM harness."""diff --git a/notebooklm/agent-harness/cli_anything/notebooklm/utils/notebooklm_backend.py b/notebooklm/agent-harness/cli_anything/notebooklm/utils/notebooklm_backend.pynew file mode 100644index 000000000..4ff424097--- /dev/null+++ b/notebooklm/agent-harness/cli_anything/notebooklm/utils/notebooklm_backend.py@@ -0,0 +1,91 @@+"""NotebookLM backend adapter.++This module wraps an installed `notebooklm` CLI for use inside a CLI-Anything+harness. It does not implement a Google official API client.++References:+- CLI-Anything methodology: https://github.com/HKUDS/CLI-Anything+- notebooklm-py project: https://github.com/teng-lin/notebooklm-py++Security rules:+- never print credential files or cookies+- never commit auth state into the repository+- prefer explicit notebook IDs+"""++from __future__ import annotations++import json+import re+import shutil+import subprocess+++def require_notebooklm() -> str:+ """Resolve the notebooklm command from PATH."""+ path = shutil.which("notebooklm")+ if path:+ return path+ raise RuntimeError(+ "notebooklm command not found. Install it with:\n"+ " python3 -m pip install --user 'notebooklm-py[browser]'\n"+ " python3 -m playwright install chromium"+ )+++def build_command(+ args: list[str],+ *,+ notebook_id: str | None = None,+ json_output: bool = False,+) -> list[str]:+ """Build a notebooklm command with explicit notebook context."""+ command = ["notebooklm", *args]+ if notebook_id:+ command.extend(["-n", notebook_id])+ if json_output:+ command.append("--json")+ return command+++def sanitize_error(text: str) -> str:+ """Redact local auth file paths from stderr/stdout."""+ patterns = [+ r"/Users/[^/\s]+/\.notebooklm/storage_state\.json",+ r"/home/[^/\s]+/\.notebooklm/storage_state\.json",+ r"[A-Za-z]:\\\\Users\\\\[^\\\s]+\\\\\.notebooklm\\\\storage_state\.json",+ ]+ sanitized = text+ for pattern in patterns:+ sanitized = re.sub(pattern, "[redacted-auth-path]", sanitized)+ sanitized = sanitized.replace("storage_state.json", "[redacted-auth-path]")+ return sanitized+++def run_notebooklm(+ args: list[str],+ *,+ notebook_id: str | None = None,+ json_output: bool = False,+) -> dict | str:+ """Run notebooklm and optionally parse JSON output."""+ command = build_command(+ args,+ notebook_id=notebook_id,+ json_output=json_output,+ )+ command[0] = require_notebooklm()++ result = subprocess.run(+ command,+ capture_output=True,+ text=True,+ check=False,+ )++ if result.returncode != 0:+ raise RuntimeError(sanitize_error(result.stderr or result.stdout))++ if json_output:+ return json.loads(result.stdout or "{}")+ return result.stdout.strip()diff --git a/notebooklm/agent-harness/setup.py b/notebooklm/agent-harness/setup.pynew file mode 100644index 000000000..c6679bd04--- /dev/null+++ b/notebooklm/agent-harness/setup.py@@ -0,0 +1,54 @@+#!/usr/bin/env python3+"""+setup.py for cli-anything-notebooklm++Install with: pip install -e .+"""++from setuptools import setup, find_namespace_packages++with open("cli_anything/notebooklm/README.md", "r", encoding="utf-8") as fh:+ long_description = fh.read()++setup(+ name="cli-anything-notebooklm",+ version="0.1.0",+ author="cli-anything contributors",+ author_email="",+ description="Experimental CLI harness for NotebookLM via an installed notebooklm CLI. Unofficial and community-maintained.",+ long_description=long_description,+ long_description_content_type="text/markdown",+ url="https://github.com/HKUDS/CLI-Anything",+ packages=find_namespace_packages(include=["cli_anything.*"]),+ classifiers=[+ "Development Status :: 4 - Beta",+ "Intended Audience :: Developers",+ "Topic :: Software Development :: Libraries :: Python Modules",+ "License :: OSI Approved :: MIT License",+ "Programming Language :: Python :: 3",+ "Programming Language :: Python :: 3.10",+ "Programming Language :: Python :: 3.11",+ "Programming Language :: Python :: 3.12",+ ],+ python_requires=">=3.10",+ install_requires=[+ "click>=8.0.0",+ "prompt-toolkit>=3.0.0",+ ],+ extras_require={+ "dev": [+ "pytest>=7.0.0",+ "pytest-cov>=4.0.0",+ ],+ },+ entry_points={+ "console_scripts": [+ "cli-anything-notebooklm=cli_anything.notebooklm.notebooklm_cli:main",+ ],+ },+ package_data={+ "cli_anything.notebooklm": ["skills/*.md"],+ },+ include_package_data=True,+ zip_safe=False,+)