Live Interactive Pairing with Marimo 0.25.2+ (marimo-pair)
Optimized for Google Antigravity 2.31.2+, Gemini 4 Carbon, and Marimo 0.25.2+.
[!CRITICAL] Operational Cardinal Rule: Active Kernel is the Source of Truth
CRITICAL RUNTIME INVARIANT: When a
.pynotebook is actively open in a runningmarimo editserver, the live Marimo kernel owns the canonical cell graph and in-memory state. NEVER edit the backing.pyfile directly with file-editing tools (edit_file/write_file/ shellsed) while a session is active — doing so causes Disk-Edit Desynchronization, and any unsynced edits will be overwritten by the running server or desync reactive execution! Perform every persistent change throughmarimo._code_modeinside an ephemeral scratchpad, or close the server cleanly before offline refactoring with/marimo-pro.
1. Execution Channels & Script Path Resolution
Choose the appropriate pairing channel for your environment:
- Direct CLI (
marimo pair, Marimo 0.25.2+ built-in): Nativemarimo pair notebook list,marimo pair execute --url ... --session ..., andmarimo pair docs {gotchas|notebook-improvements|rich-representations}. - Bundled POSIX Scripts (Cross-platform Linux / macOS / WSL2 / SSH fallback): Resolve
<SKILL_DIR>to this skill's directory (the directory containing thisSKILL.md):- scripts/discover-servers.sh (
<SKILL_DIR>/scripts/discover-servers.sh) — Probes~/.local/state/marimo/servers/(POSIX / WSL2 + Windows host fallback) and active/api/sessionsendpoints. - scripts/execute-code.sh (
<SKILL_DIR>/scripts/execute-code.sh) — Streams Python scratchpads toPOST /api/kernel/executeover HTTP/SSE, supporting--url,--session,--file,--token, and--token-file.
- scripts/discover-servers.sh (
- Antigravity 2.31.2 MCP Bridge: Launch with
marimo edit notebook.py --headless --no-token --mcp code-mode --port 2718(or--mcp tools) and connect via Streamable HTTP athttp://127.0.0.1:2718/mcp/server.
2. The 5-Step Safe Code-Mode Workflow
Discover Active Server & Stable
session_id: Usemarimo pair notebook listor<SKILL_DIR>/scripts/discover-servers.sh:# Native Marimo 0.25.2 CLI uv run marimo pair notebook list # Or bundled discovery script (includes WSL2 Windows host fallback) bash <SKILL_DIR>/scripts/discover-servers.shAlways bind to the
session_idreturned by discovery (it persists across browser reloads and file renames). If multiple sessions exist for the same notebook, ask the user before selecting one. If no session appears, remind the user to open the notebook URL in a browser tab so the kernel instantiates.Inspect Kernel State (Read-Only Scratchpad): Query
ctx.cells,ctx.graph, andctx.globalsbefore mutating anything:bash <SKILL_DIR>/scripts/execute-code.sh --url http://127.0.0.1:2718 --session "$SESSION_ID" --code-file - <<'PY' import marimo._code_mode as cm async with cm.get_context() as ctx: for cid, cell in ctx.cells.items(): print(cid, cell.name, cell.status, len(cell.errors)) print("Globals:", sorted(k for k in ctx.globals.keys() if not k.startswith("_"))) PYPlan AST-Safe Cell Topology (Zero Redefinitions, Zero Cycles): Respect Single Variable Definition Rule, Cycle Prevention, No Wildcard Imports, and reuse existing empty cells with
ctx.edit_cellbefore creating new cells.Mutate & Explicitly Run Cells (
ctx.run_cell): Cells do not auto-execute oncreate_celloredit_cell. Enqueuectx.run_cell(cid)inside the sameasync with cm.get_context() as ctx:block so Marimo flushes the mutation and executes its reactive DAG on context exit.Verify Execution Status, Errors & Outputs: Run a follow-up read-only scratchpad inspecting
cell.status,cell.errors,cell.output,cell.console_outputs, orawait ctx.screenshot(cell_id=cid)when visually verifying plots and UI widgets.
3. Non-Negotiable Scratchpad & marimo._code_mode Rules
- Scratchpad-Only Import Rule:
import marimo._code_mode as cmruns exclusively inside ephemeral scratchpads sent viaexecute-code.shormarimo pair execute. NEVER placeimport marimo._code_modeinside a persistent cell created withctx.create_cellorctx.edit_cell. - Use
async with cm.get_context() as ctx:— NEVERasyncio.run(...): The scratchpad runner already executes inside a live async event loop. Always enterasync with cm.get_context() as ctx:. - Do NOT
awaitQueuedctxMutation Methods:ctx.create_cell,ctx.edit_cell,ctx.delete_cell,ctx.move_cell,ctx.run_cell,ctx.packages.add, andctx.set_ui_valueare synchronous methods that enqueue operations onto the context transaction and commit atomically on__aexit__. Onlyawait cm.get_context(),await ctx.screenshot(...), andawait ctx.close_screenshot_session()are async coroutines. - Raw Cell Body Rule: Pass only raw, unindented Python statements inside the code string to
ctx.create_cell(code)andctx.edit_cell(cid, code). Do NOT wrap cell strings in@app.cell,def _(...):,return (...), or indentation. - Visual Display Output Rule: In persistent cells whose purpose is visual display (charts, tables, widgets, Markdown), end the raw cell code with a bare, unindented final expression (e.g.,
mo.vstack([chart, summary])), never a silent assignment alone and neverreturn mo.md(...). setupCell Imports Rule: When an import should be shared across cells, usewith app.setup:(or a single dedicated setup/import cell) — never place module-level imports outside@app.cell/app.setupvia disk hacks. Do not overwrite existingsetupdefinitions implicitly; inspectctx.cells["setup"]first if modifying imports.- Visible Code by Default When Authoring (
hide_code=False): In Marimo 0.25.2+,ctx.create_cell(code)defaults tohide_code=True! Passhide_code=Falsewhen creating analysis cells the user expects to read and edit in the notebook UI. - Confirm Destructive / Env Changes: Ask before calling
ctx.delete_cell(drops downstream variables) orctx.packages.add(modifies project environment; preferctx.packages.addover shelluv add/pip).
4. Deep Reference Modules
Load only the specific reference needed for your current pairing step:
- Code-Mode Context API & Safe AST Mutations — Full Marimo 0.25.2+
AsyncCodeModeContextreference (ctx.cells.find/grep,ctx.globals,ctx.graph,ctx.packages,ctx.find_cell_defining_object,StaleCellError,Delete-and-Createrefactoring, rich representations, and screenshots). - Antigravity 2.31.2 MCP Bridge Configuration — Streamable HTTP
mcp_config.jsonsetup on port2718(/mcp/server),--mcp code-modevs--mcp tools,--mcp-allow-remote, all 10 built-in MCP inspection tools (GetMarimoRules,LintNotebook, etc.), andmarimo pair docs. - Session Discovery, Auth & Troubleshooting — Token authentication (
--token-file), WSL2 / SSH remote tunneling,StaleCellErrorrecovery,molab/ multi-session ambiguity, and fixing Disk-Edit Desynchronization.
5. Related Skills & Operational Boundaries
- Do not use this skill when scaffolding or writing new Marimo
.pynotebooks from scratch offline — use/marimo-proinstead, then transition to/marimo-paironce the live kernel session is running. - Pair
/marimo-pairwith/python-profor type-safe Python 3.14+ refactoring, and commit/open PRs strictly via/github-flow-lifecycleafter closing any live server session cleanly.