Merge pull request teng-lin#206 from mike-golant/feat/codex-agent-support

docs(agent): add Codex repository guidance

Author: teng-lin

AGENTS.md

@@ -0,0 +1,35 @@
+# Repository Guidelines
+
+**Status:** Active
+**Last Updated:** 2026-03-13
+
+## Project Structure & Module Organization
+
+`src/notebooklm/` contains the async client and typed APIs. Internal feature modules use `_` prefixes such as `_sources.py` and `_artifacts.py`; `src/notebooklm/cli/` holds Click commands, and `src/notebooklm/rpc/` handles protocol encoding and decoding. Tests are split by scope: `tests/unit/`, `tests/integration/`, and `tests/e2e/`. Recorded HTTP fixtures live in `tests/cassettes/`. Examples are in `docs/examples/`, and diagnostics live in `scripts/`.
+
+## Build, Test, and Development Commands
+
+Use `uv` for local work:
+
+```bash
+uv sync --extra dev --extra browser
+uv run pytest
+uv run ruff check src/ tests/
+uv run ruff format src/ tests/
+uv run mypy src/notebooklm
+uv run pre-commit run --all-files
+```
+
+Run `uv run pytest tests/e2e -m readonly` only after `notebooklm login` and setting test notebook env vars.
+
+## Coding Style & Naming Conventions
+
+Target Python 3.10+, 4-space indentation, and double quotes. Ruff enforces formatting and import order with a 100-character line length. Keep module and test file names in `snake_case`; prefer descriptive Click command names that match existing groups such as `source`, `artifact`, and `research`. Preserve the internal/public split: `_*.py` for implementation, exported types in `src/notebooklm/__init__.py`.
+
+## Testing Guidelines
+
+Put pure logic in `tests/unit/`, VCR-backed flows in `tests/integration/`, and authenticated NotebookLM coverage in `tests/e2e/`. Name tests `test_<behavior>.py` and record cassettes with `NOTEBOOKLM_VCR_RECORD=1 uv run pytest tests/integration/test_vcr_*.py -v`. Coverage is expected to stay at or above the configured 90% threshold.
+
+## Commit, PR, and Agent Notes
+
+Follow the existing commit style: `feat(cli): ...`, `fix(cli): ...`, `refactor(test): ...`, `style: ...`. PRs should include a short summary, linked issue when relevant, and the commands run locally. For Codex or other parallel agents, prefer `--json`, pass explicit notebook IDs instead of relying on `notebooklm use`, and isolate runs with `NOTEBOOKLM_HOME=/tmp/<agent-id>` when multiple agents share one machine.

README.md

@@ -27,7 +27,7 @@
 
 ## What You Can Build
 
