jupyter-link 0.1.0 → 0.2.1

package/README.md

@@ -1,54 +1,52 @@
 # jupyter-link
 
-CLI and AgentSkill to execute code in running Jupyter kernels and persist outputs back to `.ipynb` notebooks.
+An [AgentSkill](https://agentskills.io) that lets AI agents execute code in running Jupyter kernels and persist outputs back to `.ipynb` notebooks.
 
-## Features
+## Why
 
-- Discover running sessions and match by notebook path or name
-- Read/write notebooks via Jupyter Contents API (nbformat v4)
-- Insert or update code cells with agent metadata (`metadata.agent`)
-- Open persistent kernel WebSocket channels for execution
-- Send `execute_request` and collect iopub/shell outputs
-- Map outputs to nbformat v4 format (stream, execute_result, display_data, error)
-- Persistent config — set URL and token once, use everywhere
+AI agents like Claude Code or Codex are great at writing and executing code, but they work in a terminal — no charts, no rich tables, no inline visualizations. Jupyter has all of that, but it's a manual, interactive tool.
 
-## Requirements
+**jupyter-link bridges the two.** The agent writes code, executes it in your notebook's kernel, and persists the outputs — while you keep JupyterLab open as your live dashboard. Changes appear in real time. You see rendered DataFrames, plots, and errors exactly as Jupyter displays them, without copy-pasting anything.
 
-- Node.js 20+
-- A running Jupyter Server (JupyterLab/Notebook)
+The result: **the agent codes, Jupyter renders, you supervise.** You can jump in at any point — edit a cell, re-run something, add notes — and the agent picks up where you left off. True human-AI collaboration on notebooks, where each side uses the interface it's best at.
 
-## Installation
+## Install as a Skill
 
-### As a global CLI
 ```bash
-npm install -g jupyter-link
+npx skills add rarce/jupyter-link
 ```
 
-### Via npx (no install)
-```bash
-echo '{}' | npx jupyter-link@0.1.0 check:env
-```
+Once installed, the agent uses `npx jupyter-link@0.1.0` to run commands. No global install required.
 
-### As an AgentSkill
-```bash
-npx skills add <owner/repo>
-```
+## What it does
+
+- Discover running Jupyter sessions and match by notebook path or name
+- Read/write notebooks via Contents API (nbformat v4)
+- Insert or update code cells with agent metadata
+- Execute code in kernels via persistent WebSocket channels
+- Collect outputs (stream, execute_result, display_data, error)
+- Persist execution results and save notebooks
+
+## Requirements
+
+- Node.js 20+
+- A running Jupyter Server (JupyterLab or Notebook)
 
 ## Quick Start
 
-```bash
-# 1. Configure connection (saved to ~/.config/jupyter-link/config.json)
-echo '{"url":"http://localhost:8888","token":"your-token"}' | npx jupyter-link@0.1.0 config:set
+1. Start your Jupyter Server (JupyterLab or Notebook)
+2. Tell your agent:
 
-# 2. Verify connectivity
-echo '{}' | npx jupyter-link@0.1.0 check:env
+> Connect to my Jupyter Server at http://localhost:8888 with token `abc123`, then run the code `print("hello")` in `notebook.ipynb`
 
-# 3. List running sessions
-echo '{}' | npx jupyter-link@0.1.0 list:sessions
+The agent will use the skill to configure the connection, open a kernel channel, execute the code, and persist the output to the notebook.
 
-# 4. Read cell outputs
-echo '{"path":"notebook.ipynb","cells":[0,1,2]}' | npx jupyter-link@0.1.0 cell:read
-```
+### Other things you can ask
+
+- *"Show me the outputs of cells 4, 8 and 12 in my notebook"*
+- *"Execute this data processing code in my notebook and save the results"*
+- *"List all running Jupyter sessions"*
+- *"Insert a new cell at the end of notebook.ipynb with this code: ..."*
 
 ## Commands
 
@@ -81,11 +79,13 @@ Priority: environment variables > config file > defaults.
 | Config file | `url` | `token` | `port` |
 | Default | `http://127.0.0.1:8888` | — | `32123` |
 
-## Tests
+## Standalone CLI
+
+You can also install and use it directly without the skills framework:
 
 ```bash
-npm test                    # Run all tests
-npm run test:coverage       # With coverage report
+npm install -g jupyter-link
+echo '{}' | jupyter-link check:env
 ```
 
 ## License

package/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: jupyter-link
+description: Execute code in running Jupyter kernels and persist outputs to the target notebook via Jupyter Server REST API and kernel WebSocket channels. Implements discovery of sessions, cell insert/update, execution, and output mapping (nbformat v4).
+compatibility: Requires Node.js 20+ and npm
+allowed-tools: Bash(npx jupyter-link:*)
+metadata:
+  version: "0.2.1"
+  author: Roberto Arce
+---
+
+## IMPORTANT: Always use the `jupyter-link` CLI via npx
+
+**NEVER use Python, curl, or raw HTTP requests to interact with Jupyter Server.**
+All operations MUST go through `npx jupyter-link@0.2.1`. Every command reads JSON from stdin and writes JSON to stdout.
+
+## Commands Reference
+
+### Configure connection (persistent — run once)
+```bash
+# Save URL and token to ~/.config/jupyter-link/config.json
+echo '{"url":"http://localhost:8888","token":"your-token-here"}' | npx jupyter-link@0.2.1 config:set
+
+# Show effective config and where each value comes from
+echo '{}' | npx jupyter-link@0.2.1 config:get
+```
+After `config:set`, all subsequent commands use the saved config. No need to pass env vars.
+Environment variables (`JUPYTER_URL`, `JUPYTER_TOKEN`) still override the config file if set.
+
+### Check connectivity
+```bash
+echo '{}' | npx jupyter-link@0.2.1 check:env
+```
+Returns `{"ok":true|false, "sessions_ok":..., "contents_ok":...}`
+
+### Create a notebook
+```bash
+# Create an empty Python3 notebook (generates nbformat v4 boilerplate)
+echo '{"path":"notebooks/new.ipynb"}' | npx jupyter-link@0.2.1 contents:create
+
+# Create with a specific kernel
+echo '{"path":"notebooks/new.ipynb","kernel_name":"julia-1.9"}' | npx jupyter-link@0.2.1 contents:create
+```
+Returns `{"ok":true,"created":true|false,"path":"..."}`. If notebook already exists, returns `created:false` without overwriting.
+
+### Create a session (start a kernel)
+```bash
+echo '{"path":"notebooks/my.ipynb"}' | npx jupyter-link@0.2.1 sessions:create
+echo '{"path":"notebooks/my.ipynb","kernel_name":"python3"}' | npx jupyter-link@0.2.1 sessions:create
+```
+Returns the full Jupyter session object with `id`, `kernel.id`, `kernel.name`, etc. If a session already exists for the notebook, returns it without creating a duplicate.
+
+### List sessions
+```bash
+echo '{}' | npx jupyter-link@0.2.1 list:sessions
+echo '{"path":"notebooks/my.ipynb"}' | npx jupyter-link@0.2.1 list:sessions
+```
+
+### Read cells (preferred for inspection)
+```bash
+# Summary of all cells (index, type, source preview, has_outputs)
+echo '{"path":"notebooks/my.ipynb"}' | npx jupyter-link@0.2.1 cell:read
+
+# Read specific cells by index
+echo '{"path":"notebooks/my.ipynb","cells":[4,8,10,12]}' | npx jupyter-link@0.2.1 cell:read
+
+# Read a single cell
+echo '{"path":"notebooks/my.ipynb","cell_id":4}' | npx jupyter-link@0.2.1 cell:read
+
+# Read a range of cells (start inclusive, end exclusive)
+echo '{"path":"notebooks/my.ipynb","range":[4,10]}' | npx jupyter-link@0.2.1 cell:read
+
+# Control output truncation (default: 3000 chars per field)
+echo '{"path":"notebooks/my.ipynb","cells":[4],"max_chars":5000}' | npx jupyter-link@0.2.1 cell:read
+```
+Returns `{"total_cells":N,"cells":[...]}` with source, outputs, execution_count, and agent metadata.
+Binary outputs (images, PDFs) are replaced with size placeholders. Error tracebacks keep last 5 frames.
+
+### Read notebook (full JSON)
+```bash
+echo '{"path":"notebooks/my.ipynb"}' | npx jupyter-link@0.2.1 contents:read
+```
+
+### Write notebook
+```bash
+echo '{"path":"notebooks/my.ipynb","nb_json":{...}}' | npx jupyter-link@0.2.1 contents:write
+```
+
+### Insert a code cell
+```bash
+echo '{"path":"notebooks/my.ipynb","code":"print(42)"}' | npx jupyter-link@0.2.1 cell:insert
+echo '{"path":"notebooks/my.ipynb","code":"print(42)","index":0}' | npx jupyter-link@0.2.1 cell:insert
+```
+Returns `{"cell_id":N,"index":N}`. Defaults to appending at end.
+
+### Update a cell
+```bash
+echo '{"path":"notebooks/my.ipynb","cell_id":3,"code":"x=1"}' | npx jupyter-link@0.2.1 cell:update
+echo '{"path":"notebooks/my.ipynb","cell_id":3,"outputs":[...],"execution_count":5}' | npx jupyter-link@0.2.1 cell:update
+```
+If `cell_id` is omitted, updates the latest agent-managed cell.
+
+### Open kernel channels (persistent WebSocket)
+```bash
+echo '{"path":"notebooks/my.ipynb"}' | npx jupyter-link@0.2.1 open:kernel-channels
+echo '{"kernel_id":"..."}' | npx jupyter-link@0.2.1 open:kernel-channels
+```
+Returns `{"channel_ref":"ch-...","session_id":"..."}`. Auto-starts daemon if needed.
+**Auto-creates session**: If no running session exists for the notebook, automatically creates one (defaults to `python3` kernel, override with `kernel_name`).
+
+### Run cell (insert + execute + collect + update in one step)
+```bash
+echo '{"path":"notebooks/my.ipynb","channel_ref":"ch-...","code":"print(42)"}' | npx jupyter-link@0.2.1 run:cell
+echo '{"path":"notebooks/my.ipynb","channel_ref":"ch-...","code":"import time; time.sleep(5)","timeout_s":30}' | npx jupyter-link@0.2.1 run:cell
+```
+Returns `{"cell_id":N,"status":"ok"|"error","execution_count":N,"outputs":[...]}`.
+This is the **recommended** way to execute code — it handles the full pipeline: insert cell, execute on kernel, collect outputs, and update the cell with results.
+
+### Execute code on a channel
+```bash
+echo '{"channel_ref":"ch-...","code":"print(123)"}' | npx jupyter-link@0.2.1 execute:code
+```
+Returns `{"parent_msg_id":"msg-..."}`.
+
+### Collect execution outputs
+```bash
+echo '{"channel_ref":"ch-...","parent_msg_id":"msg-..."}' | npx jupyter-link@0.2.1 collect:outputs
+echo '{"channel_ref":"ch-...","parent_msg_id":"msg-...","timeout_s":120}' | npx jupyter-link@0.2.1 collect:outputs
+```
+Returns `{"outputs":[...],"execution_count":N,"status":"ok"|"error"|"timeout"}`.
+
+### Close channels
+```bash
+echo '{"channel_ref":"ch-..."}' | npx jupyter-link@0.2.1 close:channels
+```
+
+### Save notebook
+```bash
+echo '{"path":"notebooks/my.ipynb"}' | npx jupyter-link@0.2.1 save:notebook
+```
+
+## Typical workflow
+
+### Recommended (using `run:cell`)
+1. **Configure**: `echo '{"url":"...","token":"..."}' | npx jupyter-link@0.2.1 config:set`
+2. **Check env**: `echo '{}' | npx jupyter-link@0.2.1 check:env`
+3. **Create notebook** (if needed): `echo '{"path":"..."}' | npx jupyter-link@0.2.1 contents:create`
+4. **Open channel**: `echo '{"path":"..."}' | npx jupyter-link@0.2.1 open:kernel-channels` → get `channel_ref` (auto-creates session if needed)
+5. **Run cell** (repeat): `echo '{"path":"...","channel_ref":"...","code":"..."}' | npx jupyter-link@0.2.1 run:cell` → get `cell_id`, `status`, `outputs`
+6. **Save**: `echo '{"path":"..."}' | npx jupyter-link@0.2.1 save:notebook`
+7. **Close**: `echo '{"channel_ref":"..."}' | npx jupyter-link@0.2.1 close:channels`
+
+### Granular (step-by-step control)
+1. **Configure**: `echo '{"url":"...","token":"..."}' | npx jupyter-link@0.2.1 config:set`
+2. **Check env**: `echo '{}' | npx jupyter-link@0.2.1 check:env`
+3. **Create notebook** (if needed): `echo '{"path":"..."}' | npx jupyter-link@0.2.1 contents:create`
+4. **Create session** (if needed): `echo '{"path":"..."}' | npx jupyter-link@0.2.1 sessions:create`
+5. **Open channel**: `echo '{"path":"..."}' | npx jupyter-link@0.2.1 open:kernel-channels` → get `channel_ref`
+6. **Insert cell**: `echo '{"path":"...","code":"..."}' | npx jupyter-link@0.2.1 cell:insert` → get `index`
+7. **Execute**: `echo '{"channel_ref":"...","code":"..."}' | npx jupyter-link@0.2.1 execute:code` → get `parent_msg_id`
+8. **Collect**: `echo '{"channel_ref":"...","parent_msg_id":"..."}' | npx jupyter-link@0.2.1 collect:outputs` → get outputs
+9. **Update cell**: `echo '{"path":"...","cell_id":N,"outputs":[...],"execution_count":N}' | npx jupyter-link@0.2.1 cell:update`
+10. **Save**: `echo '{"path":"..."}' | npx jupyter-link@0.2.1 save:notebook`
+11. **Close**: `echo '{"channel_ref":"..."}' | npx jupyter-link@0.2.1 close:channels`
+
+## Notes
+
+- Inserts cells at end by default. Reuses latest agent cell (`metadata.agent.role="jupyter-driver"`) when `cell_id` is omitted in update.
+- Kernel errors are surfaced as `error` outputs with traceback.
+- Persistent channels are managed by a daemon on `127.0.0.1:${JUPYTER_LINK_PORT:-32123}`. Auto-starts on first use.
+
+## Canonical parameter names
+
+| Primary        | Fallback     | Used in                             |
+|----------------|--------------|-------------------------------------|
+| `path`         | `notebook`   | All notebook commands               |
+| `code`         | `source`     | insert, update, execute, run:cell   |
+| `channel_ref`  | `ref`        | execute, collect, close, run:cell   |
+| `parent_msg_id`| `parent_id`  | collect                             |
+| `nb_json`      | `content`    | write                               |
+| `kernel_name`  | `kernel`     | sessions:create, contents:create, open:kernel-channels |

package/oclif.manifest.json

@@ -84,6 +84,27 @@
         "env.mjs"
       ]
     },
