Jupyter Notebook
Notebooks live on a Jupyter Server and are shown in the Jupyter Notebook side panel, where the user can edit and run cells too. Use this plugin's tools for .ipynb files: never edit .ipynb JSON with file tools, and do not start jupyter yourself in a shell.
1. Get a server
- Call
list_servers. It shows connected servers and Jupyter servers running on this machine.
- If the user named a server or pasted a URL (with or without
?token=…), call connect_server with it. A server listed as running on this machine needs no token.
- Otherwise, if a running server's root contains the notebooks you need, offer to use it; if there is none or the user wants a private one, call
start_server. It needs a Python with jupyter-server and ipykernel. On jupyter_not_installed, show the user the message and ask whether to install them into the project environment (or retry with useUv: true if they use uv); the panel also lists what is missing and can send you a setup request. Do not install packages without asking — a message from the panel starting Set up Jupyter for the Jupyter Notebook panel is such a request (see section 6).
Paths are relative to the server root. For a server from start_server that is the workspace.
2. Open and read
open_notebook opens a notebook in the panel and returns its cells; pass create: true for a new one. list_notebooks browses folders.
- Cells are listed as
[index] type id=<id> rev=<revision>. Always address cells by id; indexes shift.
- Call
read_notebook before editing if anything may have changed — the user edits in the panel too. Use cellIds to read specific cells in full and includeImages: true to look at plots.
3. Edit
edit_notebook takes a list of operations applied together:
insert with source, type (code / markdown / raw) and after / before a cell id or index (default: append),
update with the cell's complete new source (add expectedRevision from your last read when the user may be editing the same cell),
move, delete, set_type, clear_outputs.
Keep cells focused: imports and setup first, one step per cell, markdown cells to explain the analysis. Prefer editing an existing cell to adding near-duplicates. On revision_conflict, read the notebook again and redo the edit on the current content; never overwrite the user's work blindly.
4. Run
execute_cells with cellIds (in order) or all: true. It starts the kernel if needed, waits (default 300 s) and returns each cell's outputs, with plots attached as images. After an error, later cells in the batch are skipped — fix the failing cell and run again.
- If it returns "still running", the cells keep running in the background. Tell the user, check later with
read_notebook, or stop with interrupt_kernel.
restart_kernel clears all state (runAll: true reruns everything). Use it when imports or state are stale, after asking if long computations would be lost.
list_kernelspecs / set_kernel switch to another kernel (language or environment).
- Missing packages: report the
ModuleNotFoundError and ask before installing (for example %pip install <package> in a cell installs into the kernel's environment).
5. Report
Summarise results in a few sentences in the chat and refer to cells by their index; the outputs are visible in the panel, so do not paste whole tables or tracebacks. When the panel says the user ran into an error in a cell, read that cell, fix it with edit_notebook, and run it again.
Saving is automatic. On save_conflict the file changed on the server (for example in JupyterLab): ask the user whether to keep this version (save_notebook with overwrite: true) or load theirs (open_notebook with reload: true).
6. Setting up Jupyter
When the user asks you to set up Jupyter — usually with the panel's message, which names the project's Python, whether uv manages it and which packages are missing — follow its steps:
- Install
jupyter-server and ipykernel into the workspace's environment with the command the message gives (uv add --dev jupyter-server ipykernel in a uv project, uv pip install --python .venv … for a uv environment without pyproject.toml, otherwise <venv python> -m pip install …). Never install into the system Python; if the workspace has no virtual environment, create one first (uv venv, or python3 -m venv .venv).
- Confirm with
<python> -c "import jupyter_server, ipykernel".
- Call
start_server; the panel switches to the notebook list once the server is up.
1---2name: jupyter-notebook3description: Work with Jupyter notebooks (.ipynb) in the Jupyter Notebook side panel — create, read, edit and run cells on a Jupyter Server, together with the user. Use when the user wants a notebook, asks to analyse data or prototype in Jupyter, mentions a .ipynb file or a running JupyterLab / Jupyter Server, or when the panel sends a message about a notebook cell.4metadata:5 source: https://skillmd.com/skills/zai-org/jupyter-notebook6---78# Jupyter Notebook910Notebooks live on a Jupyter Server and are shown in the Jupyter Notebook side panel, where the user can edit and run cells too. Use this plugin's tools for .ipynb files: never edit .ipynb JSON with file tools, and do not start `jupyter` yourself in a shell.1112## 1. Get a server13141. Call `list_servers`. It shows connected servers and Jupyter servers running on this machine.152. If the user named a server or pasted a URL (with or without `?token=…`), call `connect_server` with it. A server listed as running on this machine needs no token.163. Otherwise, if a running server's root contains the notebooks you need, offer to use it; if there is none or the user wants a private one, call `start_server`. It needs a Python with `jupyter-server` and `ipykernel`. On `jupyter_not_installed`, show the user the message and ask whether to install them into the project environment (or retry with `useUv: true` if they use uv); the panel also lists what is missing and can send you a setup request. Do not install packages without asking — a message from the panel starting *Set up Jupyter for the Jupyter Notebook panel* is such a request (see section 6).1718Paths are relative to the server root. For a server from `start_server` that is the workspace.1920## 2. Open and read2122- `open_notebook` opens a notebook in the panel and returns its cells; pass `create: true` for a new one. `list_notebooks` browses folders.23- Cells are listed as `[index] type id=<id> rev=<revision>`. Always address cells by `id`; indexes shift.24- Call `read_notebook` before editing if anything may have changed — the user edits in the panel too. Use `cellIds` to read specific cells in full and `includeImages: true` to look at plots.2526## 3. Edit2728`edit_notebook` takes a list of operations applied together:2930- `insert` with `source`, `type` (code / markdown / raw) and `after` / `before` a cell id or `index` (default: append),31- `update` with the cell's complete new `source` (add `expectedRevision` from your last read when the user may be editing the same cell),32- `move`, `delete`, `set_type`, `clear_outputs`.3334Keep cells focused: imports and setup first, one step per cell, markdown cells to explain the analysis. Prefer editing an existing cell to adding near-duplicates. On `revision_conflict`, read the notebook again and redo the edit on the current content; never overwrite the user's work blindly.3536## 4. Run3738- `execute_cells` with `cellIds` (in order) or `all: true`. It starts the kernel if needed, waits (default 300 s) and returns each cell's outputs, with plots attached as images. After an error, later cells in the batch are skipped — fix the failing cell and run again.39- If it returns "still running", the cells keep running in the background. Tell the user, check later with `read_notebook`, or stop with `interrupt_kernel`.40- `restart_kernel` clears all state (`runAll: true` reruns everything). Use it when imports or state are stale, after asking if long computations would be lost.41- `list_kernelspecs` / `set_kernel` switch to another kernel (language or environment).42- Missing packages: report the `ModuleNotFoundError` and ask before installing (for example `%pip install <package>` in a cell installs into the kernel's environment).4344## 5. Report4546Summarise results in a few sentences in the chat and refer to cells by their index; the outputs are visible in the panel, so do not paste whole tables or tracebacks. When the panel says the user ran into an error in a cell, read that cell, fix it with `edit_notebook`, and run it again.4748Saving is automatic. On `save_conflict` the file changed on the server (for example in JupyterLab): ask the user whether to keep this version (`save_notebook` with `overwrite: true`) or load theirs (`open_notebook` with `reload: true`).4950## 6. Setting up Jupyter5152When the user asks you to set up Jupyter — usually with the panel's message, which names the project's Python, whether uv manages it and which packages are missing — follow its steps:5354- Install `jupyter-server` and `ipykernel` into the workspace's environment with the command the message gives (`uv add --dev jupyter-server ipykernel` in a uv project, `uv pip install --python .venv …` for a uv environment without `pyproject.toml`, otherwise `<venv python> -m pip install …`). Never install into the system Python; if the workspace has no virtual environment, create one first (`uv venv`, or `python3 -m venv .venv`).55- Confirm with `<python> -c "import jupyter_server, ipykernel"`.56- Call `start_server`; the panel switches to the notebook list once the server is up.