claude-nbexec 0.1.0__py3-none-any.whl

claude_nbexec-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,21 @@
+nbexec/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nbexec/paths.py,sha256=Zvx9wxDQjL3HNPuf61YHJdUfK3DmvoJoAytoRWmlQTw,362
+nbexec/protocol.py,sha256=drrVlASCFd1hq7rro-CxhbUm9a66HNcG4_zkoN2_YvY,815
+nbexec/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nbexec/cli/client.py,sha256=Jf6oKcFogSu2NMoq0nEVRo0x_vhy0MOwhE3dVZj7l6I,1564
+nbexec/cli/daemon_cmds.py,sha256=ZRfIlJEOUeh6kxlVNaLe2iXMvpvizJYjrqqdPA3zJ68,787
+nbexec/cli/exec_cmd.py,sha256=Zz8tGtA2SjzcZJcc99LQScXzvx2OHtMwxZhtjnky8Ok,3161
+nbexec/cli/interrupt_cmd.py,sha256=9l2jb7oSwSqhDou4qUNyayPdOC_lslTS9MP5sGioGpg,392
+nbexec/cli/main.py,sha256=ySmjJmf_9tbwKWHtw2-afB6fdPgsA26BQonjEHqrkco,6416
+nbexec/cli/session_cmds.py,sha256=LXS6jYza0dst5VkV7Wzwebx5a3vkTK6WThevYwA8QWQ,1860
+nbexec/daemon/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nbexec/daemon/process.py,sha256=zHGksZlPnc0wxF_Cmn8RQdU5m1U8BjlwunNfwM67Rb0,3005
+nbexec/daemon/server.py,sha256=VH2ZrsS4uikdKeSTZYYuq5Vxa1UnUn4C2ZrOkixEkKI,4601
+nbexec/daemon/state.py,sha256=lOB6p1-0WB2bYzcZ8oSOBD1syfrLtJsMu9-_2OGM-iA,1583
+nbexec/session/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nbexec/session/manager.py,sha256=kYB-9CwRPCB-SA3kJy3mAlYdq7ujZYyAzubivSq4tik,5238
+nbexec/session/notebook.py,sha256=-KLUJtVjDfMPG__eSTeJ-6Ext37N3WACp0InlsgH42I,2798
+claude_nbexec-0.1.0.dist-info/METADATA,sha256=-BCO3MRdRp03ki_vswAqzFlX-BrL8Ogyc3Q_vhzmV2Q,5703
+claude_nbexec-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+claude_nbexec-0.1.0.dist-info/entry_points.txt,sha256=MODFLALZOKEnYXZN2W8TmkG27NsTeTki5U8JX8fF9UY,47
+claude_nbexec-0.1.0.dist-info/RECORD,,

claude_nbexec-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

claude_nbexec-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+nbexec = nbexec.cli.main:cli

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

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.")

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)

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}'.")

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)

nbexec/cli/session_cmds.py

