marimo ペアプログラミングプロトコル

このスキルは実行中の marimo ノートブックに完全にアクセスできます。セルコードの読み取り、セルの作成と編集、パッケージのインストール、セルの実行、リアクティブグラフの検査 — すべてプログラマティックに実行できます。バンドルされたスクリプトまたは MCP を通じて作業している間、ユーザーはブラウザで結果をライブで見ることができます。

理念

marimo ノートブックはデータフロー グラフです — セルは計算の基本単位で、定義・参照する変数で接続されています。セルが実行されると、marimo は自動的に下流のセルを再実行します。実行中のノートブックに完全にアクセスできます。

• セルが主なレバーです。 セルを使って作業を分割し、どのように、いつ人間をループに引き込むかを選択してください。すべてのセルが豊かな出力を必要とするわけではありません — 時には対象自体で十分、時には要約が良い場合もあります。プレゼンテーションを意図に合わせてください。
• 最初に意図を理解してください。 明確な場合は行動してください。曖昧な場合は明確にしてください。
• 既存のシグナルに従ってください。 外部ツールに頼る前に、インポート、pyproject.toml、既存のセル、dir(ctx) を確認してください。
• 集中してください。 最初に構築し、後でポーランドしてください — セル名、レイアウト、スタイリングは待つことができます。

前提条件

marimo の起動方法

--no-token で起動されたサーバーのみがローカルサーバーレジストリに登録され、自動検出可能です — トークンなしで起動することにより、検出が簡単になります。サーバーがトークンを持っている場合は、実行スクリプトを呼び出す前に MARIMO_TOKEN 環境変数を設定してください（プロセスリストへのトークンの漏洩を回避）。marimo を起動するための正しい方法はコンテキストによって異なります（プロジェクトツール、グローバルインストール、サンドボックスモード）。完全な決定木については finding-marimo.md を参照してください。

ユーザーが明示的に要求しない限り、--headless を使用しないでください。 これを省略すると、marimo がブラウザを自動的に開くことができ、これが予想されるペアリング体験です。ユーザーがヘッドレスを明示的に要求した場合は、ブラウザで http://localhost:<port> を開くことを提案してください（macOS では open、Linux では xdg-open、Windows では start）。

トラブルシューティング

execute-code.sh からの SyntaxError または ImportError

コードは 実行中の marimo カーネル内で実行されます — execute-code.sh は HTTP 経由で POST し、ローカル Python を呼び出しません。ここでのエラーはローカル Python バージョン、欠落している venv、または uv vs pip が原因ではなく、送信されるコードの問題です。コードを修正してください（複数行の場合は heredoc を使用してください。; で複合ステートメントを 1 行にしようとしないでください）。

ユーザーが Bash コマンドを許可するプロンプトが出続ける

スキルはそのフロントマターで allowed-tools を宣言していますが、Claude Code は各 Bash 呼び出しでもプロンプトが表示される場合があります。これを修正するには、ユーザーはスクリプトへの絶対パスをプロジェクトレベルの .claude/settings.json またはグローバルの ~/.claude/settings.json に追加する必要があります：

{
  "permissions": {
    "allow": [
      "Bash(bash /absolute/path/to/skills/marimo-pair/scripts/discover-servers.sh *)",
      "Bash(bash /absolute/path/to/skills/marimo-pair/scripts/execute-code.sh *)"
    ]
  }
}

サーバーの検出とコードの実行方法

2 つの操作があります: サーバーの検出 と コードの実行。

操作	スクリプト	MCP
サーバーの検出	bash scripts/discover-servers.sh	list_sessions() ツール
コードを実行	bash scripts/execute-code.sh -c "code"	execute_code(code=..., session_id=...) ツール
コードを実行（複数行）	bash scripts/execute-code.sh <<'EOF'	同じ
コードを URL で実行	bash scripts/execute-code.sh --url http://localhost:2718 -c "code"	同じ（url パラム付き）

