Use a live Jupyter kernel for stateful, iterative Python execution via hamelnb. Load this skill when the task involves exploration, iteration, or inspecting intermediate results — data science, ML experimentation, API exploration, or building up complex code step-by-step. Uses terminal to run CLI commands against a live Jupyter kernel. No new tools required.
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.
| 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 drewgent 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.
which uv)uv tool install jupyterlabThe 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
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.
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":"python3"}}'
All commands return structured JSON. Always use --compact to save tokens.
uv run "$SCRIPT" servers --compact
uv run "$SCRIPT" notebooks --compact
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
uv run "$SCRIPT" variables --path <notebook.ipynb> list --compact
uv run "$SCRIPT" variables --path <notebook.ipynb> preview --name <varname> --compact
# View current cells
uv run "$SCRIPT" contents --path <notebook.ipynb> --compact
# Insert a new cell
uv 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 cell
uv run "$SCRIPT" edit --path <notebook.ipynb> delete --cell-id <id> --compact
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
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 --path go 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 ename and evalue
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.
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.