@@ -0,0 +1,53 @@
+import click
+
+from nbexec import protocol as proto
+from .client import send_to_daemon
+
+
+@click.group()
+def session():
+    """Manage kernel sessions."""
+    pass
+
+
+@session.command()
+@click.option("--server", required=True, help="Jupyter server URL (e.g. http://localhost:8888)")
+@click.option("--token", default="", help="Jupyter server token (optional if server has no auth)")
+@click.option("--notebook", required=True, help="Path for the local .ipynb file")
+@click.option("--name", default=None, help="Session name (auto-generated if omitted)")
+@click.option("--kernel", "kernel_name", default="python3", help="Kernel name")
+def create(server, token, notebook, name, kernel_name):
+    """Create a new session connected to a remote Jupyter server."""
+    result = send_to_daemon(proto.SESSION_CREATE, {
+        "server_url": server,
+        "token": token,
+        "notebook_path": notebook,
+        "name": name,
+        "kernel_name": kernel_name,
+    })
+    click.echo(f"Session created: {result['session_id']}")
+    click.echo(f"  Name:     {result['name']}")
+    click.echo(f"  Server:   {result['server_url']}")
+    click.echo(f"  Notebook: {result['notebook_path']}")
+
+
+@session.command("list")
+def list_sessions():
+    """List active sessions."""
+    sessions = send_to_daemon(proto.SESSION_LIST)
+    if not sessions:
+        click.echo("No active sessions.")
+        return
+    for s in sessions:
+        click.echo(
+            f"  {s['session_id']:<20s} {s['server_url']:<30s} "
+            f"cells={s['cell_count']:<4d} {s['notebook_path']}"
+        )
+
+
+@session.command()
+@click.option("--session", "session_id", required=True, help="Session ID to close")
+def close(session_id):
+    """Close a session and its remote kernel."""
+    send_to_daemon(proto.SESSION_CLOSE, {"session_id": session_id})
+    click.echo(f"Session '{session_id}' closed.")

nbexec/daemon/process.py

@@ -0,0 +1,135 @@
+import asyncio
+import logging
+import os
+import signal
+import sys
+import time
+
+from nbexec.paths import pid_path, log_path, socket_path
+from .server import DaemonServer
+
+
+def _setup_logging():
+    lp = log_path()
+    logging.basicConfig(
+        filename=str(lp),
+        level=logging.INFO,
+        format="%(asctime)s %(name)s %(levelname)s %(message)s",
+    )
+
+
+def _write_pid():
+    pid_path().write_text(str(os.getpid()))
+
+
+def _remove_pid():
+    pid_path().unlink(missing_ok=True)
+
+
+def daemonize() -> None:
+    """Double-fork to fully detach from the terminal."""
+    # First fork
+    pid = os.fork()
+    if pid > 0:
+        # Parent waits briefly for the daemon to create its PID file
+        for _ in range(20):
+            if pid_path().exists():
+                return
+            time.sleep(0.1)
+        return
+
+    # New session
+    os.setsid()
+
+    # Second fork
+    pid = os.fork()
+    if pid > 0:
+        os._exit(0)
+
+    # Redirect stdio
+    sys.stdin.close()
+    lp = log_path()
+    sys.stdout = open(lp, "a")
+    sys.stderr = sys.stdout
+
+    _setup_logging()
+    _write_pid()
+
+    def handle_sigterm(*_):
+        # The asyncio event loop will pick this up
+        raise SystemExit(0)
+
+    signal.signal(signal.SIGTERM, handle_sigterm)
+
+    try:
+        server = DaemonServer()
+        asyncio.run(server.run())
+    finally:
+        _remove_pid()
+        socket_path().unlink(missing_ok=True)
+        os._exit(0)
+
+
+def start_daemon() -> bool:
+    """Start the daemon. Returns True if started, False if already running."""
+    if is_daemon_running():
+        return False
+    # Clean stale files
+    pid_path().unlink(missing_ok=True)
+    socket_path().unlink(missing_ok=True)
+    daemonize()
+    return True
+
+
+def stop_daemon() -> bool:
+    """Stop the daemon via SIGTERM. Returns True if stopped."""
+    pp = pid_path()
+    if not pp.exists():
+        return False
+
+    pid = int(pp.read_text().strip())
+    try:
+        os.kill(pid, signal.SIGTERM)
+    except ProcessLookupError:
+        pp.unlink(missing_ok=True)
+        return False
+
+    # Wait for it to die
+    for _ in range(30):
+        try:
+            os.kill(pid, 0)
+            time.sleep(0.1)
+        except ProcessLookupError:
+            pp.unlink(missing_ok=True)
+            return True
+    return False
+
+
+def is_daemon_running() -> bool:
+    pp = pid_path()
+    if not pp.exists():
+        return False
+    try:
+        pid = int(pp.read_text().strip())
+        os.kill(pid, 0)
+        return True
+    except (ProcessLookupError, ValueError):
+        pp.unlink(missing_ok=True)
+        return False
+
+
+def daemon_status() -> dict:
+    pp = pid_path()
+    if not pp.exists():
+        return {"running": False}
+    try:
+        pid = int(pp.read_text().strip())
+        os.kill(pid, 0)
+        return {
+            "running": True,
+            "pid": pid,
+            "socket": str(socket_path()),
+        }
+    except (ProcessLookupError, ValueError):
+        pp.unlink(missing_ok=True)
+        return {"running": False}

