Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

docs: marimo pair (#9089)

Akshay Agrawal8f6ef3414839
diff --git a/docs/guides/generate_with_ai/index.md b/docs/guides/generate_with_ai/index.md
index 7c0264700e..2365eb0ad5 100644
--- a/docs/guides/generate_with_ai/index.md
+++ b/docs/guides/generate_with_ai/index.md
@@ -2,8 +2,9 @@
| Guide | Description |
|-------|-------------|
+| [Using agent CLIs](marimo_pair.md) | Collaborate on notebooks with agents using marimo pair |
| [Skills](skills.md) | Skills for coding agents |
-| [Zero-shot entire notebooks](text_to_notebook.md) | Generate entire notebooks with AI |
-| [AI-assisted coding](../editor_features/ai_completion.md) | Refactor code and generate cells with AI |
+| [Other tips for agent CLIs](using_claude_code.md) | Collection of utilities to get the most out of Claude Code |
+| [Using the marimo editor's AI features](../editor_features/ai_completion.md) | Refactor code and generate cells with AI |
| [Prompts for the marimo editor](prompts.md) | Collection of prompts to speed up workflows in marimo |
-| [Using Claude Code](using_claude_code.md) | Collection of utilities to get the most out of Claude Code |
+| [Generate notebooks with marimo new](text_to_notebook.md) | Generate entire notebooks with AI |
diff --git a/docs/guides/generate_with_ai/marimo_pair.md b/docs/guides/generate_with_ai/marimo_pair.md
new file mode 100644
index 0000000000..0e177f065e
--- /dev/null
+++ b/docs/guides/generate_with_ai/marimo_pair.md
@@ -0,0 +1,42 @@
+# Collaborate with agents using marimo pair
+
+Give your agent CLIs (such as Claude Code, Codex, and OpenCode) full access to running marimo notebooks with the **[marimo
+pair](https://github.com/marimo-team/marimo-pair)** agent skill.
+
+marimo pair is the recommended way to collaborate on marimo notebooks with
+agents. It lets your agent read variables, test logic in a scratchpad, run
+cells, add and remove cells, and even manipulate UI elements.
+
+<div style="text-align: center">
+ <iframe width="100%" style="aspect-ratio: 16/9; max-width: 800px"
+ src="https://www.youtube.com/embed/VKvjPJeNRPk?si=JMvoFiDFNtT1BsJY"
+ title="YouTube video player" frameborder="0" allow="accelerometer; autoplay;
+ clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+ referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
+</div>
+
+## Quickstart
+
+Install the skill with:
+
+/// tab | install with npm
+
+```bash
+npx skills add marimo-team/marimo-pair
+```
+
+///
+
+/// tab | install with uv
+
+```bash
+uvx deno -A npm:skills add marimo-team/marimo-pair
+```
+
+///
+
+Then pair on your first notebook by pasting the following in your agent CLI:
+
+```
+/marimo-pair pair with me on my_notebook.py
+```
diff --git a/docs/guides/generate_with_ai/using_claude_code.md b/docs/guides/generate_with_ai/using_claude_code.md
index b1d5fec039..c833d28c0c 100644
--- a/docs/guides/generate_with_ai/using_claude_code.md
+++ b/docs/guides/generate_with_ai/using_claude_code.md
@@ -1,3 +1,10 @@
+!!! tip "Use marimo pair to give agents access to running marimo notebook sessions"
+
+ For the best experience using Claude Code with marimo, we recommend
+ [marimo pair](marimo_pair.md), an agent skill that gives Claude Code
+ full access to your running notebook, including reading variables, running
+ cells, and manipulating UI elements.
+
Claude lets you customise the marimo editing experience with its agent. This page lists some worthwhile utilities, and we also provide compelling use cases related to marimo notebooks.
### Slash commands
diff --git a/mkdocs.yml b/mkdocs.yml
index 0669e72938..6fe0f86da1 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -111,11 +111,12 @@ nav:
- Using uv: guides/package_management/using_uv.md
- Generate with AI:
- Generate with AI: guides/generate_with_ai/index.md
+ - Using agent CLIs: guides/generate_with_ai/marimo_pair.md
- Skills: guides/generate_with_ai/skills.md
- - Generate entire notebooks: guides/generate_with_ai/text_to_notebook.md
- - AI-assisted coding: guides/editor_features/ai_completion.md
- - Prompts: guides/generate_with_ai/prompts.md
- - Using Claude Code: guides/generate_with_ai/using_claude_code.md
+ - Other tips for agent CLIs: guides/generate_with_ai/using_claude_code.md
+ - Using the marimo editor's AI features: guides/editor_features/ai_completion.md
+ - Prompts for the marimo editor: guides/generate_with_ai/prompts.md
+ - Generate notebooks with marimo new: guides/generate_with_ai/text_to_notebook.md
- Editor features:
- Editor features: guides/editor_features/index.md
- Editor overview: guides/editor_features/overview.md