marimo-pair: giving coding agents a live marimo notebook session

The gap marimo-pair fills between an agent and a running notebook

Most agent tooling treats a Python notebook as a file. The agent reads the source, edits cells, and the user re-runs things. That model breaks with marimo, because a marimo notebook is a reactive dataflow graph: cells declare their dependencies and marimo decides what to re-execute. Editing the file on disk tells you nothing about what is currently in memory, and re-running the whole notebook to see one change is slow.

marimo-pair takes the other position. Its README describes the project as "reactive Python notebooks as environments for agents." The unit of work is a notebook session that is already running, with variables already bound. The agent connects to that session and executes code in it. The audience is narrow and specific: people who keep a marimo server up while working and want an agent to inspect or manipulate live state rather than reason about a static file.

How marimo-pair talks to a notebook: discovery, then code execution

The repository is small. The top level holds .agents/, .claude-plugin/, .codex-plugin/, .github/, LICENSE, README.md, renovate.json and skills/. The primary language is Shell, and the work happens in scripts under the skill directory. Two of them are named in the README: discover-servers.sh and execute-code.sh. That naming is the architecture in miniature. One script finds candidate marimo servers, the other runs code against one.

Discovery has two modes. A notebook started with --no-token can be found automatically. A server that requires auth is addressed through the MARIMO_TOKEN environment variable. Execution goes through the marimo server's HTTP surface, which is why curl and jq are prerequisites: curl issues the request, jq parses the response. Nothing here reimplements marimo. marimo-pair is a client that assumes a marimo server is already listening.

The consequence is that the skill has no state of its own. It does not hold a kernel, buffer cells, or track a session across invocations. Whatever the agent sees is whatever the live notebook currently holds.

Installing marimo-pair as an Agent Skill or a Claude Code plugin

There are two install paths, and they target different hosts. The first uses the Agent Skills open standard, which the README says works with any agent that supports it. From a shell with npx available:

npx skills add marimo-team/marimo-pair

To move an existing install forward, the README gives the upgrade form:

npx skills upgrade marimo-team/marimo-pair

If npx is not present but uv is, the README offers an alternative that runs the same npm package through Deno:

uvx deno -A npm:skills add marimo-team/marimo-pair

The second path is Claude Code's plugin marketplace, which is a different mechanism entirely. Inside Claude Code, you add the marketplace and then install the plugin:

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

The README recommends opting in to auto-updates through /plugin, then Marketplaces, then marimo-pair, then Enable auto-update, so the installed skill tracks new versions. Note that this is a slash-command flow, not a shell command; running it in bash will not work.

Whichever path you take, the prerequisites are the same and they are not optional: a running marimo notebook, plus bash, curl and jq on PATH. The README addresses Windows explicitly, saying to run from Git Bash, or from WSL with those tools installed in the distro, and that the scripts also find notebooks running on the Windows host. That last detail matters if you develop on Windows and run marimo there.

Silencing Claude Code's Bash prompts for marimo-pair

The README's own FAQ opens with the most common friction point: repeated prompts to allow Bash commands. The skill declares its own allowed-tools, but the README states that Claude Code may still ask you to approve each Bash call. The documented fix is to copy the absolute paths to the scripts from the installed skill and allow-list them in .claude/settings.json at project level, or ~/.claude/settings.json globally:

{
  "permissions": {
    "allow": [
      "Bash(bash /path/to/skills/marimo-pair/scripts/discover-servers.sh *)",
      "Bash(bash /path/to/skills/marimo-pair/scripts/execute-code.sh *)"
    ]
  }
}

The paths in that snippet are placeholders from the README, not literal paths; you substitute the location where the skill was installed. The trailing wildcard is what covers the arguments the agent passes to each script.