-🤖 **AI Agent Tools** - Integrate NotebookLM into Claude Code or other LLM agents. Ships with [Claude Code skills](#agent-skills-claude-code) for natural language automation (`notebooklm skill install`), or build your own integrations with the async Python API.
+🤖 **AI Agent Tools** - Integrate NotebookLM into Claude Code, Codex, and other LLM agents. Ships with a [Claude Code skill](#agent-setup) (`notebooklm skill install`) and repo-level Codex instructions in [`AGENTS.md`](AGENTS.md), or build your own integrations with the async Python API.
 
 📚 **Research Automation** - Bulk-import sources (URLs, PDFs, YouTube, Google Drive), run web/Drive research queries with auto-import, and extract insights programmatically. Build repeatable research pipelines.
 
@@ -41,7 +41,7 @@
 |--------|----------|
 | **Python API** | Application integration, async workflows, custom pipelines |
 | **CLI** | Shell scripts, quick tasks, CI/CD automation |
-| **Agent Skills** | Claude Code, LLM agents, natural language automation |
+| **Agent Integration** | Claude Code, Codex, LLM agents, natural language automation |
 
 ## Features
 
@@ -95,6 +95,8 @@ pip install "notebooklm-py[browser]"
 playwright install chromium
 ```
 
+If `playwright install chromium` fails with `TypeError: onExit is not a function`, see the Linux workaround in [Troubleshooting](docs/troubleshooting.md#linux).
+
 ### Development Installation
 
 For contributors or testing unreleased features:
@@ -157,6 +159,8 @@ Other useful CLI commands:
 
 ```bash
 notebooklm auth check --test         # Diagnose auth/cookie issues
+notebooklm agent show codex          # Print bundled Codex instructions
+notebooklm agent show claude         # Print bundled Claude Code skill template
 notebooklm language list             # List supported output languages
 notebooklm metadata --json           # Export notebook metadata and sources
 notebooklm share status              # Inspect sharing state
@@ -197,18 +201,34 @@ async def main():
 asyncio.run(main())
 ```
 
-### Agent Skills (Claude Code)
+### Agent Setup
+
+#### Claude Code
 
 ```bash
 # Install via CLI or ask Claude Code to do it
 notebooklm skill install
+notebooklm agent show claude
 
 # Then use natural language:
 # "Create a podcast about quantum computing"
 # "Download the quiz as markdown"
 # "/notebooklm generate video"
 ```
 
+#### Codex
+
+Codex reads repo-level instructions from [`AGENTS.md`](AGENTS.md), so there is no separate install command. After installing dependencies and authenticating, ask Codex to use the `notebooklm` CLI or Python API directly.
+
+```bash
+uv sync --extra dev --extra browser
+notebooklm agent show codex
+notebooklm login
+notebooklm list --json
+```
+
+For automation, prefer `--json`, pass explicit notebook IDs instead of relying on `notebooklm use`, and set `NOTEBOOKLM_HOME=/tmp/codex-$RUN_ID` when multiple agents may run in parallel.
+
 ## Documentation
 
 - **[CLI Reference](docs/cli-reference.md)** - Complete command documentation

docs/cli-reference.md

@@ -1,7 +1,7 @@
 # CLI Reference
 
 **Status:** Active
-**Last Updated:** 2026-03-12
+**Last Updated:** 2026-03-13
 
 Complete command reference for the `notebooklm` CLI—providing full programmatic access to all NotebookLM features, including capabilities not exposed in the web UI.
 
@@ -27,7 +27,7 @@ See [Configuration](configuration.md) for details on environment variables and C
 - **Session commands** - Authentication and context management
 - **Notebook commands** - CRUD operations on notebooks
 - **Chat commands** - Querying and conversation management
-- **Grouped commands** - `source`, `artifact`, `generate`, `download`, `note`, `share`, `research`, `language`, `skill`, `auth`
+- **Grouped commands** - `source`, `artifact`, `agent`, `generate`, `download`, `note`, `share`, `research`, `language`, `skill`, `auth`
 - **Utility commands** - `metadata`
 
 ---
@@ -206,6 +206,19 @@ Manage Claude Code skill integration.
 
 After installation, Claude Code recognizes NotebookLM commands via `/notebooklm` or natural language like "create a podcast about X".
 
+Codex does not use the `skill` subcommand. In this repository it reads the root [`AGENTS.md`](../AGENTS.md) file and invokes the `notebooklm` CLI or Python API directly.
+
+### Agent Commands (`notebooklm agent <cmd>`)
+
+Show bundled instructions for supported agent environments.
+
+| Command | Description | Example |
+|---------|-------------|---------|
+| `show codex` | Print the Codex repository guidance | `agent show codex` |
+| `show claude` | Print the bundled Claude Code skill template | `agent show claude` |
+
+`agent show codex` prefers the root [`AGENTS.md`](../AGENTS.md) file when running from a source checkout, so the CLI mirrors the same instructions Codex sees in the repository.
+
 ### Features Beyond the Web UI
 
 These CLI capabilities are not available in NotebookLM's web interface:

docs/troubleshooting.md

@@ -1,7 +1,7 @@
 # Troubleshooting
 
 **Status:** Active
-**Last Updated:** 2026-01-20
+**Last Updated:** 2026-03-13
 
 Common issues, known limitations, and workarounds for `notebooklm-py`.
 
@@ -307,6 +307,30 @@ audio = next(a for a in artifacts if a.kind == "audio")
 playwright install-deps chromium
 ```
 
+**`playwright install chromium` fails with `TypeError: onExit is not a function`:**
+
+This is an environment-specific Playwright install failure that has been observed with some newer Playwright builds on Linux. `notebooklm-py` only needs a working browser install for `notebooklm login`; the workaround is to install a known-good Playwright version in a clean virtual environment.
+
+**Workaround:**
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -U pip
+pip install "playwright==1.57.0"
+python -m playwright install chromium
+pip install -e ".[all]"
+```
+
+**Why this order matters:**
+- `python -m playwright ...` ensures you use the Playwright module from the active virtual environment
+- installing the browser before `pip install -e ".[all]"` avoids picking up an older broken global `playwright` executable
+- if you already have another `playwright` on your system, verify with `which playwright` after activation
+
+If you need a non-editable install from Git instead of a local checkout, replace the last step with:
+```bash
+pip install "git+https://github.com/<your-user>/notebooklm-py@<branch>"
+```
+
 **No display available (headless server):**
 - Browser login requires a display
 - Authenticate on a machine with GUI, then copy `storage_state.json`

src/notebooklm/cli/__init__.py

@@ -5,6 +5,7 @@
 Command groups are organized into separate modules:
 - source.py: Source management commands (includes add-research)
 - artifact.py: Artifact management commands
+- agent.py: Agent integration helpers
 - generate.py: Content generation commands
 - download.py: Download commands
 - note.py: Note management commands
@@ -16,6 +17,7 @@
 """
 
 # Command groups (subcommand style)
+from .agent import agent
 from .artifact import artifact
 from .chat import register_chat_commands
 from .download import download
@@ -80,6 +82,7 @@
     # Command groups (subcommand style)
     "source",
     "artifact",
+    "agent",
     "generate",
     "download",
     "note",

src/notebooklm/cli/agent.py

@@ -0,0 +1,24 @@
+"""Agent integration commands."""
+
+import click
+
+from .agent_templates import get_agent_source_content
+from .helpers import console
+
+
+@click.group()
+def agent():
+    """Show bundled instructions for supported agent environments."""
+    pass
+
+
+@agent.command("show")
+@click.argument("target", type=click.Choice(["codex", "claude"], case_sensitive=False))
+def show_agent(target: str):
+    """Display instructions for Codex or Claude Code."""
+    content = get_agent_source_content(target)
+    if content is None:
+        console.print(f"[red]Error:[/red] {target} instructions not found in package data.")
+        raise SystemExit(1)
+
+    console.print(content)

src/notebooklm/cli/agent_templates.py

@@ -0,0 +1,35 @@
+"""Shared agent instruction loading helpers."""
+
+from importlib import resources
+from pathlib import Path
+
+AGENT_TEMPLATE_FILES = {
+    "claude": "SKILL.md",
+    "codex": "CODEX.md",
+}
+
+REPO_ROOT_AGENTS = Path(__file__).resolve().parents[3] / "AGENTS.md"
+
+
+def _read_package_data(filename: str) -> str | None:
+    """Read a packaged agent template file."""
+    try:
+        return (resources.files("notebooklm") / "data" / filename).read_text(encoding="utf-8")
+    except (FileNotFoundError, TypeError):
+        return None
+
+
+def get_agent_source_content(target: str) -> str | None:
+    """Return bundled instructions for a supported agent target."""
+    normalized = target.lower()
+
+    # Prefer the repo-level Codex guide when running from a source checkout so
+    # the CLI mirrors the instructions Codex actually sees in this repository.
+    if normalized == "codex" and REPO_ROOT_AGENTS.exists():
+        return REPO_ROOT_AGENTS.read_text(encoding="utf-8")
+
+    filename = AGENT_TEMPLATE_FILES.get(normalized)
+    if filename is None:
+        return None
+
+    return _read_package_data(filename)

src/notebooklm/cli/skill.py

@@ -5,11 +5,11 @@
 
 import contextlib
 import re
-from importlib import resources
 from pathlib import Path
 
 import click
 
+from .agent_templates import get_agent_source_content
 from .helpers import console
 
 # Skill paths
@@ -19,11 +19,7 @@
 
 def get_skill_source_content() -> str | None:
     """Read the skill source file from package data."""
-    try:
-        # Python 3.9+ way to read package data (use / operator for path traversal)
-        return (resources.files("notebooklm") / "data" / "SKILL.md").read_text(encoding="utf-8")
-    except (FileNotFoundError, TypeError):
-        return None
+    return get_agent_source_content("claude")
 
 
 def get_package_version() -> str:

src/notebooklm/data/CODEX.md

@@ -0,0 +1,35 @@
+# Repository Guidelines
+
+**Status:** Active
+**Last Updated:** 2026-03-13
+
+## Project Structure & Module Organization
+
+`src/notebooklm/` contains the async client and typed APIs. Internal feature modules use `_` prefixes such as `_sources.py` and `_artifacts.py`; `src/notebooklm/cli/` holds Click commands, and `src/notebooklm/rpc/` handles protocol encoding and decoding. Tests are split by scope: `tests/unit/`, `tests/integration/`, and `tests/e2e/`. Recorded HTTP fixtures live in `tests/cassettes/`. Examples are in `docs/examples/`, and diagnostics live in `scripts/`.
+
+## Build, Test, and Development Commands
+
+Use `uv` for local work:
+
+```bash
+uv sync --extra dev --extra browser
+uv run pytest
+uv run ruff check src/ tests/
+uv run ruff format src/ tests/
+uv run mypy src/notebooklm
+uv run pre-commit run --all-files
+```
+
+Run `uv run pytest tests/e2e -m readonly` only after `notebooklm login` and setting test notebook env vars.
+
+## Coding Style & Naming Conventions
+
+Target Python 3.10+, 4-space indentation, and double quotes. Ruff enforces formatting and import order with a 100-character line length. Keep module and test file names in `snake_case`; prefer descriptive Click command names that match existing groups such as `source`, `artifact`, and `research`. Preserve the internal/public split: `_*.py` for implementation, exported types in `src/notebooklm/__init__.py`.
+
+## Testing Guidelines
+
+Put pure logic in `tests/unit/`, VCR-backed flows in `tests/integration/`, and authenticated NotebookLM coverage in `tests/e2e/`. Name tests `test_<behavior>.py` and record cassettes with `NOTEBOOKLM_VCR_RECORD=1 uv run pytest tests/integration/test_vcr_*.py -v`. Coverage is expected to stay at or above the configured 90% threshold.
+
+## Commit, PR, and Agent Notes
+
+Follow the existing commit style: `feat(cli): ...`, `fix(cli): ...`, `refactor(test): ...`, `style: ...`. PRs should include a short summary, linked issue when relevant, and the commands run locally. For Codex or other parallel agents, prefer `--json`, pass explicit notebook IDs instead of relying on `notebooklm use`, and isolate runs with `NOTEBOOKLM_HOME=/tmp/<agent-id>` when multiple agents share one machine.

src/notebooklm/notebooklm_cli.py

@@ -61,6 +61,7 @@
 
 # Import command groups from cli package
 from .cli import (
+    agent,
     artifact,
     download,
     generate,
@@ -135,6 +136,7 @@ def cli(ctx, storage, verbose):
 # Register command groups (subcommand style)
 cli.add_command(source)
 cli.add_command(artifact)
+cli.add_command(agent)
 cli.add_command(generate)
 cli.add_command(download)
 cli.add_command(note)