SkillFoxx

marimo-pair skill

An agent shares a live marimo notebook session with you, running code in the same kernel and editing cells as you watch

  • 432 ★ on the repository
  • Last commit
  • Apache-2.0
SkillOfficial

Broad access

Why this level

  • The agent runs arbitrary Python in your live kernel, which holds loaded data, environment keys and open connections
  • The skill scripts call the marimo server over HTTP on the machine and run `bash`, so Claude Code approvals arrive on every call
All reasons and checks

marimo-team/marimo-pairAuthor:marimo-team

Install

In your terminal, with SkillFoxx CLI

npx skillfoxx add skills/marimo-pair

Detects the agents on your machine, shows the access level and pins the version.

Other ways to install

Access and checks

How we review

Broad accessThe tool can change data, run commands or handle secrets.

  • The agent runs arbitrary Python in your live kernel, which holds loaded data, environment keys and open connections
  • The skill scripts call the marimo server over HTTP on the machine and run `bash`, so Claude Code approvals arrive on every call

This is third-party code. Review the repository files before installing.

What it does

marimo-pair is a skill that attaches an agent to an already running reactive marimo notebook. The agent executes Python in the same kernel you use, reads variables and cell state, and changes the notebook through the private `marimo._code_mode` interface. New cells and results show up in the normal notebook window right away, with no restart. Two shell scripts in the skill folder handle the connection. `discover-servers.sh` finds running marimo servers and `execute-code.sh` sends code to the chosen one. Every session starts with one mandatory command, `help(cm)`, so the agent learns the current methods, because the interface is marked unstable. The agent must not edit the notebook's `.py` file directly: the running kernel is the source of truth and may overwrite the file on save. Code sent through `execute-code.sh` runs in a scratch namespace. New variables there live until the call ends, and only cells created through `cm` reach the notebook. The skill's second command, `/retro-marimo-pair`, collects feedback on the finished session for the authors.

Who it is for. Analysts and researchers who work in marimo notebooks and want an agent beside them in the same live state, with no code and output passed back and forth.

Good fit when

  • An agent inspects an unfamiliar dataframe in your own kernel and shows the columns and types it holds
  • An analysis goes through several iterations and new cells with charts appear in the notebook as you talk
  • You try a data transformation on live variables before any edit lands in the notebook
  • A notebook with widgets reaches a state where the agent reads slider values and checks the result
  • A notebook with a PEP 723 header runs with `--sandbox`, and the agent works with its inline dependencies

Not a fit when

  • Notebooks live in Jupyter: the skill works with marimo only
  • The kernel holds expensive state that cannot be lost, and you would rather test changes on a copy
  • You need a batch run with no notebook window open: `execute-code.sh` targets a session with an open interface
  • The machine has no `bash`, `curl` and `jq`, and you cannot install them

Example request

Attach to my open marimo notebook, look at the sales dataframe and add a cell with a monthly revenue chart

Limitations

The skill expects a running marimo notebook. For automatic discovery the server starts with `--no-token` and without `--headless`; a server with a token needs the `MARIMO_TOKEN` variable. On Windows you need Git Bash or WSL with the same `bash`, `curl` and `jq`. The authors call the `marimo._code_mode` interface private and unstable: methods can change between marimo versions, which is why the skill makes `help(cm)` the first call. The agent runs arbitrary Python in your kernel, and Claude Code may ask for approval on every `bash` call. If a notebook carries a PEP 723 header, open it with `--sandbox` or marimo skips the inline dependencies.

How to disable. Delete the `marimo-pair` skill from your agent's skills folder or disable the plugin in Claude Code through the `/plugin` menu. If you added `Bash(bash ...)` rules to `settings.json` to silence prompts, remove them separately. Stop the marimo notebook the usual way.

FAQ

How do I install marimo-pair in Claude Code?

Run `/plugin marketplace add marimo-team/marimo-pair`, then `/plugin install marimo-pair@marimo-pair`. Other agents can use the general `npx skills add marimo-team/marimo-pair`, and without `npx` the `uvx deno -A npm:skills add marimo-team/marimo-pair` form works.

What must be running before I start?

A marimo notebook. For automatic server discovery it starts with `--no-token`; a server with authentication takes the token in the `MARIMO_TOKEN` variable. The notebook window has to be open because the script targets a session with an interface.

Why does Claude Code ask for approval on every bash call?

The skill declares its own permissions, yet Claude Code may still prompt. Copy the absolute paths of `discover-servers.sh` and `execute-code.sh` from the installed skill and add them as `Bash(bash /path/execute-code.sh *)` rules to `.claude/settings.json` or `~/.claude/settings.json`.

Can the agent edit the notebook file directly?

Not while a session runs. The live kernel is the source of truth and may overwrite the file on save. Changes go through `marimo._code_mode`; reading the file from disk is fine.

How do I send feedback after a session?

Run `/retro-marimo-pair` once the session ends: it collects feedback on where the skill can improve. The repository's issue tracker takes the same feedback.

Discussion

No questions or reviews yet.

Skills

Skills from the marimo team: the right notebook format, migration from Jupyter and Streamlit, scheduled runs, WASM

SkillExtended access177

A Cypher graph database in one binary for agents: CLI, embedded engine, MCP server and a skill for Claude Code, Cursor and Codex.

CLIExtended access223

MCP server that connects Claude Code and Codex to an open R or Python session in RStudio and Positron, where your data lives

MCP serverBroad access372

A team of data analysis agents that takes a dataset from raw rows to a trained model and checks its own conclusions.

CLIBroad access122

A knowledge base from your documents where people and AI agents annotate together, with an MCP server and skills for Claude Code

MCP serverExtended access93

Monte Carlo plugin for Claude Code and Cursor: table checks before queries, data incident triage and monitor creation.

PluginExtended access93

README in short

The repository page lists environment requirements and two install routes: a generic one for any agent and a Claude Code plugin with auto-update. The FAQ covers repeated `bash` prompts, and the closing section asks for contributions and links the issue tracker.

README badge

Original SKILL.md

---
name: marimo-pair
description: >-
  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.
allowed-tools: Bash(bash **/scripts/discover-servers.sh *), Bash(bash **/scripts/execute-code.sh *), Read
---

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
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

Report a problem