This is worth pausing on. The permission model here is path-based, so an allow-list entry that points at the wrong directory silently does nothing and you keep getting prompts. It also means the trust boundary is the script path, not the code the agent chooses to execute. Allow-listing execute-code.sh grants the agent the ability to run arbitrary Python in your notebook process, with whatever credentials and data that process already holds. The README does not discuss sandboxing, and there is no indication that the scripts constrain what gets executed.

Where marimo-pair is the wrong tool

The clearest failure mode is the absence of a server. marimo-pair has no fallback: no running notebook means discover-servers.sh has nothing to report and the agent is stuck. If your workflow is to open a notebook occasionally, edit a few cells and close it, you are paying an install and a permission configuration for a bridge you will not cross.

The dependency on bash, curl and jq is a real constraint rather than a formality. On a locked-down machine where you cannot install jq, the execute-code path does not work, and the WSL guidance only helps if you can install the tools inside the distro.

There is also a category error worth naming. marimo-pair does not help an agent write or refactor notebook source. It helps an agent act inside a session that already exists. If your goal is to have an agent produce a notebook file you then commit, the skill is beside the point, and you would be better served by an agent that edits Python directly.

Finally, the versioning is early. The most recent release listed is v0.0.19 from 2026-08-26, following v0.0.18 and v0.0.17 in the preceding weeks. A 0.0.x line with frequent releases is a signal that interfaces may still move. The README does not document a rollback procedure if an upgrade breaks your setup, and it does not describe version pinning for the skill.

marimo-pair versus an agent that edits notebook files

The obvious alternative is the default behaviour of most coding agents: read the .py notebook file, edit it, let the user re-run. That approach has real advantages. It works with no server, no token, no jq, and the diff is reviewable in version control. For a notebook that is mostly a script with a few visualizations, file editing is simpler and safer.

The difference is state. A marimo notebook holds live objects: DataFrames, model handles, database connections, partially computed results. An agent editing the file has to reconstruct that state to reason about it, and any conclusion it draws is about the source, not about what is running. marimo-pair inverts this. The agent queries the live session, so what it sees is what the notebook actually holds right now. That is the entire value proposition, and it is also the entire risk, because the agent's actions land in the same process that holds your data.

Choose based on whether the state matters. If the answer to "what is in this variable?" is already in the file, you do not need marimo-pair.

Licence, maintenance and what an upgrade costs you

marimo-pair is licensed under Apache-2.0. That is a permissive licence with an explicit patent grant, and it permits commercial use and modification. This is not legal advice; if you redistribute the skill or embed it in a product, read the LICENSE file in the repository and the NOTICE requirements that Apache-2.0 carries.

The repository is not archived, and the last push was on 2026-08-27. Releases have been frequent and recent, with v0.0.19 on 2026-08-26. renovate.json at the top level indicates automated dependency updates are configured, which is consistent with a project that intends to keep its toolchain current. The README also points contributors at a /retro-marimo-pair command to run after a session and share feedback.

Upgrade cost is mostly host-side. The Claude Code path recommends enabling auto-update through the plugin marketplace, which means the skill changes under you without a version pin. The Agent Skills path gives you an explicit upgrade command, so you control when it happens. If you allow-listed absolute script paths in .claude/settings.json, an upgrade that relocates the scripts would invalidate those entries and bring the prompts back. That is the concrete thing to check after any upgrade.

Editorial conclusion

marimo-pair is for people who already run marimo notebooks and want an agent to work against the live kernel instead of a copy of the file. It is the wrong tool if you do not have a marimo server running, if you cannot install bash, curl and jq, or if you want the agent to edit notebook source offline. Before adopting it, verify three things: that the scripts resolve your server (a --no-token notebook or a MARIMO_TOKEN in the environment), that your agent host actually reads the skill's allowed-tools declaration, and that you are comfortable allow-listing the absolute paths to discover-servers.sh and execute-code.sh in .claude/settings.json. If any of those three fails, the skill degrades into repeated permission prompts and the value disappears.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. marimo-team/marimo-pair on GitHub
4. README
5. Releases