+    "collect:outputs": {
+      "aliases": [],
+      "args": {},
+      "description": "Wait for outputs/reply/idle for a parent_msg_id on a channel",
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "collect:outputs",
+      "pluginAlias": "jupyter-link",
+      "pluginName": "jupyter-link",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "src",
+        "commands",
+        "collect",
+        "outputs.mjs"
+      ]
+    },
     "close:channels": {
       "aliases": [],
       "args": {},
@@ -105,14 +126,14 @@
         "channels.mjs"
       ]
     },
-    "collect:outputs": {
+    "contents:create": {
       "aliases": [],
       "args": {},
-      "description": "Wait for outputs/reply/idle for a parent_msg_id on a channel",
+      "description": "Create a new empty notebook with proper nbformat v4 boilerplate",
       "flags": {},
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "collect:outputs",
+      "id": "contents:create",
       "pluginAlias": "jupyter-link",
       "pluginName": "jupyter-link",
       "pluginType": "core",
@@ -122,8 +143,8 @@
       "relativePath": [
         "src",
         "commands",
-        "collect",
-        "outputs.mjs"
+        "contents",
+        "create.mjs"
       ]
     },
     "contents:read": {
@@ -168,6 +189,27 @@
         "write.mjs"
       ]
     },
+    "list:sessions": {
+      "aliases": [],
+      "args": {},
+      "description": "List sessions and optionally filter by path or name",
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "list:sessions",
+      "pluginAlias": "jupyter-link",
+      "pluginName": "jupyter-link",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "src",
+        "commands",
+        "list",
+        "sessions.mjs"
+      ]
+    },
     "execute:code": {
       "aliases": [],
       "args": {},
@@ -189,14 +231,14 @@
         "code.mjs"
       ]
     },
