Skill v1.0.0
currentAutomated scan94/100name: jupyter-notebook description: "Iterative Python via live Jupyter kernel (hamelnb)." version: 1.0.0 author: Hermes Agent license: MIT platforms: [linux, macos, windows] metadata: hermes: tags: [jupyter, notebook, repl, data-science, exploration, iterative] category: data-science
Jupyter Notebook (hamelnb live kernel)
Gives you a stateful Python REPL via a live Jupyter kernel. Variables persist across executions. Use this instead of execute_code when you need to build up state incrementally, explore APIs, inspect DataFrames, or iterate on complex code.
When to Use This vs Other Tools
| Tool | Use When | |
|---|---|---|
| This skill | Iterative exploration, state across steps, data science, ML, "let me try this and check" | |
execute_code | One-shot scripts needing hermes tool access (web_search, file ops). Stateless. | |
terminal | Shell commands, builds, installs, git, process management |
Rule of thumb: If you'd want a Jupyter notebook for the task, use this skill.
Prerequisites
- uv must be installed (check:
which uv) - JupyterLab must be installed:
uv tool install jupyterlab - A Jupyter server must be running (see Setup below)
Setup
The hamelnb script location:
SCRIPT="$HOME/.agent-skills/hamelnb/skills/jupyter-live-kernel/scripts/jupyter_live_kernel.py"
If not cloned yet:
git clone https://github.com/hamelsmu/hamelnb.git ~/.agent-skills/hamelnb
Starting JupyterLab
Check if a server is already running:
uv run "$SCRIPT" servers
If no servers found, start one:
jupyter-lab --no-browser --port=8888 --notebook-dir=$HOME/notebooks \--IdentityProvider.token='' --ServerApp.password='' > /tmp/jupyter.log 2>&1 &sleep 3
Note: Token/password disabled for local agent access. The server runs headless.
Creating a Notebook for REPL Use
If you just need a REPL (no existing notebook), create a minimal notebook file:
mkdir -p ~/notebooks
Write a minimal .ipynb JSON file with one empty code cell, then start a kernel session via the Jupyter REST API:
curl -s -X POST http://127.0.0.1:8888/api/sessions \-H "Content-Type: application/json" \-d '{"path":"scratch.ipynb","type":"notebook","name":"scratch.ipynb","kernel":{"name":"python"}}'
Core Workflow
All commands return structured JSON. Always use --compact to save tokens.
1. Discover servers and notebooks
uv run "$SCRIPT" servers --compactuv run "$SCRIPT" notebooks --compact
2. Execute code (primary operation)
uv run "$SCRIPT" execute --path <notebook.ipynb> --code '<python code>' --compact
State persists across execute calls. Variables, imports, objects all survive.
Multi-line code works with $'...' quoting:
uv run "$SCRIPT" execute --path scratch.ipynb --code $'import os\nfiles = os.listdir(".")\nprint(f"Found {len(files)} files")' --compact
3. Inspect live variables
uv run "$SCRIPT" variables --path <notebook.ipynb> list --compactuv run "$SCRIPT" variables --path <notebook.ipynb> preview --name <varname> --compact
4. Edit notebook cells
# View current cellsuv run "$SCRIPT" contents --path <notebook.ipynb> --compact# Insert a new celluv run "$SCRIPT" edit --path <notebook.ipynb> insert \--at-index <N> --cell-type code --source '<code>' --compact# Replace cell source (use cell-id from contents output)uv run "$SCRIPT" edit --path <notebook.ipynb> replace-source \--cell-id <id> --source '<new code>' --compact# Delete a celluv run "$SCRIPT" edit --path <notebook.ipynb> delete --cell-id <id> --compact
5. Verification (restart + run all)
Only use when the user asks for a clean verification or you need to confirm the notebook runs top-to-bottom:
uv run "$SCRIPT" restart-run-all --path <notebook.ipynb> --save-outputs --compact
Practical Tips from Experience
- First execution after server start may timeout — the kernel needs a moment
to initialize. If you get a timeout, just retry.
- The kernel Python is JupyterLab's Python — packages must be installed in
that environment. If you need additional packages, install them into the JupyterLab tool environment first.
- --compact flag saves significant tokens — always use it. JSON output can
be very verbose without it.
- For pure REPL use, create a scratch.ipynb and don't bother with cell editing.
Just use execute repeatedly.
- Argument order matters — subcommand flags like
--pathgo BEFORE the
sub-subcommand. E.g.: variables --path nb.ipynb list not variables list --path nb.ipynb.
- If a session doesn't exist yet, you need to start one via the REST API
(see Setup section). The tool can't execute without a live kernel session.
- Errors are returned as JSON with traceback — read the
enameandevalue
fields to understand what went wrong.
- Occasional websocket timeouts — some operations may timeout on first try,
especially after a kernel restart. Retry once before escalating.
- If websocket consistently times out on this host, force zmq transport:
uv run "$SCRIPT" execute --transport zmq .... Symptom: every execute returns "Websocket execution may already have reached the kernel, so auto fallback was skipped". The kernel actually ran fine (REST shows execution_state=idle and execution_count increments) — only the websocket reply channel is broken. zmq transport uses jupyter_client directly and sidesteps the issue.
- When starting a fresh server for REST-only use, add
--ServerApp.disable_check_xsrf=True — otherwise POST /api/sessions returns "'_xsrf' argument missing from POST" and kernel session creation fails.
Timeout Defaults
The script has a 30-second default timeout per execution. For long-running operations, pass --timeout 120. Use generous timeouts (60+) for initial setup or heavy computation.