スクリプトはローカルサーバーレジストリからセッションを自動検出します。複数のサーバーが実行されている場合は --port を使用して特定のサーバーをターゲットにし、同じサーバー上で複数のノートブックが開いている場合は --session を使用して特定のセッションをターゲットにするか、--url を使用して検出をスキップして URL でサーバーに接続します（例: --url http://localhost:2718）。Windows では、レジストリ検出が空の場合は直接 --url が好ましいです — 次のセクションで理由を参照してください。サーバーがトークン認証を有効にしている場合は MARIMO_TOKEN 環境変数を設定して認証してください（--token フラグも機能しますが、トークンをプロセスリストに公開します）。サーバーが --mcp で起動された場合、MCP ツールは代替として利用可能です。

検出が何も見つけないが、ユーザーはサーバーを実行している？

--no-token サーバーのみがレジストリに登録されています。検出が空の場合、サーバーはおそらくトークン認証を持っています — ユーザーにトークンを求め、MARIMO_TOKEN 環境変数として設定してください。

Windows（Git Bash / MSYS2） では、実行中の --no-token サーバーの場合でも検出が空になることがあります。ユーザーが marimo がローカルで到達可能であることを確認した場合は、--url http://127.0.0.1:<port> にフォールバックしてください（ポートを聞いてください）。

サーバーが実行していない？

常に検出してから開始してください。 バックグラウンドタスク「完了」通知はサーバーが停止したことを意味しません — 出力を確認するか、最初に検出を実行してください。

サーバーが見つからない場合は、ユーザーの意図を読んでください — ノートブックが必要な場合は、1 つ起動してください。常に marimo をバックグラウンドタスクとして起動します（Bash ツールで run_in_background を使用）ので、セッション終了時にサーバーが自動的にクリーンアップされ、会話をブロックしません。finding-marimo.md を参照してください。

.py ファイルがまだない場合は、コンテキストに基づいて説明的なファイル名を選択してください（例: exploration.py、analysis.py、dashboard.py）。聞かないでください — 何か妥当なものを選んでください。

シェルエスケープの問題を回避してください。 -c は単純な 1 行に機能しますが、複数行のコードまたはクォート/バッククォート/${} を含むコードの場合は、heredoc またはファイルを使用してください：

# heredoc（単一引用符のデリミタはシェル補間を防止）
bash scripts/execute-code.sh <<'EOF'
import marimo._code_mode as cm

async with cm.get_context() as ctx:
    ctx.create_cell("x = 1")
EOF

# ファイル
bash scripts/execute-code.sh /tmp/code.py

# 特定のポートをターゲットにする（複数のサーバーが実行されている場合は自動選択をスキップ）
bash scripts/execute-code.sh --port 2718 -c "1 + 1"

コードの実行

すべての execute-code 呼び出しはノートブックのカーネル内で実行されます。すべてのセル変数はスコープ内にあります — print(df.head()) はそのまま機能します。呼び出し間で定義したもの（変数、インポート、副作用）は永続しませんが、ノートブックを自由に内観できます: 変数を検査し、コードスニペットをテストし、型と形状を確認します。ノートブックに何か永続化する前に、探索、プロトタイプ、検証に使用してください — その後、セルを作成して状態を永続化し、結果をユーザーに表示します。

ノートブックのデータフロー グラフを変更するには — セルの作成、編集、削除、パッケージのインストール、セルの実行 — marimo._code_mode を使用してください：

import marimo._code_mode as cm

async with cm.get_context() as ctx:
    cid = ctx.create_cell("x = 1")
    ctx.packages.add("pandas")
    ctx.run_cell(cid)

async with を 必ず 使用してください — なしでは操作は何もしません。すべての ctx.* メソッドは 同期的です — コンテキストマネージャーがコンテキストマネージャーの終了時にそれらをフラッシュします。それらを await しないでください。

カーネルはトップレベルの await をサポートしているため、直接 async with を使用してください。async def main(): ... + asyncio.run(main()) でラップしないでください — 不要で間違いやすいです（async with などの複合ステートメントは def name(): と同じ行に続くことができないため、-c 1 行に詰め込むと SyntaxError が生じます）。

セルは自動実行されません。 create_cell と edit_cell は構造的変更のみです — run_cell を使用して実行をキューイングしてください。

code_mode はノートブック変更のための検査済みで安全な API です — すべての構造的変更にこれを使用してください。カーネルから marimo 内部にもアクセスできますが、これは最後の手段として扱い、高い信頼性で探索した後にのみ使用してください。

