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: Agents docs and feature flag (#6409)

Myles Scolnick3d32c675fa50
diff --git a/docs/_static/docs-claude-code-agent.mp4 b/docs/_static/docs-claude-code-agent.mp4
new file mode 100644
index 0000000000..a44667a2c6
Binary files /dev/null and b/docs/_static/docs-claude-code-agent.mp4 differ
diff --git a/docs/guides/editor_features/agents.md b/docs/guides/editor_features/agents.md
new file mode 100644
index 0000000000..2eb68e8d02
--- /dev/null
+++ b/docs/guides/editor_features/agents.md
@@ -0,0 +1,72 @@
+# Agents
+
+!!! warning "Experimental Feature"
+ Agents are currently experimental and under active development. Features and APIs may change.
+
+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">
+ <source src="/_static/docs-claude-code-agent.mp4" type="video/mp4">
+</video>
+
+## Supported agents
+
+marimo currently supports the following agents:
+
+### Claude Code Agent
+
+Claude Code Agent that uses your [Claude Code CLI subscription](https://docs.claude.com/en/docs/claude-code/overview) to help you with coding tasks.
+
+**Installation and login:**
+
+```bash
+# Install
+npm install -g @anthropic-ai/claude-code
+# Login
+claude
+# Then type /login
+```
+
+**Connection command:**
+
+```bash
+npx stdio-to-ws "npx @zed-industries/claude-code-acp" --port 3017
+```
+
+### Gemini Agent
+
+Google's Gemini agent offers a limited free tier and login for more advanced features.
+
+See login and authentication instructions in the [Gemini CLI documentation](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#-authentication-options).
+
+**Connection command:**
+
+```bash
+npx stdio-to-ws "npx @google/gemini-cli --experimental-acp" --port 3019
+```
+
+## Connecting to an agent
+
+1. **Start the agent server**: Run the connection command for your chosen agent in a terminal
+2. **Enable the feature flag**: Enable the feature flag under the "Lab" section in the settings menu
+3. **Open the agent panel**: Click the agents icon in marimo's sidebar
+4. **Select your agent**: Choose the agent from the dropdown menu
+5. **Start chatting**: The agent can now read and modify your notebooks
+
+!!! tip "Terminal integration"
+
+ If you have terminal access enabled in marimo, you can run agent connection commands directly from the agent panel using the terminal button.
+
+## Custom agents
+
+!!! info "Custom agents"
+
+ Support for custom agents is coming soon. This will allow you to connect to your own ACP-compatible agents
+
+## Troubleshooting
+
+**Connection issues**: Ensure the agent server is running on the correct port before connecting in marimo.
+
+**Permission requests**: Agents may request permission to read or write files. Review these carefully before approving.
+
+**Session limits**: Currently, only one session per agent is supported for optimal performance.
diff --git a/docs/guides/editor_features/ai_completion.md b/docs/guides/editor_features/ai_completion.md
index 45cb063563..ca3b6911fa 100644
--- a/docs/guides/editor_features/ai_completion.md
+++ b/docs/guides/editor_features/ai_completion.md
@@ -368,7 +368,7 @@ marimo supports OpenAI's API by default. Many providers offer OpenAI API-compati
2. Navigate to the AI section
3. Enter your provider's API key in the "OpenAI API Key" field
4. Under AI Assist settings:
-
+
- Set Base URL to your provider's endpoint (e.g., `https://api.deepseek.com`)
- Set Model to your chosen model (e.g., `deepseek-chat` or `deepseek-reasoner`)
@@ -389,6 +389,13 @@ For a comprehensive list of compatible providers and their configurations, pleas
For providers not compatible with OpenAI's API, please submit a [feature request](https://github.com/marimo-team/marimo/issues/new?template=feature_request.yaml) or "thumbs up" an existing one.
+## Agents
+
+!!! example "Experimental: Agents"
+
+ marimo also supports external AI agents like Claude Code and Gemini CLI that can interact with your notebooks.
+ Learn more in the [agents](agents.md) guide.
+
## Copilots
### GitHub Copilot
diff --git a/frontend/src/components/app-config/user-config-form.tsx b/frontend/src/components/app-config/user-config-form.tsx
index f344fbe155..4649db87d7 100644
--- a/frontend/src/components/app-config/user-config-form.tsx
+++ b/frontend/src/components/app-config/user-config-form.tsx
@@ -1283,6 +1283,38 @@ export const UserConfigForm: React.FC = () => {
</div>
)}
/>
+ <FormField
+ control={form.control}
+ name="experimental.external_agents"
+ render={({ field }) => (
+ <div className="flex flex-col gap-y-1">
+ <FormItem className={formItemClasses}>
+ <FormLabel className="font-normal">
+ External Agents
+ </FormLabel>
+ <FormControl>
+ <Checkbox
+ data-testid="external-agents-checkbox"
+ checked={field.value === true}
+ onCheckedChange={field.onChange}
+ />
+ </FormControl>
+ </FormItem>
+ <IsOverridden
+ userConfig={config}
+ name="experimental.external_agents"
+ />
+ <FormDescription>
+ Enable experimental external agents such as Claude Code and
+ Gemini CLI. Learn more in the{" "}
+ <ExternalLink href="https://docs.marimo.io/guides/editor_features/agents/">
+ docs
+ </ExternalLink>
+ .
+ </FormDescription>
+ </div>
+ )}
+ />
</SettingGroup>
);
}
diff --git a/mkdocs.yml b/mkdocs.yml
index f14b1a50fb..9714d247f3 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -127,6 +127,7 @@ nav:
- Editor overview: guides/editor_features/overview.md
- Understanding dataflow: guides/editor_features/dataflow.md
- AI completion: guides/editor_features/ai_completion.md
+ - Agents: guides/editor_features/agents.md
- Language Server: guides/editor_features/language_server.md
- Package management: guides/editor_features/package_management.md
- Module autoreloading: guides/editor_features/module_autoreloading.md