nbexec/daemon/server.py

@@ -0,0 +1,127 @@
+import asyncio
+import json
+import logging
+from concurrent.futures import ThreadPoolExecutor
+
+from nbexec import protocol as proto
+from nbexec.paths import socket_path
+from .state import DaemonState
+
+logger = logging.getLogger("nbexec.daemon")
+
+
+class DaemonServer:
+    def __init__(self):
+        self.state = DaemonState()
+        self.executor = ThreadPoolExecutor(max_workers=8)
+        self.shutdown_event = asyncio.Event()
+
+    async def handle_client(
+        self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter
+    ):
+        try:
+            while True:
+                line = await reader.readline()
+                if not line:
+                    break
+                try:
+                    request = proto.decode(line)
+                except json.JSONDecodeError:
+                    writer.write(proto.encode(proto.make_error("?", "Invalid JSON")))
+                    await writer.drain()
+                    continue
+
+                req_id = request.get("id", "?")
+                method = request.get("method", "")
+                params = request.get("params", {})
+
+                response = await self.dispatch(req_id, method, params)
+                writer.write(proto.encode(response))
+                await writer.drain()
+        except asyncio.CancelledError:
+            pass
+        except Exception as e:
+            logger.exception("Error handling client: %s", e)
+        finally:
+            writer.close()
+            try:
+                await writer.wait_closed()
+            except Exception:
+                pass
+
+    async def dispatch(self, req_id: str, method: str, params: dict) -> dict:
+        loop = asyncio.get_event_loop()
+
+        try:
+            if method == proto.DAEMON_STOP:
+                self.shutdown_event.set()
+                return proto.make_response(req_id, {"message": "shutting down"})
+
+            elif method == proto.SESSION_CREATE:
+                session = await loop.run_in_executor(
+                    self.executor,
+                    lambda: self.state.create_session(
+                        server_url=params["server_url"],
+                        token=params["token"],
+                        notebook_path=params["notebook_path"],
+                        name=params.get("name"),
+                        kernel_name=params.get("kernel_name", "python3"),
+                    ),
+                )
+                return proto.make_response(req_id, session.to_info())
+
+            elif method == proto.SESSION_LIST:
+                return proto.make_response(req_id, self.state.list_sessions())
+
+            elif method == proto.SESSION_CLOSE:
+                await loop.run_in_executor(
+                    self.executor,
+                    lambda: self.state.close_session(params["session_id"]),
+                )
+                return proto.make_response(req_id, {"closed": params["session_id"]})
+
+            elif method == proto.EXEC:
+                session = self.state.get_session(params["session_id"])
+                result = await loop.run_in_executor(
+                    self.executor,
+                    lambda: session.execute(params["code"]),
+                )
+                return proto.make_response(req_id, result)
+
+            elif method == proto.INTERRUPT:
+                session = self.state.get_session(params["session_id"])
+                await loop.run_in_executor(
+                    self.executor,
+                    lambda: session.interrupt(),
+                )
+                return proto.make_response(req_id, {"interrupted": params["session_id"]})
+
+            else:
+                return proto.make_error(req_id, f"Unknown method: {method}")
+
+        except KeyError as e:
+            return proto.make_error(req_id, str(e))
+        except ValueError as e:
+            return proto.make_error(req_id, str(e))
+        except Exception as e:
+            logger.exception("Error in dispatch: %s", e)
+            return proto.make_error(req_id, f"{type(e).__name__}: {e}")
+
+    async def run(self) -> None:
+        sock = socket_path()
+        # Clean up stale socket
+        sock.unlink(missing_ok=True)
+
+        server = await asyncio.start_unix_server(self.handle_client, path=str(sock))
+        logger.info("Daemon listening on %s", sock)
+
+        # Wait for shutdown signal
+        await self.shutdown_event.wait()
+
+        logger.info("Shutting down...")
+        server.close()
+        await server.wait_closed()
+        self.state.close_all()
+        self.executor.shutdown(wait=False)
+        sock.unlink(missing_ok=True)
+        logger.info("Daemon stopped.")

