jupyter-live-kernel

Jupyter ライブカーネル（hamelnb）

ライブ Jupyter カーネルを通じて、ステートフルな Python REPL を提供します。変数は実行をまたいで保持されます。状態を段階的に構築したり、API を調べたり、DataFrame を確認したり、複雑なコードを反復して試したりする場合は、execute_code の代わりにこちらを使用してください。

ほかのツールとの使い分け

ツール	使用する場面
このスキル	反復的な探索、ステップ間での状態の保持、データサイエンス、ML、「試して確認したい」場合
execute_code	hermes ツール（web_search、ファイル操作）へのアクセスが必要な単発スクリプト。ステートレスです。
terminal	シェルコマンド、ビルド、インストール、git、プロセス管理

目安： タスクに Jupyter ノートブックを使いたいと思うなら、このスキルを使用してください。

前提条件

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

状態は実行のたびに保持されます。変数、インポート、オブジェクトはすべて維持されます。

$'...' 形式のクォートで複数行のコードを使用できます：

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. サーバー起動後の初回実行はタイムアウトする場合があります — カーネルの初期化には少し時間がかかります。タイムアウトした場合は、再試行してください。

2. カーネルの Python は JupyterLab の Python です — パッケージはその環境にインストールする必要があります。追加のパッケージが必要な場合は、まず JupyterLab のツール環境にインストールしてください。

3. --compact フラグを使うとトークンを大幅に節約できます — 必ず使用してください。使用しない場合、JSON 出力が非常に冗長になることがあります。

4. REPL のみを使う場合は、scratch.ipynb を作成し、セルの編集は気にせず、execute を繰り返し使用してください。

5. 引数の順序は重要です — --path などのサブコマンドフラグは、さらに下位のサブコマンドより前に指定します。例：variables --path nb.ipynb list。variables list --path nb.ipynb ではありません。

6. セッションがまだ存在しない場合は、REST API 経由で開始する必要があります（セットアップのセクションを参照）。ライブカーネルセッションがなければ、このツールは実行できません。

7. エラーはトレースバックを含む JSON で返されます — 何が問題だったかを把握するには、ename フィールドと evalue フィールドを確認してください。

8. WebSocket がタイムアウトすることがあります — 特にカーネルの再起動後は、一部の操作が初回にタイムアウトする場合があります。問題をエスカレーションする前に、1 回再試行してください。

タイムアウトのデフォルト値

スクリプトの実行ごとのデフォルトのタイムアウトは 30 秒です。時間のかかる操作では、--timeout 120 を指定してください。初期セットアップや負荷の高い計算では、余裕のあるタイムアウト（60 秒以上）を使用してください。