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.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
docs: consolidate AI guides and route readers to marimo pair (#10293)
Akshay Agrawalc21a67f8e360
diff --git a/docs/api/inputs/anywidget.md b/docs/api/inputs/anywidget.mdindex 5e92e397d8..b6543a67df 100644--- a/docs/api/inputs/anywidget.md+++ b/docs/api/inputs/anywidget.md@@ -94,7 +94,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 you can check out our [prompts section](../../guides/generate_with_ai/prompts.md#anywidget) for a quickstart.+- 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.- 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/examples/index.md b/docs/examples/index.mdindex 26d39a6cd0..0a477a4321 100644--- a/docs/examples/index.md+++ b/docs/examples/index.md@@ -117,13 +117,13 @@ the [dataframes guide](../guides/working_with_data/dataframes.md) for details.---- <a href="api/inputs/data_editor"><img src="/_static/example-thumbs/editable_dataframes.png" /></a>+ <a href="../api/inputs/data_editor"><img src="/_static/example-thumbs/editable_dataframes.png" /></a>- 🛠️ [**Interactive dataframe transformer**](../api/inputs/dataframe.md)---- <a href="api/inputs/dataframe"><img src="/_static/example-thumbs/dataframe_transformer.png" /></a>+ <a href="../api/inputs/dataframe"><img src="/_static/example-thumbs/dataframe_transformer.png" /></a></div>@@ -157,7 +157,7 @@ overview.---- <a href="../guides/working_with_data/plotting#Plotly"><img src="/_static/example-thumbs/plotly.png" /></a>+ <a href="../guides/working_with_data/plotting#plotly"><img src="/_static/example-thumbs/plotly.png" /></a>- 🔭 [**Showing matplotlib plots**](outputs/plots.md)@@ -190,7 +190,7 @@ overview.---- <a href="outputs/stacks.md"><img src="/_static/example-thumbs/stacks.png" /></a>+ <a href="outputs/stacks"><img src="/_static/example-thumbs/stacks.png" /></a>- 📁 [**Accordion toggle**](../api/layouts/accordion.md)@@ -221,85 +221,85 @@ guide](../guides/interactivity.md) for rules governing how UI elements work.---- <a href="../api/inputs/slider.md"><img src="/_static/example-thumbs/slider.png" /></a>+ <a href="../api/inputs/slider"><img src="/_static/example-thumbs/slider.png" /></a>- 🧾 [**Dropdown**](../api/inputs/dropdown.md)---- <a href="../api/inputs/dropdown.md"><img src="/_static/example-thumbs/dropdown.png" /></a>+ <a href="../api/inputs/dropdown"><img src="/_static/example-thumbs/dropdown.png" /></a>- 👆 [**Multi-select**](../api/inputs/multiselect.md)---- <a href="../api/inputs/multiselect.md"><img src="/_static/example-thumbs/multiselect.png" /></a>+ <a href="../api/inputs/multiselect"><img src="/_static/example-thumbs/multiselect.png" /></a>- 🔘 [**Radio buttons**](../api/inputs/radio.md)---- <a href="../api/inputs/radio.md"><img src="/_static/example-thumbs/radio.png" /></a>+ <a href="../api/inputs/radio"><img src="/_static/example-thumbs/radio.png" /></a>- ☑️ [**Checkbox**](../api/inputs/checkbox.md)---- <a href="../api/inputs/checkbox.md"><img src="/_static/example-thumbs/checkbox.png" /></a>+ <a href="../api/inputs/checkbox"><img src="/_static/example-thumbs/checkbox.png" /></a>- 📅 [**Date**](../api/inputs/dates.md)---- <a href="../api/inputs/date.md"><img src="/_static/example-thumbs/date.png" /></a>+ <a href="../api/inputs/dates"><img src="/_static/example-thumbs/date.png" /></a>- 📁 [**File**](../api/inputs/file.md)---- <a href="../api/inputs/file.md"><img src="/_static/example-thumbs/file_upload.png" /></a>+ <a href="../api/inputs/file"><img src="/_static/example-thumbs/file_upload.png" /></a>- 🔤 [**Text input**](../api/inputs/text.md)---- <a href="../api/inputs/text.md"><img src="/_static/example-thumbs/text.png" /></a>+ <a href="../api/inputs/text"><img src="/_static/example-thumbs/text.png" /></a>- 📝 [**Text area**](../api/inputs/text_area.md)---- <a href="../api/inputs/text_area.md"><img src="/_static/example-thumbs/text_area.png" /></a>+ <a href="../api/inputs/text_area"><img src="/_static/example-thumbs/text_area.png" /></a>- 🧑💻 [**Code editor**](../api/inputs/code_editor.md)---- <a href="../api/inputs/code_editor.md"><img src="/_static/example-thumbs/code_editor.png" /></a>+ <a href="../api/inputs/code_editor"><img src="/_static/example-thumbs/code_editor.png" /></a>- 🔍 [**Table**](../api/inputs/table.md)---- <a href="../api/inputs/table.md"><img src="/_static/example-thumbs/tables.png" /></a>+ <a href="../api/inputs/table"><img src="/_static/example-thumbs/tables.png" /></a>- 🎙️ [**Microphone**](../api/inputs/microphone.md)---- <a href="../api/inputs/microphone.md"><img src="/_static/example-thumbs/microphone.png" /></a>+ <a href="../api/inputs/microphone"><img src="/_static/example-thumbs/microphone.png" /></a>- 💬 [**Chat**](../api/inputs/chat.md)---- <a href="../api/inputs/chat.md"><img src="/_static/example-thumbs/chat.png" /></a>+ <a href="../api/inputs/chat"><img src="/_static/example-thumbs/chat.png" /></a>- 🔢 [**Matrix**](../api/inputs/matrix.md)---- <a href="../api/inputs/matrix.md"><img src="/_static/example-thumbs/matrix.png" /></a>+ <a href="../api/inputs/matrix"><img src="/_static/example-thumbs/matrix.png" /></a></div>@@ -314,18 +314,18 @@ other UI elements.---- <a href="../api/inputs/form.md"><img src="/_static/example-thumbs/form.png" /></a>+ <a href="../api/inputs/form"><img src="/_static/example-thumbs/form.png" /></a>- 🎒 [**Array**](../api/inputs/array.md)---- <a href="../api/inputs/array.md"><img src="/_static/example-thumbs/array.png" /></a>+ <a href="../api/inputs/array"><img src="/_static/example-thumbs/array.png" /></a>- 📖 [**Dictionary**](../api/inputs/dictionary.md)---- <a href="../api/inputs/dictionary.md"><img src="/_static/example-thumbs/dictionary.png" /></a>+ <a href="../api/inputs/dictionary"><img src="/_static/example-thumbs/dictionary.png" /></a></div>diff --git a/docs/guides/editor_features/agents.md b/docs/guides/editor_features/agents.mdindex 0b84f1e1ea..c723f987ba 100644--- a/docs/guides/editor_features/agents.md+++ b/docs/guides/editor_features/agents.md@@ -3,6 +3,12 @@!!! warning "Experimental Feature"Agents are currently experimental and under active development. Features and APIs may change.+!!! tip "Looking to pair an agent CLI with your notebook?"+ Most users should start with [marimo pair](../generate_with_ai/marimo_pair.md),+ which gives agent CLIs like Claude Code full access to your running notebook+ from the terminal. The integration described on this page instead embeds an+ agent inside the marimo editor's chat panel.+marimo supports external AI agents that can interact with your codebase through the [Agent Client Protocol](https://agentclientprotocol.com/) (ACP). Agents can read and write marimo notebooks, helping you with coding tasks directly from the chat panel.<video autoplay muted loop playsinline width="100%" height="100%" align="center">diff --git a/docs/guides/editor_features/ai_completion.md b/docs/guides/editor_features/ai_completion.mdindex 2615662c3a..887cea31f3 100644--- a/docs/guides/editor_features/ai_completion.md+++ b/docs/guides/editor_features/ai_completion.md@@ -1,5 +1,14 @@# AI-assisted coding+!!! tip "Using an agent CLI like Claude Code? Try marimo pair"++ 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.+marimo is an AI-native editor, with support for full-cell AI code generation:* generating new cells from a prompt@@ -79,7 +88,7 @@ button to add entirely new cells to your notebook.#### Chat panelThe chat panel on the left sidebar lets you chat with an LLM and ask questions-aboutyour notebook. The LLM can also generate code cells that you can insert+about your notebook. The LLM can also generate code cells that you can insertinto your notebook.The chat panel currently supports the following modes:@@ -168,10 +177,11 @@ You can still collaborate with an AI agent using [marimo pair](../generate_with_## Agents-!!! example "Experimental: Agents"+!!! example "Experimental: Agents panel"- marimo also supports external AI agents like Claude Code, Codex, and Gemini CLI that can interact with your notebooks.- Learn more in the [agents](agents.md) guide.+ 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@@ -196,7 +206,7 @@ an AI pair programmer, similar to VS Code:</figure></div>-_GitHUb Copilot is not yet available in our conda distribution; please install+_GitHub Copilot is not yet available in our conda distribution; please installmarimo using `pip`/`uv` if you need Copilot._#### Advanced configurationdiff --git a/docs/guides/editor_features/mcp.md b/docs/guides/editor_features/mcp.mdindex a0859b24e6..7bd286d10e 100644--- a/docs/guides/editor_features/mcp.md+++ b/docs/guides/editor_features/mcp.md@@ -36,7 +36,7 @@ marimo edit notebook.py --mcp --no-token## MCP Server-marimo can expose its [AI tools](tools.md) through an MCP server endpoint, allowing external AI applications to interact with your notebooks.+marimo can expose its [AI tools](tools.md) through an MCP server endpoint, allowing external AI applications to interact with your notebooks. If your goal is to have a coding agent drive a live notebook, see [marimo pair](../generate_with_ai/marimo_pair.md) instead; the MCP server exposes lower-level, read-only tools.<video autoplay loop muted playsinline width="100%" height="100%" align="center"><source src="/_static/docs-mcp-server.mp4" type="video/mp4">diff --git a/docs/guides/generate_with_ai/customize_your_agent.md b/docs/guides/generate_with_ai/customize_your_agent.mdnew file mode 100644index 0000000000..748a2c0e8d--- /dev/null+++ b/docs/guides/generate_with_ai/customize_your_agent.md@@ -0,0 +1,185 @@+---+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.mdindex 2365eb0ad5..ef1920a0bc 100644--- a/docs/guides/generate_with_ai/index.md+++ b/docs/guides/generate_with_ai/index.md@@ -1,10 +1,35 @@+---+description: "Three ways to use AI with marimo: pair coding agents with running notebooks, generate cells in the editor, and create notebooks from prompts."+---+# Generate notebooks with AI+There are three 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 the marimo editor's built-in assistant.** The marimo editor comes with+[AI-assisted coding](../editor_features/ai_completion.md): a chat panel,+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).+| Guide | Description ||-------|-------------|-| [Using agent CLIs](marimo_pair.md) | Collaborate on notebooks with agents using marimo pair |-| [Skills](skills.md) | Skills for coding agents |-| [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 |-| [Generate notebooks with marimo new](text_to_notebook.md) | Generate entire notebooks with AI |+| [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).diff --git a/docs/guides/generate_with_ai/marimo_pair.md b/docs/guides/generate_with_ai/marimo_pair.mdindex 52dbd29a98..4cd90a561a 100644--- a/docs/guides/generate_with_ai/marimo_pair.md+++ b/docs/guides/generate_with_ai/marimo_pair.md@@ -41,11 +41,11 @@ Then pair on your first notebook by pasting the following in your agent CLI:/marimo-pair pair with me on my_notebook.py```-## Sandbox with molab+## Cloud sandbox with molab-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.+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.-To connect an agent, start a notebook on molab and open the actions panel in the upper right corner. From this menu you need to click "Pair with an agent".+To connect an agent, start a notebook on molab and open the actions panel in the upper right corner. From this menu you need to click "Pair with an agent".<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"/>diff --git a/docs/guides/generate_with_ai/prompts.md b/docs/guides/generate_with_ai/prompts.mddeleted file mode 100644index da6e737f39..0000000000--- a/docs/guides/generate_with_ai/prompts.md+++ /dev/null@@ -1,67 +0,0 @@-marimo offers many tools for [AI assisted coding](../editor_features/ai_completion.md). However, sometimes you may want to do something more custom and could benefit from a prompt template to get started from. The goal of this page is to share prompts that have proven to be useful and will help you get started on specific tasks.--You can add these prompts to your [custom rules](../editor_features/ai_completion.md#custom-rules) but be mindful that doing so will make every call to the LLM more expensive because you're feeding it more tokens. That's why we generally recommend to start your conversations with these snippets if you don't plan on using them very often.--## AGENTS.md and CLAUDE.md--You can run tools like [claude code](https://www.anthropic.com/claude-code) or [codex](https://openai.com/codex/) in the terminal and ask it to edit a marimo notebook on your behalf. Make sure that you run your notebook with the [watch flag](../../api/watch.md) turned on, like `marimo edit --watch notebook.py`, to see updates appear live whenever the agent makes a change.--To help your agent, you might want to take the snippet below as starting context for your `CLAUDE.md`/`AGENTS.md` file. This snippet should be seen as a starting point and we recommend adding extra context yourself. Things like "prefer polars over pandas" to indicate your preferred libraries and tools.--```console-curl https://docs.marimo.io/CLAUDE.md > CLAUDE.md-```--/// details | Example CLAUDE.md file--```markdown---8<-- "docs/_static/CLAUDE.md"-```--///--## Anywidget--If you want to generate [custom UIs or widgets for marimo](../../api/inputs/anywidget.md?#building-custom-ui-elements) then anywidget is the way to go. Because anywidget is a fairly recent project, LLMs have been known to hallucinate when you try to generate custom widgets from scratch. The following prompt contains an example that helps prevent this behaviour and it also points out common failure scenarios that the LLM should avoid.--```-When writing an anywidget use vanilla javascript in `_esm` and do not forget about `_css`. The css should look bespoke in light mode and dark mode. Keep the css small unless explicitly asked to go the extra mile. When you display the widget it must be wrapped via `widget = mo.ui.anywidget(OriginalAnywidget())`.--<example title="Example anywidget implementation">-import anywidget-import traitlets---class CounterWidget(anywidget.AnyWidget):- _esm = """- // Define the main render function- function render({ model, el }) {- let count = () => model.get("number");- let btn = document.createElement("button");- btn.innerHTML = `count is ${count()}`;- btn.addEventListener("click", () => {- model.set("number", count() + 1);- model.save_changes();- });- model.on("change:number", () => {- btn.innerHTML = `count is ${count()}`;- });- el.appendChild(btn);- }- // Important! We must export at the bottom here!- export default { render };- """- _css = """button{- font-size: 14px;- }"""- number = traitlets.Int(0).tag(sync=True)--widget = mo.ui.anywidget(CounterWidget())-widget--# Grabbing the widget from another cell, `.value` is a dictionary.-print(widget.value["number"])-</example>--When sharing the anywidget, keep the example minimal. No need to combine it with marimo ui elements unless explicitly stated to do so.-```diff --git a/docs/guides/generate_with_ai/skills.md b/docs/guides/generate_with_ai/skills.mddeleted file mode 100644index 1210b71a5e..0000000000--- a/docs/guides/generate_with_ai/skills.md+++ /dev/null@@ -1,38 +0,0 @@-# 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.--**Feedback.** We welcome feedback at our [GitHub repository](https://github.com/marimo-team/skills/issues).--!!! tip "Watching for changes to notebooks on disk"-- When using marimo with Claude Code, configure the marimo editor to- automatically reload when Claude edits your notebook 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).--## What are skills?--Skills are folders of instructions, scripts, and resources that Claude and-other agents load dynamically to improve performance on specialized-tasks.--To learn more about skills, check out:--- [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)-- [skills.sh](https://skills.sh/)diff --git a/docs/guides/generate_with_ai/text_to_notebook.md b/docs/guides/generate_with_ai/text_to_notebook.mdindex 945f7d5f60..fda97ac9f4 100644--- a/docs/guides/generate_with_ai/text_to_notebook.md+++ b/docs/guides/generate_with_ai/text_to_notebook.md@@ -6,7 +6,7 @@ notebooks using an LLM.For example, type```bash-marimo new "Plot an interactive 3D surface with matplotlib."+marimo new "Plot an interactive 3D surface with matplotlib."```to open a freshly generated notebook in your browser.@@ -24,4 +24,10 @@ 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.)-- [Visualize sorting algorithms](https://marimo.app/ai?q=Plot+an+interesting+3D+surface+with+matplotlib.+Include+an+interactive+element+to+control+the+shape+of+the+surface.)+- [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/generate_with_ai/using_claude_code.md b/docs/guides/generate_with_ai/using_claude_code.mddeleted file mode 100644index 4cf9c854ff..0000000000--- a/docs/guides/generate_with_ai/using_claude_code.md+++ /dev/null@@ -1,177 +0,0 @@-!!! 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--[Slash Commands](https://code.claude.com/docs/en/slash-commands) allow you to predefine specific prompts that you can refer to during a conversation with Claude. You 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).--### Skills--[Skills](https://code.claude.com/docs/en/skills#agent-skills) are similar to commands, but you don't trigger them manually. You define them and then let Claude use them when it thinks they're relevant. You store these skills either in the `~/.claude/skills/` personal folder or in the `.claude/skills/` local folder of the project.--As an example, this is what the a skill might look like:--```md-----name: anywidget-generator-description: Generate anywidget components for marimo notebooks.------When writing an anywidget use vanilla javascript in `_esm` and do not forget about `_css`. The css should look bespoke in light mode and dark mode. Keep the css small unless explicitly asked to go the extra mile. When you display the widget it must be wrapped via `widget = mo.ui.anywidget(OriginalAnywidget())`.--<example title="Example anywidget implementation">-import anywidget-import traitlets---class CounterWidget(anywidget.AnyWidget):- _esm = """- // Define the main render function- function render({ model, el }) {- let count = () => model.get("number");- let btn = document.createElement("button");- btn.innerHTML = `count is ${count()}`;- btn.addEventListener("click", () => {- model.set("number", count() + 1);- model.save_changes();- });- model.on("change:number", () => {- btn.innerHTML = `count is ${count()}`;- });- el.appendChild(btn);- }- // Important! We must export at the bottom here!- export default { render };- """- _css = """button{- font-size: 14px;- }"""- number = traitlets.Int(0).tag(sync=True)--widget = mo.ui.anywidget(CounterWidget())-widget--# Grabbing the widget from another cell, `.value` is a dictionary.-print(widget.value["number"])-</example>--When sharing the anywidget, keep the example minimal. No need to combine it with marimo ui elements unless explicitly stated to do so.-```--You would store this file in a path like `~/.claude/skills/anywidget-generator/SKILL.md`. The frontmatter gives the LLM just enough context to know when to trigger it and will only read the full prompt when it's needed.--You can also choose to expand these skills by referring to a script that it can run, to learn more about that check the [multi-file documentation](https://code.claude.com/docs/en/skills#example:-multi-file-skill-structure).--### Hooks--[Hooks](https://code.claude.com/docs/en/hooks) allow you to automatically run scripts when Claude 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. Our default [`CLAUDE.md`](prompts.md#agentsmd-and-claudemd) file already points out to the LLM that it should run the `marimo check` command but hooks offer the most robust mechanism to enforce this behavior.--To configure a hook, you can 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.--```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 block on 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 blocks and shows error to Claude- 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/wasm.md b/docs/guides/wasm.mdindex 375ba59ab6..f99bdfdcbb 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/skills.md)+ like Claude Code, you can use our [official skills](generate_with_ai/customize_your_agent.md#official-marimo-skills)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.jsonindex c25c15c9d2..8342af3fe7 100644--- a/docs/vercel.json+++ b/docs/vercel.json@@ -695,6 +695,21 @@"destination": "/guides/wasm/","permanent": true},+ {+ "source": "/guides/generate_with_ai/prompts/",+ "destination": "/guides/generate_with_ai/customize_your_agent/",+ "permanent": true+ },+ {+ "source": "/guides/generate_with_ai/skills/",+ "destination": "/guides/generate_with_ai/customize_your_agent/",+ "permanent": true+ },+ {+ "source": "/guides/generate_with_ai/using_claude_code/",+ "destination": "/guides/generate_with_ai/customize_your_agent/",+ "permanent": true+ },{"source": "/:path*.html","destination": "/:path*/",diff --git a/mkdocs.yml b/mkdocs.ymlindex 7f60793618..65831464ce 100644--- a/mkdocs.yml+++ b/mkdocs.yml@@ -111,11 +111,9 @@ 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- - 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+ - 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- Editor features:- Editor features: guides/editor_features/index.md@@ -125,7 +123,6 @@ nav:- Understanding dataflow: guides/editor_features/dataflow.md- Module autoreloading: guides/editor_features/module_autoreloading.md- Hotkeys: guides/editor_features/hotkeys.md- - AI completion: guides/editor_features/ai_completion.md- Model Context Protocol: guides/editor_features/mcp.md- AI tools: guides/editor_features/tools.md- Agents: guides/editor_features/agents.md@@ -391,6 +388,9 @@ theme:font:code: Fira Monotext: PT Sans+ icon:+ admonition:+ tip: material/lightbulb-outlinelogo: _static/marimo-logotype-horizontal.pngname: materialpalette: