Using Claude Code with marimo

In this blog we explain why agentic coding tools like Claude work exceptionally well with marimo, especially when compared to other notebooks such as Jupyter. We also share tips on how to best use Claude when working with marimo. While this blog focuses on Claude Code, you don’t have to use your terminal if you don’t want to: in a future blog post we’ll describe how marimo provides a batteries-included AI-native editor, with a best-in-class experience for working with LLMs and your data in a single development environment

TL;DR: Quickstart.

curl https://docs.marimo.io/CLAUDE.md > ~/.claude/prompts/marimo.md
marimo edit notebook.py --watch
# in a different terminal tab
claude

Claude Code has taken professional software development by storm: when you walk around at a tech conference, you’ll see a lot of terminal user interfaces with a chat interface on display. The combination of human and agent in the terminal lets developers and AI collaborate on software development in a tight feedback loop, together with an immensely powerful ecosystem of command-line tools that has been developed over multiple decades.

Why Claude Code works better with marimo

Traditional notebooks such as Jupyter notebooks as well as commercial notebooks such as Deepnote and Hex are ill-suited for use with agentic coding tools.

File format. By default Jupyter notebooks are stored as JSON with base64-encoded outputs, not Python. But LLMs work best when generating code, and marimo is stored as Python, not JSON, empowering agents to do their best work.

Reproducibility. Jupyter notebooks, as well as their commercial skins, suffer from a reproducibility crisis: they are not well-formed programs but instead have hidden state and hidden bugs. This trips up not only humans but also agents. In contrast, marimo notebooks are reproducible Python programs with well-defined execution semantics, backed by a dataflow graph.

Composability and programmability. Commercial notebooks like Hex and Deepnote provide a point-and-click UI for creating interactive elements such as sliders, text boxes, dropdowns, and more. LLMs-based agents struggle with this; in contrast, marimo is code-first, letting humans and agents alike create powerful UIs with just Python.

(Of course, commercial notebooks are proprietary, so you couldn’t author them locally from your terminal even if you wanted to. Because marimo is open-source, you can use it locally, on cloud servers, wherever you like.)

Introspection. Agents work best when they can test what they’ve done. marimo notebooks are Python programs, so agents can run them and inspect outputs; the same is not true for Jupyter notebooks.

A human-computer symbiosis

AI and data development is different from traditional software engineering: it’s an exploratory process where you work together with your computer to discover what effect your algorithms have on your data, not to mention to uncover both quantitative and qualitative aspects of your data. For example:

• You might not understand the convergence behavior of your new training algorithm until you run it on a variety of different data and study loss curves.
• You’re searching for outliers in your data (you know you have some!), but you’re not exactly sure what the shape of an outlier is; you need to rely on your intuition as you interactively search through a dimensionality-reduced representation of your data.
• Your user data might look great in raw numbers — but stare at the data long enough, and you may notice some surprisingly long sessions. Are there bots in your application?
• You’re a quant and you’ve deployed a machine learning pipeline, but its online performance is far worse than what offline validation predicted. You wrangle the training data, only to find that you had a data leak based on time, making your backtests untrustworthy.
• You’re working on LLM evals and you want to understand the kinds of mistakes the model makes. You look at the data with a bespoke marimo-based UI and spend half an hour reviewing conversations. That’s when you realize a tool-call that never triggers. You turn this insight into an eval and build a classifier to help you find offending examples.
• You’re a knowledge worker building marimo-based web tools for yourself, connected to your own data, and need to conduct what-if analyses to decide your course of action. The AI built the tool for you, but you need to use it to know if it’s any good and what to do next.

So, instead of trying to get Claude to entirely automate data work, we think it’s better to explore ways where you and Claude can work together — fostering a “human-computer symbiosis”.

Kasparov drew the only conclusion he could: “Weak human + machine + better process was superior to a strong computer alone and, more remarkably, superior to a strong human + machine + inferior process.” This revelation points to the essential evolution of the conclusion from Deep Blue in 1997—that humans working together with machines can solve big data challenges better than computers alone. Tackling big data means more than just algorithms, high-performance computing, and massive storage—it means leveraging the abilities of the human mind.

• National Academies of Sciences, Engineering, and Medicine. 2012. Big Data: A Workshop Report. Washington, DC: The National Academies Press.

marimo uniquely supports a “watch” option, which allows marimo to look for changes to the notebook file on disk and reload edits in the browser editor. This lets you and Claude work together.

Tips for using Claude Code with marimo

Here are tips for using Claude with marimo.

1. Download our CLAUDE.md file: curl https://docs.marimo.io/CLAUDE.md > ~/.claude/prompts/marimo.md
2. Start your notebook with --watch, which lets marimo watch the filesystem for changes: marimo edit --watch notebook.py
3. Claude 4.1 is good at writing marimo notebooks, partially because marimo notebooks are just Python files with a clear internal structure. However, we have noticed that it helps if you can point claude to a pre-existing notebook and don’t ask it to generate one from scratch. (“See @my_notebook.py for an example marimo notebook.”)
4. Use SHIFT+TAB in Claude to toggle between planning and editing mode. Planning can be helpful if you’re asking Claude to write a lot of Python or SQL.
5. You can ask Claude to write markdown for you, to generate documentation as it codes.
6. Claude can run notebooks as Python scripts to check itself; if you are running marimo with --sandbox, this is as simple as uv run notebook.py.
7. For dataframes, ask Claude to write functions of the dataframe operations, so you or Claude can use the pipe() feature of Polars and Pandas.
8. You can ask Claude to read data files to get additional context about the task at hand.

Conclusion

Claude Code has moved a lot of our work away from IDEs and into terminals again. It’s not a great interface for everything though. marimo notebooks give you the best environment to do creative work with data. You simply need to be able to get surprised by the results that you see, and you need interactive development environments for that.

The best way forward is to use both tools and to leverage them in such a way that you get the best of both worlds. Claude still makes the edits while the human interfaces with the notebook in order to stay in the loop. marimo’s predictive execution means you’re collaborating on a document that stays reproducible. Claude can help you explore data and generate code, but the end result is a reproducible artifact of that “collaboration”.

We’re actively working on tools to improve the marimo experience with coding agents. A part of that effort is that we’ve also started recording ourselves live as we explore different tools and techniques. Check out our YouTube video to learn more.