セルを code_mode で編集し、ファイルシステムでは編集しないでください。直接ファイル書き込みはサイレントに失われます。 code_mode は完全な新しいセル本体が必要なため、Edit/Write で小さな調整に手を出すのは魅力的です。しないでください — --watch なし（デフォルトではオフ）、カーネルはそれらのエディットを見ず、次の保存時に上書きするため、ユーザーには何も見えません。（.py に対する Read は問題ありませんが、コンテンツはライブカーネルより遅れている可能性があります; ctx.cells[target].code を使用してください。）

UI 状態はリアクティブ グラフの外に存在します。 Anywidget traitlets は直接読み取りまたは設定できます（例: slider.value = 5）。mo.ui.* 要素の場合は、code_mode 内で ctx.set_ui_value(element, new_value) を使用してください。

最初のステップ: API を探索する

code_mode API は marimo バージョン間で変わる可能性があります。各セッションの開始時に探索してください — 不確実なものについて詳しく掘り下げてください。

import marimo._code_mode as cm
help(cm)

ガードレール

これをスキップすると UI が壊れます：

• uv add または pip ではなく、ctx.packages.add() でパッケージをインストールしてください。 コード API は カーネルの再起動と依存関係解決を正しく処理します。API が利用不可またはエラーが出た場合にのみ外部 CLI にフォールバックしてください。
• カスタム ウィジェット = anywidget。 ユーザー定義のビジュアル コンポーネントの場合は、HTML/CSS/JS で anywidget を使用してください。単純なフォームとコントロールの場合、合成 mo.ui は問題ありません。rich-representations.md を参照してください。
• セッションが実行されている間、ノートブック .py ファイルを Edit、Write、または NotebookEdit してはいけません。直接書き込みはサイレントに破棄され、ユーザーに決して到達しません。 marimo は --watch でのみファイルを監視し、デフォルトではオフです。これなしでは、カーネルはファイル編集を認識しません — 次の保存時に、カーネルは独自の状態を書き込み、あなたのものを上書きします。ユーザーには何も変わったように見えず、バグは見えません。常に ctx.edit_cell(target, code=...) を使用して完全な新しいセル本体を使用してください — 1 文字の変更でも。（Read は許可されていますが、ディスク コンテンツはライブカーネルより遅れている可能性があります; 現在の真実については ctx.cells[target].code が好ましいです。）
• セルコードに一時ファイル deps がないようにしてください。 pathlib.Path("/tmp/...") はセル コードのバグです。
• 空のセルを避けてください。 新しいセルを作成するのではなく、edit_cell を既存の空のセルに使用する方が良いです。編集後に空になるセルをクリーンアップしてください。
• セル名について心配しないでください。 ほとんどのセルは明示的な名前を必要としません — notebook-improvements.md を参照してください。

ウィジェットとリアクティビティ

Anywidget 状態（traitlets）は marimo のリアクティブ グラフの外に存在します。ウィジェット特性をグラフにフックするには、ウィジェットごとに 1 つの戦略を選択してください — 決して混ぜないでください：

• mo.state + .observe() — 特定の特性をブリッジするかを選択します。デフォルトの選択肢。
• mo.ui.anywidget() — すべての同期特性を 1 つのリアクティブ .value にラップします。便利ですが粗いです。

どちらかを配線する前に rich-representations.md を読んでください。

心に留めておく

• ユーザーも編集しています。 ノートブックは呼び出し間で変更される可能性があります — 前回見てからしばらく経っている場合はノートブック状態を再検査してください。
• 削除は破壊的です。 セルを削除すると、そのセルの変数がカーネル メモリから削除されます — 復元はセルを再作成し、それとその依存物を再実行することを意味します。意図が曖昧と思われる場合は、最初に聞いてください。
• パッケージのインストールはプロジェクトを変更します。 ctx.packages.add() は実際の依存関係を追加します — コンテキストから明らかでない場合は確認してください。

参考資料

• finding-marimo.md — 正しい marimo を見つけて起動する方法
• gotchas.md — キャッシュされたモジュール プロキシおよび他のトラップ
• rich-representations.md — カスタム ウィジェットと可視化
• notebook-improvements.md — 既存のノートブックの改善