marimo-pair Skill for Claude: Work Inside Your Running marimo Notebook

Lets Claude run Python in your live marimo notebook, inspect its variables and add or edit cells while you work in the same session.

Installs: 13.1K; on skills.sh
Stars: 432; on GitHub
Files: 7; besides SKILL.md
Updated: Sep 2026; last repo commit

marimo-pair makes Claude a pair programmer inside a running marimo notebook. Claude runs Python in the same kernel you use, reads live variables and cell state, and makes lasting changes through marimo's code-mode API instead of editing the .py file. SKILL.md says the running notebook, not the file, is the source of truth.

It bundles two bash scripts, discover-servers.sh and execute-code.sh, that find your marimo server and send Python to it over HTTP. You need bash, curl and jq, and a notebook open in the browser. Code Claude sends runs with your notebook's access, so use it on a marimo server you started yourself.

Good for

Data scientists who want an agent working in their live marimo session
marimo users who want Claude to build and rerun cells instead of editing the file
Developers testing transformations on real notebook data

Install marimo-pair

Claude Code

Copy this prompt.

Install the marimo-pair skill in Claude Code. Run this command:

/plugin marketplace add marimo-team/marimo-pair
/plugin install marimo-pair@marimo-pair

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires bash, curl, jq.

Needs bash, curl and jq on PATH, and a running marimo notebook started with --no-token so it can be discovered (README). Use a marimo server you started yourself. Pick one route, not both. The plugin also installs a second skill, retro-marimo-pair, which is meant for marimo team members reviewing pairing sessions. The README suggests enabling the marketplace's auto-update. If Claude Code keeps asking to approve the two scripts, the README shows how to allow them in settings.

From the project README. Source.

What's in the skill

When it loads

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.

Sections in SKILL.md

Required first kernel command
Connect to a Notebook
Scratchpad Scope
Ordinary Python
Persist with cm
Marimo Rules
The Notebook's Shape
Writing Notebook Changes
Cell Bodies
Cell Boundaries
Prefer cm-Managed Changes
UI and Widgets
References

Key facts

Author: marimo-team (marimo-team/marimo-pair)
License: Apache-2.0
Installs on skills.sh: 13,124 as of 2026-11-02
GitHub stars: 432 for the whole repo
Last commit to the repo: 2026-09-16
Files in the skill: 8 files including SKILL.md: 2 scripts and 5 reference files
skills.sh audits: Gen Agent Trust Hub pass, Socket pass, Snyk pass
Needs: bash, curl and jq on PATH; a running marimo notebook (started with --no-token for auto-discovery)
Allowed tools in SKILL.md: Bash for the two bundled scripts, and Read

What it includes

Every session starts with `help(cm)` to read the code-mode API.
Claude must see that output before it runs any task-specific code-mode call.
Try: “Open my marimo notebook and add a cell that plots the top 10 rows of df.”
Runs code · Required first command
Lists live marimo servers from marimo's local server registry.
Prints each server's URL after checking its /health endpoint. Only servers started with --no-token register.
Runs code · scripts/discover-servers.sh
Sends Python to the live notebook's scratchpad over HTTP and returns the output.
Takes --url, optionally --file or --session, and code from -c, stdin or a file. It posts to the server's /api/kernel/execute endpoint and warns when the server is not local.
Runs code · scripts/execute-code.sh
Temporary namespace: new variables vanish after each call.
Notebook variables can be read by name. In-place changes to notebook objects can persist.
Runs code · Scratchpad
Create, edit and run cells through marimo._code_mode inside `async with`.
Changes apply when the block exits cleanly; create_cell and edit_cell change structure only, so run_cell is queued separately. marimo calls this API private and unstable.
Runs code · Persist with cm
No cycles, one owner per public name, no wildcard imports.
Invalid structural changes are rejected with a validation error.
Read · Marimo rules
Do not edit the .py file; manage packages through cm; delete deliberately.
Also: reuse existing imports, read a cell before replacing it, and avoid /tmp paths in saved cells.
Write · Durable-edit rules

From the official docs

Permissions

High risk

Claude can run any Python in your live notebook, with the same access you have. Use it on a notebook you trust, keep the server on localhost, and approve each command.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

Claude can run any Python in your notebook
execute-code.sh posts code to the live kernel, so that code runs with your notebook's access. Review each call, and use disposable data when you can. github.com
It can delete cells and change packages
SKILL.md notes that deleting a cell removes the globals it defines, and packages are added or removed through ctx.packages. Ask Claude to check descendants before deleting. github.com
It starts marimo with --no-token
SKILL.md says to start marimo with --no-token so the server registers for discovery, while the README pairs MARIMO_TOKEN with servers that have auth. Keep an unauthenticated server on localhost. github.com
It relies on a private, unstable API
marimo._code_mode is marked private and unstable by the skill, so behavior can change between marimo versions. github.com

Technical details

Talks to	The marimo server URL you pass (localhost by default); the script warns when the host is not local
Sign-in and keys	Optional MARIMO_TOKEN environment variable, sent as a bearer token. --token also works but is visible in process listings.
Scopes	Runs arbitrary Python in your live marimo kernel through the bundled scripts Reads notebook variables, cell code and outputs Creates, edits and deletes cells and can add or remove packages through marimo's API

Questions

What does marimo-pair do?

It lets Claude work inside a running marimo notebook: run Python in the same kernel, inspect live state, and add or edit cells through marimo's code-mode API while you watch and edit in the browser.

How do I install marimo-pair in Claude Code?

Use the install box above. The README gives a plugin route and a skills CLI route. You also need bash, curl and jq, and a marimo notebook running.

Does it need an API key?

No key is named. If your marimo server uses a token, set MARIMO_TOKEN so the scripts can send it.

Is marimo-pair safe to use?

Claude can run any Python in your live notebook kernel, so it runs with your notebook's access. Use it on a notebook you trust, keep the server on localhost, and read what Claude proposes. The Permissions section lists the details.

Does it work in the Claude app or claude.ai?

The README documents Claude Code (plugin) and any agent that supports Agent Skills through the skills CLI. It does not document the Claude app. The skill runs bash scripts and needs curl, jq and a marimo server that those scripts can reach, so this page gives no Claude app install.

Why does Claude not edit the .py file?

SKILL.md says the live runtime is the source of truth. File edits do not reach the running kernel, and the kernel may overwrite them when it saves.

Why does it keep asking me to approve Bash commands?

The skill declares allowed tools, but the README says Claude Code may still prompt for each call. It shows how to add the two script paths to the allow list in .claude/settings.json.

Information

updated Nov 2, 2026

Repository: marimo-team/marimo-pair
Folder: skills/marimo-pair

marimo-team/marimo-pair skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 4

README · github.com
SKILL.md · github.com
execute-code.sh · github.com
discover-servers.sh · github.com