claude-nbexec 0.1.0__tar.gz

claude_nbexec-0.1.0/.claude/skills/nbexec/SKILL.md.template

@@ -0,0 +1,17 @@
+---
+name: nbexec
+description: Execute code on remote Jupyter kernels (e.g. PySpark, Python) with local notebook logging. Use when the user asks to run code on a remote kernel, query data via Spark, or interact with a Jupyter notebook session.
+argument-hint: <command> [options]
+---
+
+# nbexec — Remote Jupyter Kernel Execution CLI
+
+The nbexec binary is at: `__NBEXEC_PATH__`
+
+Before doing anything else, run `__NBEXEC_PATH__ --help` to discover available commands and their options.
+
+## Task
+
+$ARGUMENTS
+
+Use `nbexec` to accomplish the task. Follow the help output precisely.

claude_nbexec-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build
+        run: uv build

claude_nbexec-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,23 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build
+        run: uv build
+
+      - name: Publish
+        run: uv publish --token ${{ secrets.PYPI_TOKEN }}

claude_nbexec-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

claude_nbexec-0.1.0/.python-version

@@ -0,0 +1 @@
+3.10

claude_nbexec-0.1.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: claude-nbexec
+Version: 0.1.0
+Summary: CLI daemon that proxies code execution to remote Jupyter kernels with local notebook logging
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: jupyter-kernel-client>=0.3
+Requires-Dist: nbformat>=5.9
+Description-Content-Type: text/markdown
+
+# nbexec
+
+A CLI tool that lets AI agents (like Claude Code) execute code on remote Jupyter kernels. All executed code and outputs are logged to a local `.ipynb` notebook file for human review.
+
+## Why
+
+When an AI agent needs to run code on a remote compute environment — a PySpark cluster, a GPU machine, a data warehouse notebook server — there's no simple way to do it interactively. The agent can't open a Jupyter UI. It needs to send code, get results, and move on.
+
+nbexec bridges this gap. The agent calls `nbexec exec --code "..."` and gets text output on stdout. It can also run an existing `.ipynb` notebook on the same kernel with `nbexec exec --file ./analysis.ipynb` — all code cells execute sequentially, and variables persist across all exec calls in the session. Behind the scenes, a daemon holds a persistent WebSocket connection to the remote Jupyter kernel, and every cell + output is recorded in a local `.ipynb` file that you can open in VS Code or Jupyter to see exactly what the agent did.
+
+## How it works
+
+```
+Agent (Claude Code)              nbexec daemon                Remote Jupyter Server
+───────────────────              ─────────────                ─────────────────────
+                                 (background process)
+
+exec --code "..."  ────────────► Unix socket request
+                                 append cell to .ipynb
+                                 send to kernel via WS ─────► kernel executes code
+                                                         ◄─── results on iopub
+                                 write output to .ipynb
+stdout: result     ◄──────────── return output
+```
+
+The daemon is a long-running background process that holds persistent WebSocket connections to one or more remote Jupyter servers. CLI commands (`exec`, `session create`, etc.) are thin clients that talk to the daemon over a Unix socket — each `exec` is a synchronous request/response.
+
+This is the same protocol VS Code uses when you connect a local notebook to a remote Jupyter server. The notebook document stays local, only code strings are sent to the kernel. nbexec replicates this model for CLI/agent use, using [jupyter-kernel-client](https://github.com/datalayer/jupyter-kernel-client) to manage the kernel connection.
+
+## Why a CLI and not an MCP server or raw HTTP
+
+**Agents don't think in cells.** Existing Jupyter MCP servers expose notebook operations — create cell, edit cell, move cell, run cell. But an agent executing code on a remote kernel doesn't care about cells. It just wants to send code and get results. It doesn't need to edit cell 5 or reorder cells — if something went wrong, it sends corrected code as the next execution. nbexec matches this model: send code, get output, move on. The notebook is just a side effect for human review, not something the agent manages.
+
+**Clean context.** An MCP server's tool definitions live in the agent's prompt at all times. nbexec adds nothing to the prompt until the agent actually needs it — the skill loads on demand, and `--help` is only fetched when invoked.
+
+**Full visibility.** Everything inside an MCP server is opaque to the agent — it can only call the tools that are exposed. With a CLI, the agent has access to the source code, can inspect how things work, and can understand or work around issues on its own.
+
+**Persistent connections without agent coupling.** The daemon runs as a separate process, managing WebSocket connections and kernel sessions independently. The agent doesn't need to hold connections or re-establish them between calls. Sessions survive across multiple agent conversations. An MCP server's lifecycle is tied to the agent process that started it.
+
+**Fewer tokens than raw HTTP.** The agent could call the Jupyter REST API directly via curl, but that means generating verbose HTTP requests for every cell execution, manually managing XSRF tokens, parsing WebSocket message framing, and tracking kernel/session IDs. A single `nbexec exec --session spark --code "..."` replaces all of that. Less generated tokens, simpler logic, same result.
+
+**Self-documenting from the CLI.** The agent runs `nbexec --help` and gets everything it needs — commands, options, examples, workflow patterns. No need to embed documentation in MCP tool descriptions or maintain it in two places.
+
+## Inspiration
+
+The architectural pattern — a long-lived daemon process, CLI-driven interaction, persistent state across calls, and a skill file for agent discovery — is inspired by [OpenClaw](https://github.com/openclaw/openclaw). nbexec applies the same intuition to a narrower problem: giving AI coding agents structured access to remote Jupyter kernels.
+
+## Installation
+
+Requires Python 3.10+.
+
+```bash
+uv tool install claude-nbexec
+```
+
+Or with pip:
+
+```bash
+pip install claude-nbexec
+```
+
+### Install the Claude Code skill
+
+Clone the repo and run the skill installer:
+
+```bash
+git clone https://github.com/anish749/claude-nbexec.git && cd claude-nbexec
+./install-skill.sh
+```
+
+This installs a skill to `$CLAUDE_CONFIG_DIR/skills/nbexec/` that teaches Claude Code when and how to use nbexec.
+
+### Usage
+
+All commands and options are documented in `nbexec --help`.

claude_nbexec-0.1.0/README.md

@@ -0,0 +1,75 @@
+# nbexec
+
+A CLI tool that lets AI agents (like Claude Code) execute code on remote Jupyter kernels. All executed code and outputs are logged to a local `.ipynb` notebook file for human review.
+
+## Why
+
+When an AI agent needs to run code on a remote compute environment — a PySpark cluster, a GPU machine, a data warehouse notebook server — there's no simple way to do it interactively. The agent can't open a Jupyter UI. It needs to send code, get results, and move on.
+
+nbexec bridges this gap. The agent calls `nbexec exec --code "..."` and gets text output on stdout. It can also run an existing `.ipynb` notebook on the same kernel with `nbexec exec --file ./analysis.ipynb` — all code cells execute sequentially, and variables persist across all exec calls in the session. Behind the scenes, a daemon holds a persistent WebSocket connection to the remote Jupyter kernel, and every cell + output is recorded in a local `.ipynb` file that you can open in VS Code or Jupyter to see exactly what the agent did.
+
+## How it works
+
+```
+Agent (Claude Code)              nbexec daemon                Remote Jupyter Server
+───────────────────              ─────────────                ─────────────────────
+                                 (background process)
+
+exec --code "..."  ────────────► Unix socket request
+                                 append cell to .ipynb
+                                 send to kernel via WS ─────► kernel executes code
+                                                         ◄─── results on iopub
+                                 write output to .ipynb
+stdout: result     ◄──────────── return output
+```
+
+The daemon is a long-running background process that holds persistent WebSocket connections to one or more remote Jupyter servers. CLI commands (`exec`, `session create`, etc.) are thin clients that talk to the daemon over a Unix socket — each `exec` is a synchronous request/response.
+
+This is the same protocol VS Code uses when you connect a local notebook to a remote Jupyter server. The notebook document stays local, only code strings are sent to the kernel. nbexec replicates this model for CLI/agent use, using [jupyter-kernel-client](https://github.com/datalayer/jupyter-kernel-client) to manage the kernel connection.
+
+## Why a CLI and not an MCP server or raw HTTP
+
+**Agents don't think in cells.** Existing Jupyter MCP servers expose notebook operations — create cell, edit cell, move cell, run cell. But an agent executing code on a remote kernel doesn't care about cells. It just wants to send code and get results. It doesn't need to edit cell 5 or reorder cells — if something went wrong, it sends corrected code as the next execution. nbexec matches this model: send code, get output, move on. The notebook is just a side effect for human review, not something the agent manages.
+
+**Clean context.** An MCP server's tool definitions live in the agent's prompt at all times. nbexec adds nothing to the prompt until the agent actually needs it — the skill loads on demand, and `--help` is only fetched when invoked.
+
+**Full visibility.** Everything inside an MCP server is opaque to the agent — it can only call the tools that are exposed. With a CLI, the agent has access to the source code, can inspect how things work, and can understand or work around issues on its own.
+
+**Persistent connections without agent coupling.** The daemon runs as a separate process, managing WebSocket connections and kernel sessions independently. The agent doesn't need to hold connections or re-establish them between calls. Sessions survive across multiple agent conversations. An MCP server's lifecycle is tied to the agent process that started it.
+
+**Fewer tokens than raw HTTP.** The agent could call the Jupyter REST API directly via curl, but that means generating verbose HTTP requests for every cell execution, manually managing XSRF tokens, parsing WebSocket message framing, and tracking kernel/session IDs. A single `nbexec exec --session spark --code "..."` replaces all of that. Less generated tokens, simpler logic, same result.
+
+**Self-documenting from the CLI.** The agent runs `nbexec --help` and gets everything it needs — commands, options, examples, workflow patterns. No need to embed documentation in MCP tool descriptions or maintain it in two places.
+
+## Inspiration
+
+The architectural pattern — a long-lived daemon process, CLI-driven interaction, persistent state across calls, and a skill file for agent discovery — is inspired by [OpenClaw](https://github.com/openclaw/openclaw). nbexec applies the same intuition to a narrower problem: giving AI coding agents structured access to remote Jupyter kernels.
+
+## Installation
+
+Requires Python 3.10+.
+
+```bash
+uv tool install claude-nbexec
+```
+
+Or with pip:
+
+```bash
+pip install claude-nbexec
+```
+
+### Install the Claude Code skill
+
+Clone the repo and run the skill installer:
+
+```bash
+git clone https://github.com/anish749/claude-nbexec.git && cd claude-nbexec
+./install-skill.sh
+```
+
+This installs a skill to `$CLAUDE_CONFIG_DIR/skills/nbexec/` that teaches Claude Code when and how to use nbexec.
+
+### Usage
+
+All commands and options are documented in `nbexec --help`.

claude_nbexec-0.1.0/install-skill.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_DIR="$(cd "$(dirname "$0")" && pwd)"
+SKILL_SRC="$REPO_DIR/.claude/skills/nbexec/SKILL.md.template"
+CLAUDE_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
+CLAUDE_DIR="${CLAUDE_DIR%/}"
+SKILL_DST="$CLAUDE_DIR/skills/nbexec"
+
+# Find nbexec: prefer PATH, fall back to local .venv
+if command -v nbexec &>/dev/null; then
+    NBEXEC_PATH="$(command -v nbexec)"
+elif [ -x "$REPO_DIR/.venv/bin/nbexec" ]; then
+    NBEXEC_PATH="$REPO_DIR/.venv/bin/nbexec"
+else
+    echo "Error: nbexec not found. Install with: pip install claude-nbexec" >&2
+    exit 1
+fi
+
+mkdir -p "$SKILL_DST"
+sed "s|__NBEXEC_PATH__|$NBEXEC_PATH|g" "$SKILL_SRC" > "$SKILL_DST/SKILL.md"
+echo "Installed skill to $SKILL_DST/SKILL.md (nbexec path: $NBEXEC_PATH)"

claude_nbexec-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "claude-nbexec"
+dynamic = ["version"]
+description = "CLI daemon that proxies code execution to remote Jupyter kernels with local notebook logging"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "click>=8.1",
+    "jupyter-kernel-client>=0.3",
+    "nbformat>=5.9",
+]
+
+[project.scripts]
+nbexec = "nbexec.cli.main:cli"
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/nbexec"]

claude_nbexec-0.1.0/src/nbexec/cli/client.py

@@ -0,0 +1,51 @@
+import asyncio
+import json
+import sys
+
+from nbexec import protocol as proto
+from nbexec.paths import socket_path
+
+
+def send_to_daemon(method: str, params: dict | None = None, timeout: float | None = None) -> dict:
+    """Send a request to the daemon and return the response.
+
+    Raises SystemExit on connection errors so CLI commands fail cleanly.
+    """
+    sock = socket_path()
+    if not sock.exists():
+        print("Error: daemon is not running. Start it with: nbexec daemon start", file=sys.stderr)
+        sys.exit(1)
+
+    request = proto.make_request(method, params)
+    response = asyncio.run(_send(str(sock), request, timeout))
+
+    if not response.get("ok"):
+        print(f"Error: {response.get('error', 'unknown error')}", file=sys.stderr)
+        sys.exit(1)
+
+    return response["result"]
+
+
+async def _send(sock_path: str, request: dict, timeout: float | None) -> dict:
+    try:
+        reader, writer = await asyncio.open_unix_connection(sock_path)
+    except (ConnectionRefusedError, FileNotFoundError):
+        print("Error: cannot connect to daemon. Is it running?", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        writer.write(proto.encode(request))
+        await writer.drain()
+
+        line = await asyncio.wait_for(reader.readline(), timeout=timeout)
+        if not line:
+            print("Error: daemon closed connection", file=sys.stderr)
+            sys.exit(1)
+
+        return proto.decode(line)
+    finally:
+        writer.close()
+        try:
+            await writer.wait_closed()
+        except Exception:
+            pass

claude_nbexec-0.1.0/src/nbexec/cli/daemon_cmds.py

@@ -0,0 +1,38 @@
+import json
+import click
+
+from nbexec.daemon.process import start_daemon, stop_daemon, daemon_status
+
+
+@click.group()
+def daemon():
+    """Manage the nbexec daemon."""
+    pass
+
+
+@daemon.command()
+def start():
+    """Start the daemon in the background."""
+    if start_daemon():
+        click.echo("Daemon started.")
+    else:
+        click.echo("Daemon is already running.")
+
+
+@daemon.command()
+def stop():
+    """Stop the daemon."""
+    if stop_daemon():
+        click.echo("Daemon stopped.")
+    else:
+        click.echo("Daemon is not running.")
+
+
+@daemon.command()
+def status():
+    """Check daemon status."""
+    info = daemon_status()
+    if info["running"]:
+        click.echo(f"Running (pid={info['pid']}, socket={info['socket']})")
+    else:
+        click.echo("Not running.")

claude_nbexec-0.1.0/src/nbexec/cli/exec_cmd.py

@@ -0,0 +1,81 @@
+import sys
+from pathlib import Path
+
+import click
+import nbformat
+
+from nbexec import protocol as proto
+from .client import send_to_daemon
+
+
+def _exec_one(session_id, code, timeout):
+    """Execute a single code string and print output. Returns True on success."""
+    result = send_to_daemon(
+        proto.EXEC,
+        {"session_id": session_id, "code": code},
+        timeout=timeout,
+    )
+    text = result.get("text", "")
+    if text:
+        click.echo(text)
+    return result.get("status") != "error"
+
+
+def _exec_notebook(session_id, notebook_path, timeout, from_cell, to_cell):
+    """Execute code cells from a .ipynb file sequentially."""
+    nb = nbformat.read(notebook_path, as_version=4)
+    code_cells = [c for c in nb.cells if c.cell_type == "code" and c.source.strip()]
+    total = len(code_cells)
+    if not code_cells:
+        click.echo("No code cells found in notebook", err=True)
+        sys.exit(1)
+
+    # --from-cell and --to-cell are 1-based, inclusive
+    start = (from_cell or 1) - 1
+    end = to_cell or total
+
+    if start >= total:
+        click.echo(f"--from-cell {from_cell} is beyond the {total} code cells in the notebook", err=True)
+        sys.exit(1)
+
+    selected = code_cells[start:end]
+    if not selected:
+        click.echo("No code cells in the specified range", err=True)
+        sys.exit(1)
+
+    for i, cell in enumerate(selected, start + 1):
+        click.echo(f"--- cell {i}/{total} ---", err=True)
+        ok = _exec_one(session_id, cell.source, timeout)
+        if not ok:
+            click.echo(f"Cell {i} failed, stopping.", err=True)
+            sys.exit(1)
+
+
+@click.command()
+@click.option("--session", "session_id", required=True, help="Session ID")
+@click.option("--code", default=None, help="Code to execute")
+@click.option("--file", "file_path", default=None, type=click.Path(exists=True), help="File containing code to execute (.py or .ipynb)")
+@click.option("--timeout", default=None, type=float, help="Execution timeout in seconds (default: no timeout)")
+@click.option("--from-cell", "from_cell", default=None, type=int, help="Start from this code cell (1-based, inclusive). Only for .ipynb files.")
+@click.option("--to-cell", "to_cell", default=None, type=int, help="Stop at this code cell (1-based, inclusive). Only for .ipynb files.")
+def exec_code(session_id, code, file_path, timeout, from_cell, to_cell):
+    """Execute code on a remote kernel."""
+    if (from_cell or to_cell) and (file_path is None or not file_path.endswith(".ipynb")):
+        click.echo("--from-cell and --to-cell can only be used with .ipynb files", err=True)
+        sys.exit(1)
+
+    if code is None and file_path is None:
+        # Read from stdin
+        if sys.stdin.isatty():
+            click.echo("Error: provide --code, --file, or pipe code via stdin", err=True)
+            sys.exit(1)
+        code = sys.stdin.read()
+    elif file_path is not None:
+        if file_path.endswith(".ipynb"):
+            _exec_notebook(session_id, file_path, timeout, from_cell, to_cell)
+            return
+        code = Path(file_path).read_text()
+
+    ok = _exec_one(session_id, code, timeout)
+    if not ok:
+        sys.exit(1)

claude_nbexec-0.1.0/src/nbexec/cli/interrupt_cmd.py

@@ -0,0 +1,12 @@
+import click
+
+from nbexec import protocol as proto
+from .client import send_to_daemon
+
+
+@click.command()
+@click.option("--session", "session_id", required=True, help="Session ID")
+def interrupt(session_id):
+    """Interrupt a running execution on a remote kernel."""
+    send_to_daemon(proto.INTERRUPT, {"session_id": session_id})
+    click.echo(f"Interrupt sent to session '{session_id}'.")

claude_nbexec-0.1.0/src/nbexec/cli/main.py

@@ -0,0 +1,179 @@
+import sys
+
+import click
+
+from .daemon_cmds import daemon
+from .session_cmds import session
+from .exec_cmd import exec_code
+from .interrupt_cmd import interrupt
+
+USAGE = """\
+nbexec — CLI daemon that proxies code execution to remote Jupyter kernels
+with local notebook logging.
+
+Designed for AI agent use. An agent sends code strings to a remote Jupyter
+kernel (e.g. PySpark, Python) and gets text results back. All executed code
+and outputs are recorded in a local .ipynb file for human inspection.
+
+Architecture: a background daemon holds persistent WebSocket connections to
+remote Jupyter servers. CLI commands talk to the daemon via a Unix socket.
+Multiple sessions can run simultaneously, each connected to a different
+(or the same) Jupyter server with its own kernel and notebook file.
+
+Usage:
+  nbexec <command> [options]
+
+Commands:
+
+  daemon start
+      Start the nbexec daemon in the background. The daemon listens on a
+      Unix socket at ~/.local/state/nbexec/nbexec.sock and manages all
+      kernel connections. Idempotent — prints a message if already running.
+
+      Example:
+        nbexec daemon start
+
+  daemon stop
+      Stop the daemon. Closes all sessions (shutting down remote kernels),
+      saves all notebooks, removes the socket and PID file.
+
+      Example:
+        nbexec daemon stop
+
+  daemon status
+      Check if the daemon is running. Prints PID and socket path if running.
+
+      Example:
+        nbexec daemon status
+
+  session create
+      Create a new session: connects to a remote Jupyter server, starts a
+      kernel, and creates a local .ipynb notebook file. The session ID is
+      used in subsequent exec and close commands.
+
+      Options:
+        --server URL       Jupyter server URL (required, e.g. http://localhost:8888)
+        --token TOKEN      Jupyter server auth token (required)
+        --notebook PATH    Local path for the .ipynb log file (required)
+        --name NAME        Session name/ID (optional, auto-generated if omitted)
+        --kernel NAME      Kernel name (default: python3)
+
+      Examples:
+        nbexec session create --server http://localhost:8888 --token abc123 \\
+            --notebook ./spark_session.ipynb --name spark
+        nbexec session create --server http://localhost:9999 --token xyz \\
+            --notebook ./analysis.ipynb --name analysis
+
+  session list
+      List all active sessions. Shows session ID, server URL, cell count,
+      and notebook path for each session.
+
+      Example:
+        nbexec session list
+
+  session close
+      Close a session: shuts down the remote kernel, saves the notebook
+      file, and removes the session from the daemon.
+
+      Options:
+        --session ID       Session ID to close (required)
+
+      Example:
+        nbexec session close --session spark
+
+  exec
+      Execute code on a remote kernel. Sends the code string to the kernel,
+      waits for completion, prints the output to stdout, and records the
+      cell and outputs in the session's notebook file.
+
+      Exit code is 0 on success, 1 on execution error.
+
+      Options:
+        --session ID       Session ID (required)
+        --file PATH        File containing code to execute (recommended).
+                           Supports .ipynb files — all code cells in the
+                           notebook are executed sequentially on the session's
+                           kernel. Execution stops on the first cell error.
+        --code CODE        Code string to execute (simple one-liners only)
+        --from-cell N      Start from code cell N (1-based, inclusive, .ipynb only)
+        --to-cell N        Stop at code cell N (1-based, inclusive, .ipynb only)
+
+      If neither --code nor --file is given, reads code from stdin.
+
+      Variables persist across exec calls within the same session (same
+      kernel). Each exec appends a new cell to the notebook.
+
+  interrupt
+      Interrupt a currently running execution on a remote kernel. Sends a
+      SIGINT to the kernel process, which will cause most Python code to
+      raise a KeyboardInterrupt. Use this to cancel long-running cells.
+
+      Options:
+        --session ID       Session ID (required)
+
+      Example:
+        nbexec interrupt --session spark
+
+IMPORTANT — how to send code:
+
+  Prefer --file for anything beyond a trivial one-liner. Write the
+  code to a temporary file first, then pass the path. This avoids
+  bash escaping issues with quotes, newlines, and special characters
+  that are common in Python/SQL code.
+
+  Use --code only for simple single-line expressions like:
+    nbexec exec --session spark --code "df.show()"
+    nbexec exec --session spark --code "print(x)"
+
+  For multiline code, write to a file first, then use --file:
+    nbexec exec --session spark --file /tmp/cell.py
+
+  To run an existing .ipynb notebook (e.g. shared setup, a saved
+  analysis, or a notebook the user points you to), pass it to --file.
+  All code cells run sequentially on the session's kernel, and variables
+  persist in both directions:
+    nbexec exec --session spark --file ./analysis.ipynb
+
+  Use --from-cell and --to-cell to run a subset of code cells. Both are
+  1-based and inclusive. For a notebook with 10 code cells:
+    --from-cell 5              runs cells 5, 6, 7, 8, 9, 10
+    --to-cell 3                runs cells 1, 2, 3
+    --from-cell 3 --to-cell 5  runs cells 3, 4, 5
+
+Agent Workflow Examples:
+
+  Start a session, run a notebook, then explore interactively:
+    nbexec daemon start
+    nbexec session create --server http://localhost:8888 --token $TOKEN \\
+        --notebook ./session.ipynb --name spark
+    nbexec exec --session spark --file ./analysis.ipynb
+    nbexec exec --session spark --code "df.show()"
+    nbexec exec --session spark --file /tmp/query.py
+    nbexec session close --session spark
+    nbexec daemon stop
+
+  Inspect what was executed:
+    Open the .ipynb file in VS Code or Jupyter to see all cells and outputs.
+    The notebook is updated after every exec call.
+
+Runtime:
+  PID file:    ~/.local/state/nbexec/daemon.pid
+  Unix socket: ~/.local/state/nbexec/nbexec.sock
+  Log file:    ~/.local/state/nbexec/daemon.log
+"""
+
+
+class NbexecGroup(click.Group):
+    def format_help(self, ctx, formatter):
+        formatter.write(USAGE)
+
+
+@click.group(cls=NbexecGroup)
+def cli():
+    pass
+
+
+cli.add_command(daemon)
+cli.add_command(session)
+cli.add_command(exec_code, name="exec")
+cli.add_command(interrupt)