nbexec/daemon/state.py

@@ -0,0 +1,54 @@
+import secrets
+from pathlib import Path
+
+from nbexec.session.manager import Session
+
+
+class DaemonState:
+    """Registry of active sessions."""
+
+    def __init__(self):
+        self.sessions: dict[str, Session] = {}
+
+    def create_session(
+        self,
+        server_url: str,
+        token: str,
+        notebook_path: str,
+        name: str | None = None,
+        kernel_name: str = "python3",
+    ) -> Session:
+        session_id = name or secrets.token_hex(4)
+        if session_id in self.sessions:
+            raise ValueError(f"Session '{session_id}' already exists")
+
+        session = Session(
+            session_id=session_id,
+            server_url=server_url,
+            token=token,
+            notebook_path=Path(notebook_path),
+            name=name,
+            kernel_name=kernel_name,
+        )
+        session.start()
+        self.sessions[session_id] = session
+        return session
+
+    def get_session(self, session_id: str) -> Session:
+        if session_id not in self.sessions:
+            raise KeyError(f"Session '{session_id}' not found")
+        return self.sessions[session_id]
+
+    def list_sessions(self) -> list[dict]:
+        return [s.to_info() for s in self.sessions.values()]
+
+    def close_session(self, session_id: str) -> None:
+        session = self.sessions.pop(session_id, None)
+        if session is None:
+            raise KeyError(f"Session '{session_id}' not found")
+        session.close()
+
+    def close_all(self) -> None:
+        for session in self.sessions.values():
+            session.close()
+        self.sessions.clear()

nbexec/paths.py

@@ -0,0 +1,19 @@
+from pathlib import Path
+
+
+def runtime_dir() -> Path:
+    d = Path.home() / ".local" / "state" / "nbexec"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def pid_path() -> Path:
+    return runtime_dir() / "daemon.pid"
+
+
+def socket_path() -> Path:
+    return runtime_dir() / "nbexec.sock"
+
+
+def log_path() -> Path:
+    return runtime_dir() / "daemon.log"

nbexec/protocol.py

@@ -0,0 +1,36 @@
+import json
+import uuid
+from typing import Any
+
+
+# Method names
+DAEMON_STOP = "daemon.stop"
+SESSION_CREATE = "session.create"
+SESSION_LIST = "session.list"
+SESSION_CLOSE = "session.close"
+EXEC = "exec"
+INTERRUPT = "interrupt"
+
+
+def make_request(method: str, params: dict[str, Any] | None = None) -> dict:
+    return {
+        "id": uuid.uuid4().hex[:12],
+        "method": method,
+        "params": params or {},
+    }
+
+
+def make_response(request_id: str, result: Any = None) -> dict:
+    return {"id": request_id, "ok": True, "result": result}
+
+
+def make_error(request_id: str, error: str) -> dict:
+    return {"id": request_id, "ok": False, "error": error}
+
+
+def encode(msg: dict) -> bytes:
+    return json.dumps(msg).encode("utf-8") + b"\n"
+
+
+def decode(line: bytes) -> dict:
+    return json.loads(line.strip())

nbexec/session/manager.py

