Marimo Pair Vscode

marimo is a reactive Python runtime for building reproducible Python programs (marimo notebooks). Cells are connected by the variables they define and reference. Running a cell re-executes dependents in dataflow order. The active runtime holds the kernel namespace, cell state, and dataflow graph. The notebook (.py file) is the artifact the kernel writes from that state while a session is running.

A user interacts with the same runtime via a notebook UI with cells, outputs, and widgets.

WARNING. The active runtime is the source of truth. While the user is pairing on an open notebook, you SHOULD NOT modify the associated .py file directly, and you SHOULD NOT use VS Code's NotebookEdit to change cells. File edits WILL NOT reach the active kernel or user, and the kernel may overwrite them on save; NotebookEdit bypasses the kernel's dataflow graph. Use marimo._code_mode (cm) for all notebook changes. Reading disk is fine, but prefer ctx.cells[...].code for current cell code.

WARNING. Every notebook edit goes through code mode — no exceptions. When the user asks you to change the notebook (add, edit, delete, or run a cell; rename; change a value or a package), you MUST make that change through marimo._code_mode (cm). DO NOT edit the notebook .py file with Edit or Write, and DO NOT use VS Code's notebook-editing tools (NotebookEdit) — those bypass the live kernel, never reach the user's running session, and get clobbered when the kernel saves. Running ad-hoc Python with marimo_executeCode to explore or test is fine; persisting any change to the notebook is only ever done via cm.

Connect to a Notebook

The notebook is already open in VS Code, and the extension manages its kernel. Run Python in that kernel with the marimo_executeCode tool, passing the notebookUri of the notebook the user is working in (VS Code provides the active notebook as context; if several are open or you are unsure which one, ask rather than guessing). The tool runs your code in the scratchpad — see below.

Scratchpad Scope

marimo_executeCode evaluates Python in marimo's scratchpad: a temporary namespace with a shallow copy of the kernel globals. Notebook variables are available by name, but new top-level bindings and rebindings are discarded after each call. In-place mutations to notebook-owned objects can persist because those names still reference live objects.

Each call reports stdout and stderr from the scratchpad, plus console output from notebook cells it causes to run, including reactive descendants.

Ordinary Python

Use ordinary Python in the scratchpad to inspect variables, sample data, test transformations, probe APIs, check imports, and read widget state.

print(df.head())

x = 10
print(x)

Here df comes from notebook globals, while x is a scratchpad-local binding. x exists for this call only and WILL NOT be added to notebook globals.

Persist with cm

Top-level scratchpad assignments and rebindings are temporary. To persist work, including new variables, you MUST submit changes through marimo._code_mode (cm).

marimo._code_mode is a PRIVATE, UNSTABLE agent API (note the leading underscore). It exists for tools like this skill to drive a live kernel from the scratchpad. DO NOT import it from notebook cells, library code, or anything a user would run — methods can change or disappear across marimo versions and kernels. Treat every import marimo._code_mode as cm as scratchpad-only.

At session start, inspect what cm exposes in the active kernel:

import marimo._code_mode as cm

help(cm)

Open a code-mode context to queue notebook changes.

import marimo._code_mode as cm

async with cm.get_context() as ctx:
    cid = ctx.create_cell("x = df.head()")
    ctx.run_cell(cid)

The scratchpad supports top-level async code. Use async with directly; wrapping it in asyncio.run(...) is unnecessary and can conflict with the kernel's event loop.

After this block exits and the new cell runs, x is notebook state. Later scratchpad calls can read x by name. Code later in the same scratchpad call should read ctx.globals["x"], because the scratchpad namespace was copied before the cell ran.

Inside the context, queued mutation methods are synchronous. Call them directly; do not await them. Each call queues an operation for marimo to apply when the context exits normally. If the block raises, the queue is discarded.

On clean exit, marimo applies packages, validates and applies structural cell changes, runs queued cells, then may run dependents. Validation is only structural since queued cell runs can still error. create_cell and edit_cell change notebook structure only. Use run_cell to execute.

create_cell currently defaults to hide_code=True, which collapses the code editor in the UI. Pass hide_code=False if the user wants created cells to be visible without manually expanding them.

Marimo Rules

marimo imposes a small contract on notebook code so it can keep the notebook as a directed acyclic graph (DAG):

• No cycles - cells cannot depend on each other in a cycle.
• No public redefinitions across cells - each name has one owning cell.
• No wildcard imports - import * prevents static analysis of definitions.

These rules keep the kernel, UI, and saved artifact consistent.

When cm submits a cell body, marimo parses its top-level definitions and references. A top-level name enters the graph unless it is private with a leading underscore.

# Public definitions: values, total, i, value, mean
values = np.array([1, 2, 3])
total = 0
for i, value in enumerate(values):
    total += value
mean = total / len(values)
mean

# Public definition: mean
_values = np.array([1, 2, 3])
_total = 0
for _i, _value in enumerate(_values):
    _total += _value
mean = _total / len(_values)
mean

Use private names for intermediates that no other cell should read. Public names define the notebook-level dataflow. If a cm edit violates the contract, marimo rejects the structural change and returns the validation error.