Show HN: Marimo pair – Reactive Python notebooks as environments for agents
TL;DR Highlight
This is an open-source tool that allows you to directly drop-in an AI agent into a running Marimo notebook session, using the notebook's reactive execution state itself as the agent's working memory.
Who Should Read
Python developers who want to interactively integrate AI agents like Claude Code into their data science or ML experiments with Marimo/Jupyter notebooks. It's particularly suitable for those who want agents to collaborate within a 'live' session rather than simply submitting temporary scripts.
Core Mechanics
- marimo-pair is a tool that directly attaches an agent to a running Marimo notebook session, allowing the agent to read and execute notebook cells and manipulate its state.
- Marimo uses a reactive execution model with Python notebooks, unlike traditional Jupyter. When a variable in one cell changes, other dependent cells are automatically re-executed. This structure allows the notebook runtime itself to serve as the agent's persistent memory.
- Installation is done with a single line: `npx skills add marimo-team/marimo-pair`, and it supports the Agent Skills open standard, working with any agent tool. A dedicated plugin for Claude Code is also available.
- The core scripts used by the agent are simple: `discover-servers.sh` (detecting running Marimo servers) and `execute-code.sh` (executing code). Access to the notebook can be automatically detected without a token (--no-token) or authenticated using the `MARIMO_TOKEN` environment variable.
- Unlike traditional agent approaches that submit ephemeral scripts, agents working with marimo-pair can understand the notebook's cell structure and current state, enabling more natural collaboration between humans and models with shared context.
- According to the development team, this project was a unique engineering experience of creating an 'API that is consumed by the model'. They were able to repeatedly change the skill interface without version migration because the model could read documentation and discover new features within the session.
- Marimo notebooks' ability to well-describe their current state and structure is a key advantage, providing agents with rich context. The agent can explore and experiment while simultaneously creating reproducible artifacts (the notebook).
- Currently, the project has received 169 stars on GitHub (as of 2025) and is in its early stages, released up to v0.0.11. It is open-source under the Apache-2.0 license.
Evidence
- A user shared their experience successfully completing a data science task with a Medicaid dataset using marimo-pair, stating that it 'worked right away without bugs'.
- Users noted that Marimo's reactive model's inability to reassign variables caused confusion for the agent (Claude). The LLM repeatedly 'forgot' that variables cannot be absolutely reassigned due to the graph structure, which is a necessary trade-off for Marimo's interactivity.
- A developer who used an external persistent store like BigQuery for agent state isolation when building a multi-agent trading system acknowledged the advantage of marimo-pair's approach: 'If the runtime itself is memory, you get reproducibility for free'.
- A developer from Posit introduced a simple REPL-based MCP tool (mcp-repl) and sparked a detailed discussion about the design trade-offs between 'maintaining a simple interaction model like REPL and keeping the context small' and 'introducing a notebook structure like Marimo early on to allow the model to explore and generate artifacts simultaneously'.
- Similar open-source projects like Jeremy Howard's solveit and ipyai (fast.ai/answer.ai), and independent developers' agentnb, cleon, and replsh were shared in the comments, demonstrating that the idea of 'using notebooks as agent execution environments' is being explored by multiple teams simultaneously.
How to Apply
- If you are already using Claude Code and performing data analysis in Marimo notebooks, you can install the plugin with the commands `/plugin marketplace add marimo-team/marimo-pair` → `/plugin install marimo-pair@marimo-team-marimo-pair`, allowing Claude to directly access and execute cells in the currently open notebook session and view the results.
- If you are annoyed by repetitive Bash permission prompts, you can add the absolute path of the installed skill's scripts to the `permissions.allow` array in `.claude/settings.json` to automatically allow them. Configure per-project in the project root's `.claude/settings.json`, or globally in `~/.claude/settings.json`.
- If you want to manage data analysis work reproducibly as a team, the agent's work is saved cell by cell in the notebook, making the notebook itself an experimental artifact and a prompt history. Leveraging this feature to version control agent work results in the notebook ensures reproducibility.
- If you are using an agent tool other than Claude Code, you can install it with `npx skills add marimo-team/marimo-pair` if the tool supports the Agent Skills open standard. If npx is not available, you can use `uvx deno -A npm:skills add marimo-team/marimo-pair` if uv is installed.
Code Example
snippet
# Claude Code plugin installation
/plugin marketplace add marimo-team/marimo-pair
/plugin install marimo-pair@marimo-team-marimo-pair
# Agent Skills (npx) installation
npx skills add marimo-team/marimo-pair
# Installation in uv environment (when npx is not available)
uvx deno -A npm:skills add marimo-team/marimo-pair
# Allow automatic detection without token when running Marimo server
marimo edit notebook.py --no-token
# Use environment variable for authentication if required
export MARIMO_TOKEN=your_token_here
# .claude/settings.json - Automatic Bash permission allowance configuration
{
"permissions": {
"allow": [
"Bash(bash /path/to/skills/marimo-pair/scripts/discover-servers.sh *)",
"Bash(bash /path/to/skills/marimo-pair/scripts/execute-code.sh *)"
]
}
}Terminology
reactive notebookA notebook that automatically tracks dependencies between cells, re-executing other cells that depend on it when a value in one cell changes. Think of it as a connected computation graph, similar to a spreadsheet.
Agent SkillsAn open standard designed to make agent tools interoperable. It allows you to install and manage skills that can be used across multiple agent tools like npm packages using `npx skills add`.
ephemeral scriptA one-time-use script that the agent executes and then discards, returning only the result. It does not maintain state, making it difficult to continue from previous execution contexts.
MCPShort for Model Context Protocol, it's a protocol that allows AI models to access external tools and data sources in a standardized way. Agents use it to interact with notebooks, databases, APIs, and other environments.
drop-inA way to integrate something into an existing system with minimal modification. In this case, it means adding an agent to an already running notebook session without extensive setup.
artifactA file or structure that remains as a result of an agent or model's work. In the context of marimo-pair, it refers to the agent's work being saved as notebook cells, creating a reproducible document.