@@ -0,0 +1,157 @@
+from pathlib import Path
+from datetime import datetime, timezone
+
+import requests
+from jupyter_kernel_client import KernelClient
+
+from .notebook import NotebookWriter
+
+
+class Session:
+    """A session owns a remote kernel connection and a local notebook file."""
+
+    def __init__(
+        self,
+        session_id: str,
+        server_url: str,
+        token: str,
+        notebook_path: Path,
+        name: str | None = None,
+        kernel_name: str = "python3",
+    ):
+        self.session_id = session_id
+        self.server_url = server_url.rstrip("/")
+        self.token = token
+        self.notebook_path = Path(notebook_path)
+        self.name = name or session_id
+        self.kernel_name = kernel_name
+        self.kernel: KernelClient | None = None
+        self.notebook: NotebookWriter | None = None
+        self.created_at = datetime.now(timezone.utc).isoformat()
+        self._execution_count = 0
+
+    def start(self) -> None:
+        self.notebook = NotebookWriter(self.notebook_path)
+
+        # Fetch XSRF cookie from the server (needed for POST requests)
+        headers = {}
+        xsrf_cookie = self._fetch_xsrf_cookie()
+        if xsrf_cookie:
+            headers["X-XSRFToken"] = xsrf_cookie
+            headers["Cookie"] = f"_xsrf={xsrf_cookie}"
+
+        self.kernel = KernelClient(
+            server_url=self.server_url,
+            token=self.token or None,
+            headers=headers,
+        )
+        self.kernel.start(name=self.kernel_name)
+
+    def _fetch_xsrf_cookie(self) -> str | None:
+        """Fetch XSRF token from the Jupyter server."""
+        try:
+            resp = requests.get(f"{self.server_url}/tree", timeout=10)
+            xsrf = resp.cookies.get("_xsrf")
+            return xsrf
+        except Exception:
+            return None
+
+    def execute(self, code: str) -> dict:
+        if self.kernel is None or self.notebook is None:
+            raise RuntimeError("Session not started")
+
+        cell_index = self.notebook.add_cell(code)
+        self._execution_count += 1
+
+        try:
+            reply = self.kernel.execute(code)
+        except Exception as e:
+            error_output = {
+                "output_type": "error",
+                "ename": type(e).__name__,
+                "evalue": str(e),
+                "traceback": [str(e)],
+            }
+            self.notebook.set_outputs(cell_index, [error_output])
+            self.notebook.set_execution_count(cell_index, self._execution_count)
+            self.notebook.flush()
+            return {
+                "status": "error",
+                "execution_count": self._execution_count,
+                "cell_index": cell_index,
+                "outputs": [error_output],
+                "text": str(e),
+            }
+
+        outputs = self._extract_outputs(reply)
+        exec_count = reply.get("execution_count", self._execution_count)
+        self.notebook.set_outputs(cell_index, outputs)
+        self.notebook.set_execution_count(cell_index, exec_count)
+        self.notebook.flush()
+
+        text = self._outputs_to_text(outputs)
+        status = reply.get("status", "ok")
+
+        return {
+            "status": status,
+            "execution_count": exec_count,
+            "cell_index": cell_index,
+            "outputs": outputs,
+            "text": text,
+        }
+
+    def interrupt(self) -> None:
+        if self.kernel is None:
+            raise RuntimeError("Session not started")
+        self.kernel.interrupt()
+
+    def close(self) -> None:
+        if self.kernel is not None:
+            try:
+                self.kernel.stop()
+            except Exception:
+                pass
+            self.kernel = None
+        if self.notebook is not None:
+            try:
+                self.notebook.flush()
+            except Exception:
+                pass
+
+    def to_info(self) -> dict:
+        return {
+            "session_id": self.session_id,
+            "name": self.name,
+            "server_url": self.server_url,
+            "notebook_path": str(self.notebook_path),
+            "cell_count": self.notebook.cell_count if self.notebook else 0,
+            "created_at": self.created_at,
+        }
+
+    @staticmethod
+    def _extract_outputs(reply: dict) -> list[dict]:
+        """Extract outputs from jupyter-kernel-client reply.
+
+        Reply format: {"execution_count": int, "status": str, "outputs": list[dict]}
+        Outputs follow nbformat structure.
+        """
+        return reply.get("outputs", [])
+
+    @staticmethod
+    def _outputs_to_text(outputs: list[dict]) -> str:
+        """Flatten outputs to plain text for CLI display."""
+        parts = []
+        for o in outputs:
+            otype = o.get("output_type", "")
+            if otype == "stream":
+                parts.append(o.get("text", ""))
+            elif otype == "error":
+                tb = o.get("traceback", [])
+                parts.append("\n".join(tb) if tb else o.get("evalue", ""))
+            elif otype in ("execute_result", "display_data"):
+                data = o.get("data", {})
+                if "text/plain" in data:
+                    parts.append(data["text/plain"])
+                elif "text/html" in data:
+                    parts.append(data["text/html"])
+        return "\n".join(parts)

