---
title: "marimo-pair by marimo-team · skilld"
canonical_url: "https://skilld.dev/gh/marimo-team/marimo-pair"
meta:
description: "Executes Python code in a live marimo notebook kernel, inspects notebook state, and commits durable cell changes through the private `marimo._code_mode` API. Use this… From marimo-team/marimo-pair."
"og:description": "Executes Python code in a live marimo notebook kernel, inspects notebook state, and commits durable cell changes through the private `marimo._code_mode` API. Use this… From marimo-team/marimo-pair."
"og:title": "marimo-pair by marimo-team"
"twitter:description": "Executes Python code in a live marimo notebook kernel, inspects notebook state, and commits durable cell changes through the private `marimo._code_mode` API. Use this… From marimo-team/marimo-pair."
"twitter:title": "marimo-pair by marimo-team"
---
`
[All skills](https://skilld.dev/skills)
[](https://skilld.dev/gh/marimo-team)
# **/marimo-pair**
[@41b64fc](https://github.com/marimo-team/marimo-pair/commit/41b64fc258d5684fc1b6042867e11c37aab548d0 "Your agent reads SKILL.md at commit 41b64fc")
by [marimo](https://skilld.dev/gh/marimo-team)· [marimo-team](https://skilld.dev/gh/marimo-team)/ [marimo-pair](https://skilld.dev/gh/marimo-team/marimo-pair)·420 stars
32
Drive a live marimo notebook as a workspace: run Python in the same kernel the user does, inspect live notebook state, and commit durable notebook changes. Use when the user wants to start a marimo notebook or pair on an active marimo session.
- 8 files
- 53.4 KB
- Updated 2 weeks ago
- [GitHub](https://github.com/marimo-team/marimo-pair/blob/main/skills/marimo-pair/SKILL.md "View SKILL.md on GitHub")
- [1 alert](#third-party-checks "Third-party checks: 1 alert · 5 checks · Risk SAFE")
## SKILL.md
11.6 KB
**≈64** tokens always: the name and description. **≈2.9k** when used: this file. **≈6.1k** more on demand in 5 files.
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.** During a session, you SHOULD NOT modify the associated `.py` file directly. File edits WILL NOT reach the active kernel or user, and the kernel may overwrite them on save. Use `marimo._code_mode` (`cm`) for notebook changes. Reading disk is fine, but prefer `ctx.cells[...].code` for current cell code.
The harness reports the absolute path to this `SKILL.md`. Resolve bundled `scripts/...` and `reference/...` paths from its parent directory, even when the current working directory is a notebook workspace. In command examples, replace `/absolute/path/to/marimo-pair` with that directory.
### Required first kernel command
Start every code-mode session with this dedicated command:
```
bash /absolute/path/to/marimo-pair/scripts/execute-code.sh \
--url http://localhost:2718 \
-c "import marimo._code_mode as cm; help(cm)"
```
Follow this order for each kernel, including read-only tasks:
1. Run the inspection command once.
2. Wait for successful `help(cm)` output.
3. Then use `cm.get_context()` or another `cm` API in a later call.
Do not run task-specific `cm` code before the inspection command succeeds.
### Connect to a Notebook
Use the bundled `execute-code.sh` from the reported skill directory or MCP (`execute_code(...)`) to run Python in a live marimo kernel.
`execute-code.sh` always takes `--url`. If the user provides a notebook URL, run the required inspection against it directly:
```
bash /absolute/path/to/marimo-pair/scripts/execute-code.sh \
--url http://localhost:2718 \
-c "import marimo._code_mode as cm; help(cm)"
```
After that command succeeds, pass task code with `-c CODE`, `-` for stdin, or a file path:
```
bash /absolute/path/to/marimo-pair/scripts/execute-code.sh \
--url http://localhost:2718 - <<'PY'
import marimo._code_mode as cm
async with cm.get_context() as ctx:
cid = ctx.create_cell("x = df.head()")
ctx.run_cell(cid)
PY
```
If the user gives no URL, find or start a notebook. Look for a running server with `bash /absolute/path/to/marimo-pair/scripts/discover-servers.sh`, MCP `list_sessions()`, or local process context, and pass the `url` it reports to `--url`. With one notebook open, the script targets it automatically; with several, pass `--file` with the notebook's file key.
If no server is running and the user wants a notebook, start marimo with `--no-token` (and without `--headless`) so it auto-registers for discovery. The notebook UI must be open for `execute-code` to target it. The right invocation depends on context (project tooling, global install, sandbox mode). If the notebook file contains a PEP 723 `# /// script` header, it MUST be opened with `--sandbox` — otherwise marimo ignores the inline dependencies. See [finding-marimo.md](https://skilld.dev/gh/marimo-team/marimo-pair/marimo-pair/-/reference/finding-marimo.md) for the full decision tree and [execution-context.md](https://skilld.dev/gh/marimo-team/marimo-pair/marimo-pair/-/reference/execution-context.md) for selector resolution, scripts, MCP, and shell quoting.
### Scratchpad Scope
`execute-code` 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.
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. Public names enter the graph. Names that start with `_` are local to their cell and unavailable to other cells. If a `cm` edit violates the contract, marimo rejects the structural change and returns the validation error.
### The Notebook's Shape
A notebook is an ordered collection of cells. `ctx.cells` is the document view and `ctx.graph` is the dataflow view.
```
for cell in ctx.cells:
cell # .id, .code, .name, .config, .status, .errors
ctx.cells["setup"] # by name
ctx.cells[0] # by position
list(ctx.cells.keys()) # all IDs, in notebook order
```
Cell IDs are opaque strings which can be queried from the notebook or captured from `cm` return values:
```
cid = ctx.create_cell("df = pd.read_csv('data.csv')")
print(cid) # e.g. 'Hbol'
```
Alternatively, cells can be assigned and referenced by `name`. The graph can be used to understand its role in the dataflow.
```
for cid, impl in ctx.graph.cells.items():
impl # .defs, .refs (sets of public names)
ctx.graph.descendants(cid) # cells that re-run when this one changes
ctx.graph.ancestors(cid) # cells this one depends on
```
In marimo, deletes are *destructive* so it can be useful to query the descendants prior to deleting to understand it's impact.
### Writing Notebook Changes
The graph contract keeps marimo able to run and save the notebook. Passing those checks alone does not guarantee a useful artifact. Committed cells should still be readable, rerunnable, and editable.
Make durable edits that reuse the notebook's existing names, imports, dependencies, and UI model. Don't be lazy. Avoid one-off workarounds that pass `cm` validation but leave a brittle notebook.
#### Cell Bodies
Submit the code that belongs in the cell.
- **Submit cell contents** - `create_cell` and `edit_cell` take cell contents, not saved-file `@app.cell` wrappers.
- **Read before replacing** - for now, another editor may change a cell between scratchpad calls. Before `edit_cell`, read the current body from `ctx.cells[...]` and submit the full replacement.
- **Reuse notebook imports** - if `np` already exists, use it or edit the owning import cell. DO NOT add `import numpy as _np` just to bypass the graph.
- **Define each public name once** - a public name has one owning cell. Reassigning it in another cell fails with `Multiply-defined names`; edit the owning cell or give the result a new name. See [gotchas.md](https://skilld.dev/gh/marimo-team/marimo-pair/marimo-pair/-/reference/gotchas.md).
- **Run cells deliberately** - `create_cell` and `edit_cell` change structure only. Queue `ctx.run_cell(...)` when the cell should execute.
#### Cell Boundaries
A cell is also a rerun boundary. Put expensive or reusable computation upstream of presentation so UI edits stay cheap. Keep cheap, presentation-specific work with the view when that is easier to read.
Use `mo.vstack` and `mo.hstack` only when the composition is part of the UI. Narrative often reads better in an adjacent markdown cell.
#### Prefer `cm`-Managed Changes
Use `cm` APIs when they exist. Avoid direct file edits, shell package commands, and scratchpad-only state for changes that should persist.
- **Do not edit the `.py` artifact** - DO NOT use `Edit`, `Write`, or `NotebookEdit` on the notebook file during a live session. Use `ctx.edit_cell(...)` even for small changes.
- **Manage packages through `cm`** - use `ctx.packages.add()` or `ctx.packages.remove()` instead of direct `uv` or `pip`; confirm non-obvious dependency changes.
- **Avoid transient paths** - persisted cells should not depend on `/tmp/...` unless the work is intentionally transient.
- **Delete deliberately** - deleting a cell removes globals it defines. Reuse empty cells when convenient and delete cells left empty after edits.
#### UI and Widgets
Inspect the object before changing it. Different UI objects update through different paths.
- **Set `mo.ui.*` through `cm`** - use `ctx.set_ui_value(element, value)` inside `cm.get_context()`.
- **Set anywidget traitlets directly** - synced traitlets are Python attributes, for example `widget.value = 5`.
For designing custom visual or interactive output, see [rich-representations.md](https://skilld.dev/gh/marimo-team/marimo-pair/marimo-pair/-/reference/rich-representations.md).
### References
- [execution-context.md](https://skilld.dev/gh/marimo-team/marimo-pair/marimo-pair/-/reference/execution-context.md) — scripts, MCP, auth, startup, and shell quoting
- [finding-marimo.md](https://skilld.dev/gh/marimo-team/marimo-pair/marimo-pair/-/reference/finding-marimo.md) — choosing the right marimo invocation
- [gotchas.md](https://skilld.dev/gh/marimo-team/marimo-pair/marimo-pair/-/reference/gotchas.md) — name redefinition, cached module proxies, and notebook traps
- [rich-representations.md](https://skilld.dev/gh/marimo-team/marimo-pair/marimo-pair/-/reference/rich-representations.md) — custom widgets and visualizations
- [notebook-improvements.md](https://skilld.dev/gh/marimo-team/marimo-pair/marimo-pair/-/reference/notebook-improvements.md) — improving existing notebooks
Source: [SKILL.md on GitHub](https://github.com/marimo-team/marimo-pair/blob/main/skills/marimo-pair/SKILL.md)
## Third-party checks
1 alert15d5 checks · Risk SAFE
- Gen Agent Trust Hub15d
This skill enables an AI agent to interact with live marimo Python notebooks by discovering local/remote servers and executing Python code within the notebook's kernel. It includes specialized scripts for cross-platform server discovery and communication with the marimo API. The primary security considerations involve the execution of arbitrary Python code and the potential for reading untrusted notebook content.
- Socket15d
No alerts
- Snyk15d
Risk: LOW · No issues
- Runlayer6mo
4/7 files flagged
- ZeroLeaks5mo
Score: 93/100 · 2 sections analyzed
## Provenance
[Signed by skilld at 41b64fc.](https://github.com/marimo-team/marimo-pair/commit/41b64fc258d5684fc1b6042867e11c37aab548d0 "41b64fc258d5684fc1b6042867e11c37aab548d0") This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.
Last checked against GitHub 2 weeks ago.
Activeupdated 2 weeks ago
## Capability
What it can do
Runs commands Reads files
All 3 allowed tools
Bash(bash \*\*/scripts/discover-servers.sh \*)Bash(bash \*\*/scripts/execute-code.sh \*)Read
## Topics
- [Python](https://skilld.dev/skills/tag/python "Python-specific patterns and tooling")
- marimo
- jupyter
- notebook
- reactive
- kernel
- dataflow
- repl
- interactive
## README badge
## What it does
Executes Python code in a live marimo notebook kernel, inspects notebook state, and commits durable cell changes through the private \`marimo.\_code\_mode\` API. Use this skill when pairing on an active marimo session or starting a new notebook to run code reactively alongside the user.
Generated from the current SKILL.md.
## Frequently asked
Can I edit the notebook file directly while a session is running?
No. During an active session, you must use marimo.\_code\_mode (cm) to make changes. Direct file edits will not reach the kernel and the kernel may overwrite them on save.
How do I persist new variables or changes to the notebook?
Use marimo.\_code\_mode (cm) with ctx.create\_cell() or ctx.edit\_cell() to queue changes, then ctx.run\_cell() to execute them. Assignments in the scratchpad are temporary and will not persist.
What are the constraints on notebook cell code?
Marimo enforces no cycles between cells, no redefinition of public names across cells, and no wildcard imports. Use private names (leading underscore) for intermediates that other cells should not reference.
Can I use this skill with a running marimo session I already have open?
Yes. Provide the notebook URL or port, and the skill will connect to the active kernel via the bundled execute-code script.
What happens when code runs in the scratchpad?
Scratchpad code runs in a shallow copy of the kernel's namespace and can read notebook variables. Top-level bindings made in the scratchpad are discarded after the call unless submitted through cm.
Generated from the current SKILL.md. These answers refresh after source changes.
## Related skills
-
-
-
-
-
-