Skip to main content
Iterative Python via live Jupyter kernel (hamelnb).

​
Skill metadata

​
Reference: full SKILL.md

The following is the complete skill definition that Mibyan loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.

​
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

Rule of thumb: If you’d want a Jupyter notebook for the task, use this skill.

​
Prerequisites

  1. uv must be installed (check: which uv)
  2. JupyterLab must be installed: uv tool install jupyterlab
  3. A Jupyter server must be running (see Setup below)

​
Setup

The hamelnb script location:
If not cloned yet:

​
Starting JupyterLab

Check if a server is already running:
If no servers found, start one:
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:
Write a minimal .ipynb JSON file with one empty code cell, then start a kernel session via the Jupyter REST API:

​
Core Workflow

All commands return structured JSON. Always use --compact to save tokens.

​
1. Discover servers and notebooks

​
2. Execute code (primary operation)

State persists across execute calls. Variables, imports, objects all survive. Multi-line code works with $’…’ quoting:

​
3. Inspect live variables

​
4. Edit notebook cells

​
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:

​
Practical Tips from Experience

  1. First execution after server start may timeout — the kernel needs a moment to initialize. If you get a timeout, just retry.
  2. 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.
  3. —compact flag saves significant tokens — always use it. JSON output can be very verbose without it.
  4. For pure REPL use, create a scratch.ipynb and don’t bother with cell editing. Just use execute repeatedly.
  5. Argument order matters — subcommand flags like --path go BEFORE the sub-subcommand. E.g.: variables --path nb.ipynb list not variables list --path nb.ipynb.
  6. 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.
  7. Errors are returned as JSON with traceback — read the ename and evalue fields to understand what went wrong.
  8. Occasional websocket timeouts — some operations may timeout on first try, especially after a kernel restart. Retry once before escalating.
  9. 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.
  10. 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.