Jupyter Notebook

動いている Jupyter カーネルで Python を少しずつ試します（hamelnb）。

skill の情報

参考: SKILL.md 全文

Jupyter Notebook (hamelnb live kernel)

動いている Jupyter カーネルを通じて、状態が残る Python の REPL を使えるようにします。変数は 実行をまたいで残ります。状態を少しずつ積み上げたいとき、API を触って試したいとき、DataFrame を 覗きたいとき、込み入ったコードを何度も直したいときは、execute_code ではなくこちらを使います。

他のツールとの使い分け

目安: その作業に Jupyter ノートブックが欲しくなるなら、この skill を使ってください。

前提条件

1. uv が入っていること（確認: which uv）
2. JupyterLab が入っていること: uv tool install jupyterlab
3. Jupyter サーバーが動いていること（下の「セットアップ」を参照）

セットアップ

hamelnb のスクリプトの場所:

SCRIPT="$HOME/.agent-skills/hamelnb/skills/jupyter-live-kernel/scripts/jupyter_live_kernel.py"

まだクローンしていない場合:

git clone https://github.com/hamelsmu/hamelnb.git ~/.agent-skills/hamelnb

JupyterLab を起動する

すでにサーバーが動いていないか確かめます:

uv run "$SCRIPT" servers

見つからなければ、起動します:

jupyter-lab --no-browser --port=8888 --notebook-dir=$HOME/notebooks \
  --IdentityProvider.token='' --ServerApp.password='' > /tmp/jupyter.log 2>&1 &
sleep 3

補足: ローカルのエージェントから触れるように、トークンとパスワードを無効にしています。 サーバーは画面を持たずに動きます。

REPL 用のノートブックを作る

REPL だけあればよく、既存のノートブックがない場合は、最小限のノートブックファイルを作ります:

mkdir -p ~/notebooks

空のコードセルを 1 つだけ持つ最小の .ipynb を JSON で書き、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"}}'

基本の流れ

どのコマンドも構造化された JSON を返します。トークンを節約するため、必ず --compact を 付けてください。

1. サーバーとノートブックを探す

uv run "$SCRIPT" servers --compact
uv run "$SCRIPT" notebooks --compact

2. コードを実行する（主に使う操作）

uv run "$SCRIPT" execute --path <notebook.ipynb> --code '<python code>' --compact

execute をまたいで状態は残ります。変数も import もオブジェクトも、すべて生き続けます。

複数行のコードは $'...' の引用で書けます:

uv run "$SCRIPT" execute --path scratch.ipynb --code $'import os\nfiles = os.listdir(".")\nprint(f"Found {len(files)} files")' --compact

3. 生きている変数を覗く

uv run "$SCRIPT" variables --path <notebook.ipynb> list --compact
uv run "$SCRIPT" variables --path <notebook.ipynb> preview --name <varname> --compact

4. ノートブックのセルを編集する

# 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

5. 検証（再起動して全実行）

ユーザーがまっさらな状態での検証を求めたときや、ノートブックが上から下まで通ることを 確かめたいときだけ使ってください:

uv run "$SCRIPT" restart-run-all --path <notebook.ipynb> --save-outputs --compact

実際に使って分かったこと

1. サーバー起動後の最初の実行はタイムアウトすることがあります — カーネルの準備に少し

かかります。タイムアウトしたら、もう一度実行するだけで大丈夫です。

1. カーネルの Python は JupyterLab の Python です — パッケージはその環境に入っている

必要があります。追加のパッケージが要るなら、先に JupyterLab のツール環境へ入れてください。

1. --compact を付けるとトークンがかなり減ります — 必ず付けてください。付けないと JSON の

出力がとても長くなります。

1. 純粋に REPL として使うなら、scratch.ipynb を作って、セルの編集は気にせず execute を

繰り返すだけにします。

1. 引数の順番が効きます — --path のようなサブコマンドのフラグは、その下のサブコマンドの

前に置きます。たとえば variables --path nb.ipynb list であって、 variables list --path nb.ipynb ではありません。

1. セッションがまだ無い場合は、REST API から開始する必要があります（「セットアップ」を

参照）。生きたカーネルのセッションがないと、このツールは実行できません。

1. エラーは JSON で返ります。トレースバック付きなので、ename と evalue を読んで何が

起きたか把握してください。

1. websocket がときどきタイムアウトします — 一部の操作は、特にカーネルの再起動直後に、

1 回目でタイムアウトすることがあります。問題として上げる前に一度やり直してください。

1. そのホストで websocket が毎回タイムアウトするなら、zmq の通信に切り替えます:

uv run "$SCRIPT" execute --transport zmq ...。症状は、execute のたびに 「Websocket execution may already have reached the kernel, so auto fallback was skipped」が返ることです。カーネル自体はきちんと動いています（REST では execution_state=idle が返り、execution_count も増えます）。壊れているのは websocket の 返信経路だけです。zmq の通信は jupyter_client を直接使うので、この問題を回避できます。

1. REST だけで使うサーバーを新しく立てるときは、--ServerApp.disable_check_xsrf=True を

足してください。付けないと POST /api/sessions が "'_xsrf' argument missing from POST" を返し、カーネルのセッションを作れません。

タイムアウトの既定値

このスクリプトは 1 回の実行につき 30 秒を既定のタイムアウトにしています。長くかかる処理には --timeout 120 を渡してください。最初のセットアップや重い計算では、60 秒以上のゆとりのある 値にします。