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
Add "using claude code" section (#7687)
vincent d warmerdam0d106b5386e8
diff --git a/docs/guides/generate_with_ai/index.md b/docs/guides/generate_with_ai/index.mdindex b2e579fd4c..9276a96c69 100644--- a/docs/guides/generate_with_ai/index.md+++ b/docs/guides/generate_with_ai/index.md@@ -5,3 +5,4 @@| [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 || [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 |diff --git a/docs/guides/generate_with_ai/prompts.md b/docs/guides/generate_with_ai/prompts.mdindex 5403f22d04..da6e737f39 100644--- a/docs/guides/generate_with_ai/prompts.md+++ b/docs/guides/generate_with_ai/prompts.md@@ -2,11 +2,11 @@ marimo offers many tools for [AI assisted coding](../editor_features/ai_completiYou 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.-## CLAUDE.md+## AGENTS.md and CLAUDE.md-You can run [claude code](https://www.anthropic.com/claude-code) 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 claude makes a change.+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 claude code, you might want to take the snippet below as starting context for your `CLAUDE.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.+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.```consolecurl https://docs.marimo.io/CLAUDE.md > CLAUDE.mddiff --git a/docs/guides/generate_with_ai/using_claude_code.md b/docs/guides/generate_with_ai/using_claude_code.mdnew file mode 100644index 0000000000..afaad3909e--- /dev/null+++ b/docs/guides/generate_with_ai/using_claude_code.md@@ -0,0 +1,170 @@+Claude lets you customise the marimo editing experience with it's 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/#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 it's 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/#marimo-check), every single time a marimo notebook is changed. Our default [`CLAUDE.md`](../../generate_with_ai/prompts/#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+#!/bin/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/mkdocs.yml b/mkdocs.ymlindex 35729f487a..6434875e9a 100644--- a/mkdocs.yml+++ b/mkdocs.yml@@ -110,6 +110,7 @@ nav:- 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- Editor features:- Editor features: guides/editor_features/index.md- Editor overview: guides/editor_features/overview.md