nbexec/session/notebook.py

@@ -0,0 +1,85 @@
+import os
+import tempfile
+from pathlib import Path
+
+import nbformat
+from nbformat.v4 import new_code_cell, new_notebook
+
+
+class NotebookWriter:
+    """Append-only .ipynb writer. Adds code cells and their outputs."""
+
+    def __init__(self, path: Path):
+        self.path = Path(path)
+        if self.path.exists():
+            with open(self.path) as f:
+                self.nb = nbformat.read(f, as_version=4)
+        else:
+            self.nb = new_notebook()
+            self.nb.metadata["kernelspec"] = {
+                "display_name": "Python 3",
+                "language": "python",
+                "name": "python3",
+            }
+            self.flush()
+
+    def add_cell(self, source: str) -> int:
+        cell = new_code_cell(source=source)
+        self.nb.cells.append(cell)
+        return len(self.nb.cells) - 1
+
+    def set_outputs(self, cell_index: int, outputs: list[dict]) -> None:
+        cell = self.nb.cells[cell_index]
+        cell.outputs = [self._normalize_output(o) for o in outputs]
+
+    def set_execution_count(self, cell_index: int, count: int | None) -> None:
+        if count is not None:
+            self.nb.cells[cell_index].execution_count = count
+
+    def flush(self) -> None:
+        """Atomic write: write to temp file then rename."""
+        dir_ = self.path.parent
+        dir_.mkdir(parents=True, exist_ok=True)
+        fd, tmp = tempfile.mkstemp(dir=dir_, suffix=".ipynb.tmp")
+        try:
+            with os.fdopen(fd, "w") as f:
+                nbformat.write(self.nb, f)
+            os.replace(tmp, self.path)
+        except BaseException:
+            try:
+                os.unlink(tmp)
+            except OSError:
+                pass
+            raise
+
+    @property
+    def cell_count(self) -> int:
+        return len(self.nb.cells)
+
+    @staticmethod
+    def _normalize_output(output: dict) -> nbformat.NotebookNode:
+        """Convert a raw output dict to an nbformat output node."""
+        otype = output.get("output_type", "execute_result")
+
+        if otype == "stream":
+            return nbformat.v4.new_output(
+                output_type="stream",
+                name=output.get("name", "stdout"),
+                text=output.get("text", ""),
+            )
+        elif otype == "error":
+            return nbformat.v4.new_output(
+                output_type="error",
+                ename=output.get("ename", ""),
+                evalue=output.get("evalue", ""),
+                traceback=output.get("traceback", []),
+            )
+        else:
+            # execute_result or display_data
+            data = output.get("data", {})
+            metadata = output.get("metadata", {})
+            return nbformat.v4.new_output(
+                output_type=otype,
+                data=data,
+                metadata=metadata,
+            )