-    "list:sessions": {
+    "run:cell": {
       "aliases": [],
       "args": {},
-      "description": "List sessions and optionally filter by path or name",
+      "description": "Insert a cell, execute it, collect outputs, and update the cell in one step",
       "flags": {},
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "list:sessions",
+      "id": "run:cell",
       "pluginAlias": "jupyter-link",
       "pluginName": "jupyter-link",
       "pluginType": "core",
@@ -206,8 +248,29 @@
       "relativePath": [
         "src",
         "commands",
-        "list",
-        "sessions.mjs"
+        "run",
+        "cell.mjs"
+      ]
+    },
+    "open:kernel-channels": {
+      "aliases": [],
+      "args": {},
+      "description": "Open persistent kernel WS channels and return a channel_ref",
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "open:kernel-channels",
+      "pluginAlias": "jupyter-link",
+      "pluginName": "jupyter-link",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "src",
+        "commands",
+        "open",
+        "kernel-channels.mjs"
       ]
     },
     "config:get": {
@@ -252,14 +315,14 @@
         "set.mjs"
       ]
     },
-    "open:kernel-channels": {
+    "save:notebook": {
       "aliases": [],
       "args": {},
-      "description": "Open persistent kernel WS channels and return a channel_ref",
+      "description": "Save notebook (round-trip PUT)",
       "flags": {},
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "open:kernel-channels",
+      "id": "save:notebook",
       "pluginAlias": "jupyter-link",
       "pluginName": "jupyter-link",
       "pluginType": "core",
@@ -269,18 +332,18 @@
       "relativePath": [
         "src",
         "commands",
-        "open",
-        "kernel-channels.mjs"
+        "save",
+        "notebook.mjs"
       ]
     },
-    "save:notebook": {
+    "sessions:create": {
       "aliases": [],
       "args": {},
-      "description": "Save notebook (round-trip PUT)",
+      "description": "Create a Jupyter session (start a kernel) for a notebook",
       "flags": {},
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "save:notebook",
+      "id": "sessions:create",
       "pluginAlias": "jupyter-link",
       "pluginName": "jupyter-link",
       "pluginType": "core",
@@ -290,10 +353,10 @@
       "relativePath": [
         "src",
         "commands",
-        "save",
-        "notebook.mjs"
+        "sessions",
+        "create.mjs"
       ]
     }
   },
-  "version": "0.1.0"
+  "version": "0.2.1"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jupyter-link",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "CLI and AgentSkill to execute code in Jupyter kernels and persist outputs to notebooks",
   "type": "module",
   "license": "MIT",
@@ -27,7 +27,9 @@
     "bin",
     "src",
     "scripts",
-    "oclif.manifest.json"
+    "oclif.manifest.json",
+    "skills.json",
+    "SKILL.md"
   ],
   "dependencies": {
     "@oclif/core": "^3.26.3"

package/skills.json

@@ -0,0 +1,30 @@
+{
+  "name": "jupyter-link",
+  "version": "0.2.1",
+  "description": "Execute code in Jupyter kernels and persist outputs to notebooks",
+  "using": "scripts",
+  "environment": {
+    "JUPYTER_URL": {"description": "Base URL, e.g. http://127.0.0.1:8888", "required": false},
+    "JUPYTER_TOKEN": {"description": "Server token if required", "required": false}
+  },
+  "tools": {
+    "config_set": { "description": "Save Jupyter connection settings (url, token, port) to persistent config file", "command": "npx jupyter-link@0.2.1 config:set", "stdin": "json", "stdout": "json" },
+    "config_get": { "description": "Show effective configuration with source (env/file/default) for each field", "command": "npx jupyter-link@0.2.1 config:get", "stdin": "json", "stdout": "json" },
+    "check_env": { "description": "Verify connectivity and basic Jupyter Server compatibility", "command": "npx jupyter-link@0.2.1 check:env", "stdin": "json", "stdout": "json" },
+    "list_sessions": { "description": "List sessions and optionally filter by path or name", "command": "npx jupyter-link@0.2.1 list:sessions", "stdin": "json", "stdout": "json" },
+    "read_notebook": { "description": "Read a notebook JSON via Contents API", "command": "npx jupyter-link@0.2.1 contents:read", "stdin": "json", "stdout": "json" },
+    "write_notebook": { "description": "Write notebook JSON via Contents API", "command": "npx jupyter-link@0.2.1 contents:write", "stdin": "json", "stdout": "json" },
+    "read_cell": { "description": "Read specific cells with source, outputs, and metadata. Supports single cell, list, range, or full summary", "command": "npx jupyter-link@0.2.1 cell:read", "stdin": "json", "stdout": "json" },
+    "insert_cell": { "description": "Insert a code cell with agent metadata", "command": "npx jupyter-link@0.2.1 cell:insert", "stdin": "json", "stdout": "json" },
+    "update_cell": { "description": "Update a code cell (source/outputs/execution_count/metadata)", "command": "npx jupyter-link@0.2.1 cell:update", "stdin": "json", "stdout": "json" },
+    "open_kernel_channels": { "description": "Open persistent kernel WS channels and return a channel_ref. Auto-creates session if none exists for the notebook", "command": "npx jupyter-link@0.2.1 open:kernel-channels", "stdin": "json", "stdout": "json" },
+    "execute_code": { "description": "Send execute_request on an open channel and return parent_msg_id", "command": "npx jupyter-link@0.2.1 execute:code", "stdin": "json", "stdout": "json" },
+    "collect_outputs": { "description": "Wait for outputs/reply/idle for a parent_msg_id on a channel", "command": "npx jupyter-link@0.2.1 collect:outputs", "stdin": "json", "stdout": "json" },
+    "close_channels": { "description": "Close a previously opened channel_ref", "command": "npx jupyter-link@0.2.1 close:channels", "stdin": "json", "stdout": "json" },
+    "save_notebook": { "description": "Save notebook (round-trip PUT)", "command": "npx jupyter-link@0.2.1 save:notebook", "stdin": "json", "stdout": "json" },
+    "create_notebook": { "description": "Create a new empty notebook via Contents API. Idempotent (returns existing if found). Accepts kernel_name, language, display_name", "command": "npx jupyter-link@0.2.1 contents:create", "stdin": "json", "stdout": "json" },
+    "create_session": { "description": "Create a Jupyter session (start kernel) for a notebook. Idempotent (returns existing session if found)", "command": "npx jupyter-link@0.2.1 sessions:create", "stdin": "json", "stdout": "json" },
+    "run_cell": { "description": "Insert, execute, and collect outputs for a cell in one compound command. Returns cell index, outputs, and execution status", "command": "npx jupyter-link@0.2.1 run:cell", "stdin": "json", "stdout": "json" },
+    "test_api": { "description": "Validate Jupyter Server REST API compatibility using the official OpenAPI schema", "command": "node scripts/test_api.mjs", "stdin": "json", "stdout": "json" }
+  }
+}

package/src/commands/contents/create.mjs

@@ -0,0 +1,37 @@
+import { Command } from '@oclif/core';
+import { getConfig, httpJson, readStdinJson, ok, assertNodeVersion } from '../../lib/common.mjs';
+
+export default class ContentsCreate extends Command {
+  static description = 'Create a new empty notebook with proper nbformat v4 boilerplate';
+  async run() {
+    assertNodeVersion();
+    const input = await readStdinJson();
+    const path = input.path ?? input.notebook;
+    if (!path) throw new Error('path is required');
+    const kernelName = input.kernel_name ?? input.kernel ?? 'python3';
+    const displayName = input.display_name ?? kernelName.replace(/^\w/, c => c.toUpperCase()).replace(/(\d)/, ' $1');
+    const language = input.language ?? (kernelName.startsWith('python') ? 'python' : kernelName);
+    const { baseUrl, token } = getConfig();
+
+    // Check if notebook already exists
+    try {
+      const existing = await httpJson('GET', `${baseUrl}/api/contents/${encodeURIComponent(path)}`, token);
+      if (existing && existing.type === 'notebook') return ok({ ok: true, created: false, path });
+    } catch { /* 404 — does not exist, proceed to create */ }
+
+    const nb = {
+      nbformat: 4,
+      nbformat_minor: 5,
+      metadata: {
+        kernelspec: { display_name: displayName, language, name: kernelName },
+        language_info: { name: language },
+      },
+      cells: [],
+    };
+
+    await httpJson('PUT', `${baseUrl}/api/contents/${encodeURIComponent(path)}`, token, {
+      type: 'notebook', format: 'json', content: nb,
+    });
+    ok({ ok: true, created: true, path });
+  }
+}

package/src/commands/open/kernel-channels.mjs

@@ -15,7 +15,13 @@ export default class OpenKernelChannels extends Command {
       const sessions = await httpJson('GET', `${baseUrl}/api/sessions`, token);
       let session = sessions.find(s => s.notebook && s.notebook.path === nbPath);
       if (!session) { const name = nbPath.split('/').pop(); session = sessions.find(s => s.notebook && s.notebook.path && s.notebook.path.endsWith('/' + name)); }
-      if (!session) throw new Error('No running session for target notebook');
+      if (!session) {
+        // Auto-create session if kernel_name is provided (or default to python3)
+        const kernelName = input.kernel_name ?? input.kernel ?? 'python3';
+        const name = nbPath.split('/').pop();
+        const body = { path: nbPath, name, type: 'notebook', kernel: { name: kernelName } };
+        session = await httpJson('POST', `${baseUrl}/api/sessions`, token, body);
+      }
       kernelId = session.kernel && session.kernel.id;
       if (!kernelId) throw new Error('Selected session has no kernel id');
     }

package/src/commands/run/cell.mjs

@@ -0,0 +1,64 @@
+import { Command } from '@oclif/core';
+import { getConfig, httpJson, readStdinJson, ok, assertNodeVersion, nowIso } from '../../lib/common.mjs';
+import { ensureDaemon, request } from '../../lib/daemonClient.mjs';
+
+export default class RunCell extends Command {
+  static description = 'Insert a cell, execute it, collect outputs, and update the cell in one step';
+  async run() {
+    assertNodeVersion();
+    const input = await readStdinJson();
+    const path = input.path ?? input.notebook;
+    const channelRef = input.channel_ref ?? input.ref;
+    const code = input.code ?? input.source ?? '';
+    const timeoutS = input.timeout_s ?? 60;
+    const index = input.index;
+    const position = input.position || 'end';
+    const agentMeta = input.metadata || {};
+
+    if (!path) throw new Error('path is required');
+    if (!channelRef) throw new Error('channel_ref is required (call open:kernel-channels first)');
+    if (!code) throw new Error('code is required');
+
+    const { baseUrl, token } = getConfig();
+
+    // 1. Insert cell into notebook
+    const nb = await httpJson('GET', `${baseUrl}/api/contents/${encodeURIComponent(path)}?content=1`, token);
+    if (nb.type !== 'notebook') throw new Error('Path is not a notebook');
+    const nbj = nb.content;
+    const cells = nbj.cells || (nbj.cells = []);
+    const meta = { role: 'jupyter-driver', created_at: nowIso(), auto_save: false, ...agentMeta };
+    const cell = { cell_type: 'code', metadata: { agent: meta }, source: code, outputs: [], execution_count: null };
+    let insertAt;
+    if (typeof index === 'number') insertAt = Math.max(0, Math.min(index, cells.length));
+    else insertAt = position === 'start' ? 0 : cells.length;
+    cells.splice(insertAt, 0, cell);
+    await httpJson('PUT', `${baseUrl}/api/contents/${encodeURIComponent(path)}`, token, { type: 'notebook', format: 'json', content: nbj });
+    const cellId = insertAt;
+
+    // 2. Execute code on kernel channel
+    await ensureDaemon();
+    const execOut = await request('exec', { channel_ref: channelRef, code, allow_stdin: false, stop_on_error: input.stop_on_error !== false });
+    if (execOut.error) throw new Error(execOut.error);
+    const parentMsgId = execOut.parent_msg_id;
+
+    // 3. Collect outputs
+    const collectOut = await request('collect', { channel_ref: channelRef, parent_msg_id: parentMsgId, timeout_s: timeoutS });
+    if (collectOut.error) throw new Error(collectOut.error);
+    const outputs = collectOut.outputs || [];
+    const executionCount = collectOut.execution_count;
+    const status = collectOut.status || 'unknown';
+
+    // 4. Update cell with outputs
+    const nb2 = await httpJson('GET', `${baseUrl}/api/contents/${encodeURIComponent(path)}?content=1`, token);
+    const nbj2 = nb2.content;
+    const cells2 = nbj2.cells || [];
+    if (cellId >= 0 && cellId < cells2.length) {
+      const targetCell = cells2[cellId];
+      targetCell.outputs = outputs;
+      if (executionCount !== undefined && executionCount !== null) targetCell.execution_count = executionCount;
+      await httpJson('PUT', `${baseUrl}/api/contents/${encodeURIComponent(path)}`, token, { type: 'notebook', format: 'json', content: nbj2 });
+    }
+
+    ok({ cell_id: cellId, status, execution_count: executionCount ?? null, outputs });
+  }
+}

package/src/commands/sessions/create.mjs

@@ -0,0 +1,26 @@
+import { Command } from '@oclif/core';
+import { getConfig, httpJson, readStdinJson, ok, assertNodeVersion } from '../../lib/common.mjs';
+
+export default class SessionsCreate extends Command {
+  static description = 'Create a Jupyter session (start a kernel) for a notebook';
+  async run() {
+    assertNodeVersion();
+    const input = await readStdinJson();
+    const path = input.path ?? input.notebook;
+    if (!path) throw new Error('path is required');
+    const kernelName = input.kernel_name ?? input.kernel ?? 'python3';
+    const type = input.type ?? 'notebook';
+    const { baseUrl, token } = getConfig();
+
+    // Check if a session already exists for this notebook
+    const sessions = await httpJson('GET', `${baseUrl}/api/sessions`, token);
+    const existing = sessions.find(s => s.notebook && s.notebook.path === path);
+    if (existing) return ok(existing);
+
+    // Create new session via Jupyter Sessions API
+    const name = path.split('/').pop();
+    const body = { path, name, type, kernel: { name: kernelName } };
+    const session = await httpJson('POST', `${baseUrl}/api/sessions`, token, body);
+    ok(session);
+  }
+}