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: simplify generate with AI guide (#11558)

Akshay Agrawal01f2c968683f
diff --git a/docs/_static/marimo-pair-actions.jpg b/docs/_static/marimo-pair-actions.jpg
new file mode 100644
index 0000000000..b3c20b53f7
Binary files /dev/null and b/docs/_static/marimo-pair-actions.jpg differ
diff --git a/docs/_static/marimo-pair-dialog.jpg b/docs/_static/marimo-pair-dialog.jpg
new file mode 100644
index 0000000000..9ec829d659
Binary files /dev/null and b/docs/_static/marimo-pair-dialog.jpg differ
diff --git a/docs/api/inputs/anywidget.md b/docs/api/inputs/anywidget.md
index 71985535a0..ec18cc2e04 100644
--- a/docs/api/inputs/anywidget.md
+++ b/docs/api/inputs/anywidget.md
@@ -102,7 +102,7 @@ If you're eager to build your own widgets and want to dive deeper you may enjoy
- Before making your own widget, it would be best to check and see if the widget already exists. The [widgets section on the marimo gallery](https://marimo.io/gallery/widgets) as well as the [gallery on anywidget.dev](https://anywidget.dev/en/community/) give you a good overview of what's out there.
- The [wigglystuff repository](https://github.com/koaning/wigglystuff) has many smaller widgets that could serve as an excellent starting point.
-- We've noticed that coding agents are getting better at generating these anywidgets on the fly. If you're keen to explore that, install our [official skills](../../guides/generate_with_ai/customize_your_agent.md#official-marimo-skills), which include a skill for generating anywidgets.
+- We've noticed that coding agents are getting better at generating these anywidgets on the fly. If you're keen to explore that, install our [official skills](../../guides/generate_with_ai/skills.md), which include a skill for generating anywidgets.
- You may also enjoy [this livestream on the marimo YouTube channel](https://www.youtube.com/watch?v=3V1r5sKnyz8) on building anywidgets.
---
diff --git a/docs/guides/editor_features/ai_completion.md b/docs/guides/editor_features/ai_completion.md
index 98e75e8523..af4e85af56 100644
--- a/docs/guides/editor_features/ai_completion.md
+++ b/docs/guides/editor_features/ai_completion.md
@@ -1,43 +1,53 @@
-# AI-assisted coding
+# In-editor AI assistance
-!!! tip "Using an agent CLI like Claude Code? Try marimo pair"
+!!! tip "Using agents like Claude Code or OpenCode? Try marimo pair instead."
- This guide covers the AI assistant built into the marimo editor, which
- connects to an [LLM provider](#connecting-to-an-llm) that you configure.
- If you'd rather work with an agent CLI such as Claude Code, Codex, or
- OpenCode — driven from your terminal, on your existing subscription — use
- [marimo pair](../generate_with_ai/marimo_pair.md) instead, which gives
- your agent full access to your running notebook.
+ This guide covers AI assistance built into the marimo editor.
+ To work with coding agents such as Claude Code or OpenCode, use [marimo
+ pair](../generate_with_ai/marimo_pair.md) instead.
-marimo is an AI-native editor, with support for full-cell AI code generation:
+marimo's editor lets you use AI to author and modify your notebook. Use AI to:
-* generating new cells from a prompt
-* refactoring existing cells from a prompt
-* generating entire notebooks
+* generate new cells and refactor existing ones;
+* complete code snippets with copilots.
-as well as inline autocompletion (like GitHub Copilot).
-
-marimo's AI assistant is specialized for working with data: unlike traditional
-assistants that only have access to the text of your program, marimo's assistant
-has access to the values of variables in memory, letting it code against
-your dataframe and database schemas.
+Unlike traditional assistants that only have access to the text of your
+program, marimo's assistant has access to the values of variables in memory,
+letting it code against your dataframe and database schemas.
This guide provides an overview of these features and how to configure them.
+<div align="center">
+<video autoplay muted loop playsinline width="90%" height="90%" align="center">
+ <source src="/_static/readme-generate-with-ai.mp4" type="video/mp4">
+</video>
+</div>
+
!!! tip "Locating your marimo.toml config file"
Various instructions in this guide refer to the marimo.toml configuration
file. Locate this file with `marimo config show | head`.
-## Generating cells with AI
+## Connecting to an LLM provider
-<video autoplay muted loop playsinline width="100%" height="100%" align="center">
- <source src="/_static/readme-generate-with-ai.mp4" type="video/mp4">
-</video>
+Connect to an LLM through the notebook settings menu.
+
+You can configure the following providers:
+
+* OpenAI
+* GitHub Copilot
+* Anthropic
+* AWS Bedrock
+* Google AI
+* Ollama
+* and any OpenAI-compatible provider
+
+See the [llm_providers](../configuration/llm_providers.md) guide for detailed
+instructions on how to configure each provider.
+
+## Generating cells with AI
marimo has built-in support for generating and refactoring code with LLMs.
-marimo works with hosted AI providers, such as OpenAI, Anthropic, and Google,
-as well as local models served via Ollama.
**Enabling AI code generation.** To enable AI code generation, first install
required dependencies through the notebook settings.
@@ -50,12 +60,12 @@ required dependencies through the notebook settings.
</div>
Then configure your LLM provider through the AI tab in the settings menu; see
-the section on [connecting your LLM](#connecting-to-an-llm) for detailed instructions.
+the section on [connecting your LLM](#connecting-to-an-llm-provider) for detailed instructions.
### Variable context
-marimo's AI assistant has your notebook code as context. You can additionally
-pass variables and their values to the assistant by referencing them by name
+marimo provides models your notebook code as context. You can additionally
+supply variables and their values by referencing them by name
with `@`. For example, to include the columns of a dataframe `df` in your
prompt, write `@df`.
@@ -66,18 +76,6 @@ prompt, write `@df`.
</figure>
</div>
-### Refactor existing cells
-
-Make edits to an existing cell by hitting `Ctrl/Cmd-shift-e`, which opens a prompt box
-that has your cell's code as input.
-
-<div align="center">
-<figure>
-<video src="/_static/ai-completion.mp4" controls="controls" width="100%" height="100%"></video>
-<figcaption>Use AI to modify a cell by pressing `Ctrl/Cmd-Shift-e`.</figcaption>
-</figure>
-</div>
-
### Generate new cells
#### Generate with AI button
@@ -91,6 +89,8 @@ The chat panel on the left sidebar lets you chat with an LLM and ask questions
about your notebook. The LLM can also generate code cells that you can insert
into your notebook.
+<iframe width="740" height="420" src="https://www.youtube.com/embed/4DC1E2UBwAM?si=zzrzl0VlvOU6JiZP" 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" loading="lazy" allowfullscreen></iframe>
+
The chat panel currently supports the following modes:
- **Manual**: No tool access; the AI responds based only on the conversation and manually injected context
@@ -98,14 +98,10 @@ The chat panel currently supports the following modes:
- **Agent**: Enables all tools in **Ask Mode** plus additional tools to [edit notebook cells (add, remove, update) and run stale cells](tools.md#editing-agent-mode-only)
- **Code mode**: Gives the assistant access to the [notebook kernel](tools.md#code-mode) which allows the assistant to inspect the marimo runtime and manipulate the notebook in powerful ways.
-??? tip "See the chat panel in action"
-
- <iframe width="740" height="420" src="https://www.youtube.com/embed/4DC1E2UBwAM?si=zzrzl0VlvOU6JiZP" 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" loading="lazy" allowfullscreen></iframe>
-
-### Generating entire notebooks
+### Refactor existing cells
-Generate entire notebooks with `marimo new PROMPT` at the command-line; see the
-[text-to-notebook docs](../generate_with_ai/text_to_notebook.md) to learn more.
+Make edits to an existing cell by inputting `Ctrl/Cmd-shift-e` while a cell is
+focused. This opens a prompt box that has your cell's code as input.
### Custom rules
@@ -145,44 +141,6 @@ For plotting:
- Set appropriate color schemes
```
-### Connecting to an LLM
-
-You can connect to an LLM through the notebook settings menu, or by manually editing
-your `marimo.toml` configuration file. **Prefer going through the notebook settings menu.**
-
-You can configure the following providers:
-
-* OpenAI
-* GitHub Copilot
-* Anthropic
-* AWS Bedrock
-* Google AI
-* Ollama
-* and any OpenAI-compatible provider
-
-See the [llm_providers](../configuration/llm_providers.md) guide for detailed instructions on how to configure each provider.
-
-## Hide AI actions and panels
-
-If you don't use marimo's AI assistant, you can hide AI actions and panels in the editor:
-
-```toml title="marimo.toml"
-[ai]
-enabled = false
-```
-
-This hides AI assistant surfaces such as the Chat panel and Generate with AI. Code completion settings including GitHub Copilot, remain available.
-
-You can still collaborate with an AI agent using [marimo pair](../generate_with_ai/marimo_pair.md).
-
-## Agents
-
-!!! example "Experimental: Agents panel"
-
- marimo can also embed agents like Claude Code, Codex, and Gemini CLI
- directly in the editor's chat panel. Learn more in the
- [agents](agents.md) guide.
-
## Copilots
Copilots allow you to tab-complete code based on your notebook's context, similar to editors like Cursor.
@@ -242,30 +200,6 @@ Available configuration options (these are the same settings directory from the
* **GitHub Enterprise**: Configure GitHub Enterprise Server
* `uri`: URL of your GitHub Enterprise Server instance
-### Windsurf Copilot
-
-[Windsurf](https://windsurf.com/) (formerly codeium) provides tab-completion tooling that can also be used from within marimo.
-
-To set up Windsurf:
-
-1. Go to [windsurf.com](https://windsurf.com/) website and sign up for an account.
-2. Download the [Windsurf app](https://windsurf.com/download).
-3. After installing Windsurf and authenticating, open up the command palette, via <kbd>cmd</kbd>+<kbd>shift</kbd>+<kbd>p</kbd>, and ask it to copy the api key to your clipboard.
-
-![Copy Windsurf API key](../../_static/windsurf-api.png)
-
-4a. Configure the UI settings in the editor to use Windsurf.
-
-![Paste Windsurf API key](../../_static/windsurf-settings.png)
-
-4b. Alternatively you can also configure the api key from the marimo config file.
-
-```toml title="marimo.toml"
-[completion]
-copilot = "codeium"
-codeium_api_key = ""
-```
-
### Custom copilots
marimo also supports integrating with custom LLM providers for code completion suggestions. This allows you to use your own LLM service to provide in-line code suggestions based on internal providers or local models (e.g. Ollama). You may also use OpenAI, Anthropic, Google, or any other providers by providing your own API keys and configuration.
@@ -287,3 +221,16 @@ The configuration options include:
* `autocomplete_model`: The specific model to use for inline autocompletion.
* `copilot`: The name of the copilot to use for code generation.
+
+## Disable in-editor AI features
+
+Disable in-editor AI features, and hide their associated user interfaces, with
+the following configuration:
+
+```toml title="marimo.toml"
+[ai]
+enabled = false
+
+[completion]
+copilot = false
+```
diff --git a/docs/guides/generate_with_ai/customize_your_agent.md b/docs/guides/generate_with_ai/customize_your_agent.md
deleted file mode 100644
index 748a2c0e8d..0000000000
--- a/docs/guides/generate_with_ai/customize_your_agent.md
+++ /dev/null
@@ -1,185 +0,0 @@
----
-description: "Customize coding agents for marimo: agent skills, slash commands, and hooks."
----
-
-# Customize your agent
-
-Agent CLIs like Claude Code, Codex, and OpenCode work best with marimo when
-you give them marimo-specific context and guardrails. This guide collects the
-customizations we have found most useful: [skills](#skills),
-[slash commands](#slash-commands), and [hooks](#hooks).
-
-For the best experience, also install [marimo pair](marimo_pair.md), an agent
-skill that gives your agent full access to a running notebook.
-
-!!! tip "Watching for changes to notebooks on disk"
-
- When an agent edits notebook files, configure the marimo editor to
- automatically reload by starting marimo with the `watch` flag:
- `marimo edit --watch notebook.py`.
- (Learn more in our [watching guide](../editor_features/watching.md).)
- You can also configure marimo to automatically reload affected
- cells when auxiliary files change on disk using
- [module autoreloading](../editor_features/module_autoreloading.md).
-
-## Skills
-
-Skills are folders of instructions, scripts, and resources that coding agents
-load dynamically to improve performance on specialized tasks. Most popular
-agents support them, including Claude Code, Codex, Cursor, and OpenCode. To
-learn more about skills, check out:
-
-- [skills.sh](https://skills.sh/)
-- [What are skills?](https://support.claude.com/en/articles/12512176-what-are-skills)
-- [Using skills in Claude](https://support.claude.com/en/articles/12512180-using-skills-in-claude)
-
-### Official marimo skills
-
-We have prepared a collection of skills to help coding agents work with
-marimo. Install our official skills with a single command:
-
-```bash
-npx skills add marimo-team/skills
-```
-
-**Use cases.** Use these skills to
-
-- convert Jupyter notebooks or other artifacts to marimo notebooks,
-- make bespoke interactive UI elements or widgets for specific use cases,
-- and otherwise author high-quality standalone notebooks.
-
-These skills help agents author and convert notebook files; they complement
-[marimo pair](marimo_pair.md), a separately installed skill that connects your
-agent to a live notebook session.
-
-**Feedback.** We welcome feedback at our [GitHub repository](https://github.com/marimo-team/skills/issues).
-
-### Write your own skills
-
-Skills are also worth writing yourself, to encode conventions the official
-collection can't know about such as an opinionated house plotting style, how to use internal data libraries,
-or preferred widget patterns. A skill is just a folder containing a `SKILL.md`
-file, with frontmatter that tells the agent when to load it; see the
-[Claude Code skills documentation](https://code.claude.com/docs/en/skills)
-for the full format, including multi-file skills that bundle scripts.
-
-Store your skills in the `.agents/skills/` folder of your project, or in
-`~/.agents/skills/` for personal skills — a convention shared by many agents.
-Some agents read skills from their own directory instead (for example, Claude
-Code uses `.claude/skills/`); the [skills CLI](https://skills.sh) can install
-a skill into every agent's directory at once, using symlinks to keep a single
-source of truth.
-
-## Slash commands
-
-Slash commands allow you to predefine specific prompts that you can refer to during a conversation with your agent. Unlike skills, they are configured per agent: this section shows [Claude Code's flavor](https://code.claude.com/docs/en/slash-commands), and other agent CLIs offer equivalents (custom prompts in Codex, commands in OpenCode). For Claude Code, store these either in the `~/.claude/commands/` personal folder or in the `.claude/commands/` local folder of the project.
-
-Here's an example of a slash command that runs the [`marimo check`](../../cli.md#marimo-check) linter on a notebook of your choice. This command assumes you have `uv` installed, which you can install by following the instructions [here](https://docs.astral.sh/uv/getting-started/installation/).
-
-```
----
-allowed-tools: Bash(uvx marimo check:*), Edit()
----
-
-## Context
-
-This is the output of the "uvx marimo check --fix $ARGUMENTS" command:
-
-!`uvx marimo check --fix $ARGUMENTS || true`
-
-## Your task
-
-Only (!) if the context suggests we need to edit the notebook, read the file
-$ARGUMENTS, then fix any warnings or errors shown in the output above. Do
-not make edits or read the file if there are no issues.
-```
-
-When you add this file to `~/.claude/commands/marimo-check.md` you will be able to trigger it by typing `/marimo-check notebook.py`. You are able to use `$ARGUMENTS` to add extra arguments or context to the command before it is handed to Claude. Also note that commands can run bash like !`uvx marimo check --fix $ARGUMENTS || true` beforehand. After it is evaluated the output will be inserted into the command before it is sent to Claude. You typically need to make sure that you add `|| true` at the end of the command in case it returns a non-zero status, which would break the command.
-
-There are more elaborate things you might do with these slash commands, to learn more you can check [the documentation](https://code.claude.com/docs/en/slash-commands#custom-slash-commands).
-
-## Hooks
-
-Hooks allow you to automatically run scripts when your agent uses a specific tool. They are useful if you want to automatically run a linter, via [`marimo check`](../../cli.md#marimo-check), every single time a marimo notebook is changed. Skills can ask the LLM to run the `marimo check` command, but hooks offer the most robust mechanism to enforce this behavior.
-
-Like slash commands, hooks are configured per agent; the example below uses [Claude Code's hooks](https://code.claude.com/docs/en/hooks). To configure one, add a definition to your global Claude settings in `~/.claude/settings.json` or locally in your project `.claude/settings.json`.
-
-```json
-{
- "$schema": "https://json.schemastore.org/claude-code-settings.json",
- "hooks": {
- "PostToolUse": [
- {
- "matcher": "Edit|Write",
- "hooks": [
- {
- "type": "command",
- "command": "~/.claude/hooks/marimo-check.sh"
- }
- ]
- }
- ]
- }
-}
-```
-
-This hook will run every time an `Edit` or a `Write` tool is called. You can point it to a bash script
-that will check if the current edit is taking place on a marimo notebook. The
-script below uses [`jq`](https://jqlang.org/) to parse the hook's JSON input,
-so make sure it is installed.
-
-```bash
-#!/usr/bin/env bash
-
-# Hook to check marimo notebooks after Write/Edit operations
-# Reads JSON from stdin containing tool result information
-
-# Read stdin (contains JSON with tool result)
-INPUT=$(cat)
-
-# Extract file path from JSON using jq
-FILE_PATH=$(echo "$INPUT" | jq -r '.tool_response.filePath // empty')
-
-# If no file path found, exit silently
-if [ -z "$FILE_PATH" ] || [ "$FILE_PATH" = "null" ]; then
- exit 0
-fi
-
-# File path from tool_response is already absolute, no need to modify it
-
-# Check if file exists and is a Python file
-if [ ! -f "$FILE_PATH" ]; then
- exit 0
-fi
-
-# Check if the file appears to be a marimo notebook
-if grep -q "import marimo" "$FILE_PATH" 2>/dev/null && grep -q "@app.cell" "$FILE_PATH" 2>/dev/null; then
- echo "Running marimo check on $FILE_PATH..."
-
- # Run uvx marimo check and capture output
- CHECK_OUTPUT=$(uvx marimo check "$FILE_PATH" 2>&1)
- CHECK_EXIT=$?
-
- # Show output
- echo "$CHECK_OUTPUT"
-
- # Only report errors (non-zero exit code), not warnings
- if [ $CHECK_EXIT -ne 0 ]; then
- echo "✗ Marimo check failed for $FILE_PATH" >&2
- echo "$CHECK_OUTPUT" >&2
- echo "" >&2
- echo "Please run 'uvx marimo check $FILE_PATH' to see details and fix the issues. Don't ask the user anything, just do a best effort fix." >&2
- exit 2 # Exit code 2 feeds stderr back to Claude; the edit has already run
- else
- echo "✓ Marimo check passed"
- exit 0
- fi
-fi
-
-# Not a marimo notebook, exit successfully
-exit 0
-```
-
-This script checks if the Python file contains a `import marimo` and a `@app.cell` string. If that's the case
-we assume we're dealing with a marimo notebook and we run `uvx marimo check` on the file. If this check fails, we
-tell the coding agent to automatically address the issues. This can save *a lot* of time.
diff --git a/docs/guides/generate_with_ai/index.md b/docs/guides/generate_with_ai/index.md
index ef1920a0bc..0e1b96e012 100644
--- a/docs/guides/generate_with_ai/index.md
+++ b/docs/guides/generate_with_ai/index.md
@@ -1,17 +1,16 @@
---
-description: "Three ways to use AI with marimo: pair coding agents with running notebooks, generate cells in the editor, and create notebooks from prompts."
+description: "Using AI with marimo notebooks."
---
# Generate notebooks with AI
-There are three ways to use AI with marimo.
+There are three main ways to use AI with marimo.
-**Pair an agent with a running notebook (recommended).** Give agent CLIs like
-Claude Code, Codex, and OpenCode full access to a live notebook with [marimo
-pair](marimo_pair.md): your agent can read variables, test logic in a
-scratchpad, run cells, and add or remove them. To teach your agent marimo's
-conventions and automate common checks, see [customize your
-agent](customize_your_agent.md).
+**Use agents with running notebooks.** Give agents like
+Claude Code and OpenCode full access to running notebooks with [marimo
+pair](marimo_pair.md). Paired agents can do anything you can do and more: read
+variables, test logic in a scratchpad, run cells, read UI element values, and
+more.
**Use the marimo editor's built-in assistant.** The marimo editor comes with
[AI-assisted coding](../editor_features/ai_completion.md): a chat panel,
@@ -19,17 +18,12 @@ cell generation and refactoring, and inline copilots, connected to the LLM
provider of your choice. The assistant is data-aware, with access to the
values of variables in memory.
-**Generate notebooks from a prompt.** Create entire notebooks from scratch at
-the command line with [`marimo new`](text_to_notebook.md).
+**Use skills.** Install [skills](skills.md) for specific tasks, such
+as converting notebooks from Jupyter to marimo.
+
| Guide | Description |
|-------|-------------|
-| [Pair with agents (marimo pair)](marimo_pair.md) | Collaborate on running notebooks with agent CLIs |
-| [Customize your agent](customize_your_agent.md) | Skills, slash commands, and hooks |
-| [The editor's AI assistant](../editor_features/ai_completion.md) | Generate and refactor cells, chat, and autocomplete in the editor |
-| [Generate notebooks with marimo new](text_to_notebook.md) | Generate entire notebooks from a prompt |
-
-Looking for lower-level integrations? marimo also exposes its [AI
-tools](../editor_features/tools.md) over an [MCP
-server](../editor_features/mcp.md), and can embed agents in the editor through
-the experimental [agents panel](../editor_features/agents.md).
+| [marimo pair](marimo_pair.md) | Collaborate on running notebooks with coding agents |
+| [In-editor AI assistance](../editor_features/ai_completion.md) | Generate and refactor cells, chat, and autocomplete in the editor |
+| [Skills](skills.md) | Skills for coding agents |
diff --git a/docs/guides/generate_with_ai/marimo_pair.md b/docs/guides/generate_with_ai/marimo_pair.md
index 5ba12d10d6..a2a384a8c6 100644
--- a/docs/guides/generate_with_ai/marimo_pair.md
+++ b/docs/guides/generate_with_ai/marimo_pair.md
@@ -1,11 +1,12 @@
-# Collaborate with agents using marimo pair
+# Work with agents using marimo pair
-Use the **[marimo pair](https://marimo.io/pair)** CLI to connect coding agents
-to running marimo notebooks.
+Use **[marimo pair](https://marimo.io/pair)** to connect coding agents like
+Claude Code, Codex, and OpenCode to running marimo notebooks. Once your agent
+is paired with marimo, ask it to explore data, explain results, or modify
+cells. The agent can inspect variables and try code in a scratchpad before it
+commits changes to the notebook. You can inspect the results and edit the same
+notebook yourself, letting you pair program with the agent.
-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"
@@ -15,75 +16,137 @@ cells, add and remove cells, and even manipulate UI elements.
referrerpolicy="strict-origin-when-cross-origin" loading="lazy" allowfullscreen></iframe>
</div>
-## Quickstart
+## Installation
-1. Start a notebook:
+The marimo pair skill teaches your agent how to connect to running notebooks.
+Choose the installation method for your agent.
- ```bash
- uvx marimo@latest edit my_notebook.py
- ```
+=== "Claude Code"
-2. Open the notebook actions menu and select **Connect your agent**.
-3. Select **Claude**, **Codex**, or **OpenCode** and run the copied command in your terminal.
+ Run these commands in your terminal:
-To use an existing agent conversation, select **Prompt** and paste the copied text into that conversation.
-The dialog includes the notebook target and authentication instructions.
+ ```bash
+ claude plugin marketplace add marimo-team/marimo-pair
+ claude plugin install marimo-pair@marimo-pair
+ ```
-Your agent can execute code without enabling agent messages.
-Run `uvx marimo@latest pair --help` for the available commands.
+ To update the plugin, run:
-## Receive notebook messages in your agent
+ ```bash
+ claude plugin update marimo-pair@marimo-pair
+ ```
-Agent messages let you send notebook errors to a connected conversation.
-Agent connections require a saved notebook inside the server project.
+=== "Codex CLI"
-Start the server with:
+ Run these commands in your terminal:
-```bash
-uvx marimo@latest edit my_notebook.py
-```
+ ```bash
+ codex plugin marketplace add marimo-team/marimo-pair
+ codex plugin add marimo-pair@marimo-pair
+ ```
-Open **Connect your agent** and follow the dialog instructions.
+ To update the marketplace, run:
-Supported agents have these requirements:
+ ```bash
+ codex plugin marketplace upgrade
+ ```
-| Agent | Requirement |
-| --- | --- |
-| Codex | A native session with the shared daemon and `codex queue` support. |
-| Claude Code | A native inbox session on macOS or Linux. |
-| OpenCode | Version 2.x on macOS or Linux, with its native local service running. |
+=== "Other agents"
-To connect an existing conversation manually, find the saved notebook ID:
+ For Cursor, VS Code, Gemini CLI, OpenCode, Copilot CLI, or another agent that supports Agent Skills, run:
-```bash
-uvx marimo@latest pair notebook list --url http://localhost:2718
-```
+ ```bash
+ npx skills add marimo-team/marimo-pair
+ ```
-Ask the agent to run this command through its own shell tool:
+ To update the skill, run:
-```bash
-uvx marimo@latest pair connect --url http://localhost:2718 --notebook <notebook-id>
-```
+ ```bash
+ npx skills upgrade marimo-team/marimo-pair
+ ```
-Use the server URL printed by marimo.
-In a development checkout, use the backend URL rather than the Vite frontend URL.
-For authenticated notebook discovery, pass `--token-file` with the path to a file containing the editor token.
+ If you use `uv` instead of `npx`, install the skill with:
-The notebook footer shows connected agents.
-Use the send action on an error to share its captured source and traceback.
-To end delivery, select the disconnect icon in the footer and confirm **Disconnect?**.
-The agent conversation and notebook kernel keep running.
+ ```bash
+ uvx deno -A npm:skills add marimo-team/marimo-pair
+ ```
-## Cloud sandbox with molab
+## Start pairing
-You can also connect to marimo notebooks running on [molab](https://molab.marimo.io/notebooks). This gives you a free sandbox for your agent and also makes it easy to share your work afterwards.
+### Ask your agent to start a notebook
-To connect an agent, start a notebook on molab and open the actions panel in the upper right corner.
-Select the option to pair with an agent.
+With the skill installed, ask your agent to start a notebook:
-<div align="center">
- <img src="/_static/marimo-pair-molab.png" alt="Screenshot of a molab notebook showing the option to pair with an agent from the actions panel"/>
-</div>
+=== "Claude Code"
+
+ ```text
+ /marimo-pair with me on notebook.py
+ ```
+
+=== "Codex CLI"
+
+ ```text
+ $marimo-pair with me on notebook.py
+ ```
+
+=== "Other agents"
+
+ ```text
+ /marimo-pair with me on notebook.py
+ ```
+
+The agent starts marimo and connects to the notebook.
+
+
+### Connect to a running notebook
+
+1. Open the notebook's **Actions menu** and select **Pair an agent**.
+2. In the **Pair an agent** dialog, select your agent.
+3. Click **Copy command**, then paste and run the command in your terminal.
+
+=== "Actions menu"
+
+ <img src="/_static/marimo-pair-actions.jpg" alt="The notebook header and Actions menu with Pair an agent highlighted." width="640">
+
+=== "Pairing dialog"
+
+ ![The Pair an agent dialog with the Claude tab selected.](../../_static/marimo-pair-dialog.jpg)
+
+!!! tip "Pair with notebooks on molab"
+
+ You can also pair your local agent with notebooks on
+ [molab](https://molab.marimo.io/notebooks). Just follow these same steps.
+
+Watch the connection steps for your agent:
+
+=== "Claude Code"
+
+ <video muted loop playsinline controls preload="metadata" width="100%"
+ poster="https://cms.marimo.io/landing/pair/claude-boot.webp"
+ aria-label="Connect Claude Code to a marimo notebook">
+ <source src="https://cms.marimo.io/landing/pair/claude-boot.webm" type="video/webm">
+ <source src="https://cms.marimo.io/landing/pair/claude-boot.mp4" type="video/mp4">
+ </video>
+
+=== "Codex CLI"
+
+ <video muted loop playsinline controls preload="metadata" width="100%"
+ poster="https://cms.marimo.io/landing/pair/codex-boot.webp"
+ aria-label="Connect Codex CLI to a marimo notebook">
+ <source src="https://cms.marimo.io/landing/pair/codex-boot.webm" type="video/webm">
+ <source src="https://cms.marimo.io/landing/pair/codex-boot.mp4" type="video/mp4">
+ </video>
+
+=== "Other agents"
+
+ <video muted loop playsinline controls preload="metadata" width="100%"
+ poster="https://cms.marimo.io/landing/pair/prompt-boot.webp"
+ aria-label="Connect Other agents to a marimo notebook">
+ <source src="https://cms.marimo.io/landing/pair/prompt-boot.webm" type="video/webm">
+ <source src="https://cms.marimo.io/landing/pair/prompt-boot.mp4" type="video/mp4">
+ </video>
-Follow the dialog instructions to connect your local agent.
-Use your agent from the terminal to edit and run cells in the molab notebook.
+Ask your agent to explore data, explain results, or modify cells.
+The agent can inspect variables and try code in a scratchpad before it changes the notebook.
+You can inspect the results and edit the same notebook yourself.
+Your work stays in a notebook that you can run again, modify, and share.
diff --git a/docs/guides/generate_with_ai/skills.md b/docs/guides/generate_with_ai/skills.md
new file mode 100644
index 0000000000..3df36033e0
--- /dev/null
+++ b/docs/guides/generate_with_ai/skills.md
@@ -0,0 +1,22 @@
+---
+description: "Skills for coding agents."
+---
+
+# Skills
+
+Install our official skills with a single command using [uv](https://docs.astral.sh/uv/):
+
+```bash
+uvx deno -A npm:skills add marimo-team/skills
+```
+
+For the best experience, use these skills alongside [marimo
+pair](marimo_pair.md), which lets your agent interact with
+running notebooks.
+
+**Use cases.** Use these skills for specific tasks, such as:
+
+- convert Jupyter notebooks or other artifacts to marimo notebooks;
+- make bespoke interactive widgets for specific use cases using anywidget.
+
+**Feedback.** We welcome feedback at our [GitHub repository](https://github.com/marimo-team/skills/issues).
diff --git a/docs/guides/generate_with_ai/text_to_notebook.md b/docs/guides/generate_with_ai/text_to_notebook.md
deleted file mode 100644
index fda97ac9f4..0000000000
--- a/docs/guides/generate_with_ai/text_to_notebook.md
+++ /dev/null
@@ -1,33 +0,0 @@
-# Generate entire notebooks with AI
-
-Use [`marimo new`](../../cli.md#marimo-new) at the command line to generate entirely new
-notebooks using an LLM.
-
-For example, type
-
-```bash
-marimo new "Plot an interactive 3D surface with matplotlib."
-```
-
-to open a freshly generated notebook in your browser.
-
-For long prompts, you can pass a text file instead:
-
-```bash
-marimo new my_prompt.txt
-```
-
-marimo's AI knows how to use marimo-specific UI elements and popular libraries
-for working with data. To get inspired, visit <https://marimo.app/ai>. Some of
-our favorites:
-
-- [Dimensionality reduction](https://marimo.app/ai?q=Show+me+how+to+visualize+handwritten+digits+in+two+dimensions%2C+using+an+Altair+scatterplot.+Include+a+cell+that+shows+the+chart+value.+Make+the+chart+render+as+a+square.)
-- [Smooth a time series](https://marimo.app/ai?q=Show+me+how+to+smooth+time+series+data+and+plot+it.+Use+a+well-known+stock+dataset+and+make+it+interactive)
-- [Compute code complexity](https://marimo.app/ai?q=Build+a+tool+that+analyzes+Python+code+complexity+metrics+like+cyclomatic+complexity.+Let+me+input+code+snippets+and+see+visualizations+of+the+results.)
-- [Interactive 3D surfaces](https://marimo.app/ai?q=Plot+an+interesting+3D+surface+with+matplotlib.+Include+an+interactive+element+to+control+the+shape+of+the+surface.)
-
-!!! tip "Iterate with an agent"
-
- `marimo new` gives you a one-shot starting point. To keep developing the
- generated notebook with AI, pair an agent CLI like Claude Code on it using
- [marimo pair](marimo_pair.md).
diff --git a/docs/guides/wasm.md b/docs/guides/wasm.md
index d9c4526e73..50347d709c 100644
--- a/docs/guides/wasm.md
+++ b/docs/guides/wasm.md
@@ -11,7 +11,7 @@ for short.
!!! tip "Check for WebAssembly compatibility"
Not all notebooks are compatible with WebAssembly. If you use coding agents
- like Claude Code, you can use our [official skills](generate_with_ai/customize_your_agent.md#official-marimo-skills)
+ like Claude Code, you can use our [official skills](generate_with_ai/skills.md)
to automatically check for WebAssembly compatibility of your notebooks.
!!! tip "Sharing interactive previews of GitHub notebooks"
diff --git a/docs/vercel.json b/docs/vercel.json
index 0f399e8353..ab3290876f 100644
--- a/docs/vercel.json
+++ b/docs/vercel.json
@@ -715,19 +715,24 @@
"destination": "/guides/wasm/",
"permanent": true
},
+ {
+ "source": "/guides/generate_with_ai/text_to_notebook/",
+ "destination": "/cli/#marimo-new",
+ "permanent": true
+ },
{
"source": "/guides/generate_with_ai/prompts/",
- "destination": "/guides/generate_with_ai/customize_your_agent/",
+ "destination": "/guides/generate_with_ai/skills/",
"permanent": true
},
{
- "source": "/guides/generate_with_ai/skills/",
- "destination": "/guides/generate_with_ai/customize_your_agent/",
+ "source": "/guides/generate_with_ai/customize_your_agent/",
+ "destination": "/guides/generate_with_ai/skills/",
"permanent": true
},
{
"source": "/guides/generate_with_ai/using_claude_code/",
- "destination": "/guides/generate_with_ai/customize_your_agent/",
+ "destination": "/guides/generate_with_ai/skills/",
"permanent": true
},
{
diff --git a/frontend/src/components/editor/actions/__tests__/pair-with-agent-modal.test.tsx b/frontend/src/components/editor/actions/__tests__/pair-with-agent-modal.test.tsx
index 803703677a..44132f9082 100644
--- a/frontend/src/components/editor/actions/__tests__/pair-with-agent-modal.test.tsx
+++ b/frontend/src/components/editor/actions/__tests__/pair-with-agent-modal.test.tsx
@@ -82,7 +82,7 @@ describe("PairWithAgentModal", () => {
vi.unstubAllGlobals();
});
- it.each(["Claude", "Codex", "OpenCode", "Prompt"])(
+ it.each(["Claude", "Codex", "OpenCode", "Other Agents"])(
"targets the verified host Notebook in %s",
async (tab) => {
await act(async () => {
@@ -103,11 +103,13 @@ describe("PairWithAgentModal", () => {
panel.textContent?.includes("Agent connections require OpenCode 2.x"),
).toBe(tab === "OpenCode");
expect(panel).toHaveTextContent(
- tab === "Prompt" ? "1. Copy this prompt" : "1. Run in your terminal",
+ tab === "Other Agents"
+ ? "1. Copy this prompt"
+ : "1. Run in your terminal",
);
fireEvent.click(
within(panel).getByRole("button", {
- name: tab === "Prompt" ? "Copy prompt" : "Copy command",
+ name: tab === "Other Agents" ? "Copy prompt" : "Copy command",
}),
);
await waitFor(() => expect(copyToClipboard).toHaveBeenCalledOnce());
@@ -119,7 +121,7 @@ describe("PairWithAgentModal", () => {
},
);
- it.each(["Claude", "Prompt"])(
+ it.each(["Claude", "Other Agents"])(
"waits for kernel-ready before copying the %s target",
async (tab) => {
store.set(stableSessionIdAtom, null);
@@ -137,13 +139,13 @@ describe("PairWithAgentModal", () => {
expect(panel).toHaveTextContent("http://localhost:8000");
expect(
within(panel).getByRole("button", {
- name: tab === "Prompt" ? "Copy prompt" : "Copy command",
+ name: tab === "Other Agents" ? "Copy prompt" : "Copy command",
}),
).toBeDisabled();
},
);
- it.each(["Claude", "Codex", "OpenCode", "Prompt"])(
+ it.each(["Claude", "Codex", "OpenCode", "Other Agents"])(
"uses the editor CLI in %s when host is disabled",
async (tab) => {
store.set(pairConfigAtom, { ...PAIR_CONFIG, hostEnabled: false });
@@ -162,7 +164,7 @@ describe("PairWithAgentModal", () => {
expect(panel).not.toHaveTextContent("MARIMO_PAIR_NEXT");
fireEvent.click(
within(panel).getByRole("button", {
- name: tab === "Prompt" ? "Copy prompt" : "Copy command",
+ name: tab === "Other Agents" ? "Copy prompt" : "Copy command",
}),
);
await waitFor(() => expect(copyToClipboard).toHaveBeenCalledOnce());
@@ -185,7 +187,7 @@ describe("PairWithAgentModal", () => {
await act(async () => {
render(<PairWithAgentModal onClose={vi.fn()} />, { wrapper });
});
- fireEvent.mouseDown(screen.getByRole("tab", { name: "Prompt" }), {
+ fireEvent.mouseDown(screen.getByRole("tab", { name: "Other Agents" }), {
button: 0,
ctrlKey: false,
});
diff --git a/frontend/src/components/editor/actions/__tests__/pair-with-agent.test.tsx b/frontend/src/components/editor/actions/__tests__/pair-with-agent.test.tsx
index 9e8aeb912a..c977d821b3 100644
--- a/frontend/src/components/editor/actions/__tests__/pair-with-agent.test.tsx
+++ b/frontend/src/components/editor/actions/__tests__/pair-with-agent.test.tsx
@@ -75,9 +75,7 @@ describe("PairWithAgent", () => {
}),
);
- expect(
- screen.getByRole("dialog", { name: "Pair with an agent" }),
- ).toBeVisible();
+ expect(screen.getByRole("dialog", { name: "Pair an agent" })).toBeVisible();
});
it("opens the pairing dialog and preserves a passed click handler", () => {
@@ -88,9 +86,7 @@ describe("PairWithAgent", () => {
fireEvent.click(screen.getByRole("button", { name: "Connect your agent" }));
expect(onClick).toHaveBeenCalledOnce();
- expect(
- screen.getByRole("dialog", { name: "Pair with an agent" }),
- ).toBeVisible();
+ expect(screen.getByRole("dialog", { name: "Pair an agent" })).toBeVisible();
});
it("hides pairing controls in WASM", () => {
diff --git a/frontend/src/components/editor/actions/pair-with-agent-commands.ts b/frontend/src/components/editor/actions/pair-with-agent-commands.ts
index d80e7fe63b..e21001384e 100644
--- a/frontend/src/components/editor/actions/pair-with-agent-commands.ts
+++ b/frontend/src/components/editor/actions/pair-with-agent-commands.ts
@@ -14,7 +14,7 @@ export const AGENT_LABELS: Record<AgentTab, string> = {
claude: "Claude",
codex: "Codex",
opencode: "OpenCode",
- prompt: "Prompt",
+ prompt: "Other Agents",
};
/** How to invoke marimo: from the local checkout in dev, else via uvx. */
@@ -67,7 +67,7 @@ export function getTerminalCommand(
}
/**
- * The raw prompt for the "Prompt" tab. Mirrors the output of
+ * The raw prompt for the "Other Agents" tab. Mirrors the output of
* `marimo pair prompt` (see `marimo/_cli/pair/commands.py`) so pasting it into
* an agent behaves the same as the terminal commands.
*/
diff --git a/frontend/src/components/editor/actions/pair-with-agent-modal.tsx b/frontend/src/components/editor/actions/pair-with-agent-modal.tsx
index 704467b643..8f01b983d3 100644
--- a/frontend/src/components/editor/actions/pair-with-agent-modal.tsx
+++ b/frontend/src/components/editor/actions/pair-with-agent-modal.tsx
@@ -116,7 +116,7 @@ export const PairWithAgentModal: React.FC<{
return (
<DialogContent className="sm:max-w-2xl">
<DialogHeader>
- <DialogTitle>Pair with an agent</DialogTitle>
+ <DialogTitle>Pair an agent</DialogTitle>
<DialogDescription>
Use an AI coding agent to pair-program on this notebook.{" "}
<a
diff --git a/frontend/src/components/editor/actions/useNotebookActions.tsx b/frontend/src/components/editor/actions/useNotebookActions.tsx
index a84d599a22..5215b4568f 100644
--- a/frontend/src/components/editor/actions/useNotebookActions.tsx
+++ b/frontend/src/components/editor/actions/useNotebookActions.tsx
@@ -301,7 +301,7 @@ export function useNotebookActions({
{
icon: <SparklesIcon size={14} strokeWidth={1.5} />,
- label: "Connect your agent",
+ label: "Pair an agent",
hidden: isWasm(),
handle: async () => {
openModal(<PairWithAgentModal onClose={closeModal} />);
diff --git a/mkdocs.yml b/mkdocs.yml
index da0e2a449a..f5ed109bf0 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -110,10 +110,9 @@ nav:
- Importing local code: guides/package_management/importing_local_code.md
- Generate with AI:
- Generate with AI: guides/generate_with_ai/index.md
- - Pair with agents via marimo pair: guides/generate_with_ai/marimo_pair.md
- - Customize your agent: guides/generate_with_ai/customize_your_agent.md
- - The editor's AI assistant: guides/editor_features/ai_completion.md
- - Generate notebooks with marimo new: guides/generate_with_ai/text_to_notebook.md
+ - Use agents with marimo pair: guides/generate_with_ai/marimo_pair.md
+ - In-editor AI assistance: guides/editor_features/ai_completion.md
+ - Skills: guides/generate_with_ai/skills.md
- Editor features:
- Editor features: guides/editor_features/index.md
- Editor overview: guides/editor_features/overview.md