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.

feat(ai): experimental in-notebook code mode (#9956)

Shahmir Varqha95ecfca656c8
diff --git a/frontend/src/components/chat/chat-panel.tsx b/frontend/src/components/chat/chat-panel.tsx
index 95a7d9388b..70bbd86b30 100644
--- a/frontend/src/components/chat/chat-panel.tsx
+++ b/frontend/src/components/chat/chat-panel.tsx
@@ -23,6 +23,7 @@ import {
PlusIcon,
SparklesIcon,
SettingsIcon,
+ CodeIcon,
} from "lucide-react";
import { memo, useEffect, useRef, useState } from "react";
import useEvent from "react-use-event-hook";
@@ -268,24 +269,32 @@ const ChatInputFooter: React.FC<ChatInputFooterProps> = memo(
{
value: "ask",
label: "Ask",
- subtitle:
- "Use AI with access to read-only tools like documentation search",
+ subtitle: "AI with access to read-only tools like documentation search",
Icon: NotebookText,
},
{
value: "agent",
- label: "Agent (beta)",
- subtitle: "Use AI with access to read and write tools",
+ label: "Agent",
+ subtitle: "AI with access to read and write tools",
Icon: HatGlasses,
},
];
+ if (import.meta.env.DEV) {
+ modeOptions.push({
+ value: "code_mode",
+ label: "Code Mode (experimental)",
+ subtitle: "AI with access to the notebook's kernel. Use with caution.",
+ Icon: CodeIcon,
+ });
+ }
+
const isAttachmentSupported =
PROVIDERS_THAT_SUPPORT_ATTACHMENTS.has(currentProvider);
- const CurrentModeIcon = modeOptions.find(
- (o) => o.value === currentMode,
- )?.Icon;
+ const currentModeOption = modeOptions.find((o) => o.value === currentMode);
+ const CurrentModeIcon = currentModeOption?.Icon;
+ const CurrentModeLabel = currentModeOption?.label;
return (
<TooltipProvider>
@@ -294,7 +303,7 @@ const ChatInputFooter: React.FC<ChatInputFooterProps> = memo(
<Select value={currentMode} onValueChange={saveModeChange}>
<SelectTrigger className="h-6 text-xs border-border shadow-none! ring-0! bg-muted hover:bg-muted/30 py-0 px-2 gap-1.5">
{CurrentModeIcon && <CurrentModeIcon className="h-3 w-3" />}
- <span className="capitalize">{currentMode}</span>
+ <span>{CurrentModeLabel}</span>
</SelectTrigger>
<SelectContent>
<SelectGroup>
diff --git a/frontend/src/core/config/config-schema.ts b/frontend/src/core/config/config-schema.ts
index 7274dd9b63..a9dba1c12e 100644
--- a/frontend/src/core/config/config-schema.ts
+++ b/frontend/src/core/config/config-schema.ts
@@ -45,7 +45,12 @@ export const DEFAULT_AI_MODEL = "openai/gpt-4o";
const AUTO_DOWNLOAD_FORMATS = ["html", "markdown", "ipynb"] as const;
export type CopilotMode = NonNullable<schemas["AiConfig"]["mode"]>;
-export const COPILOT_MODES: CopilotMode[] = ["manual", "ask", "agent"];
+export const COPILOT_MODES: CopilotMode[] = [
+ "manual",
+ "ask",
+ "agent",
+ "code_mode",
+];
const AiConfigSchema = z
.object({
diff --git a/marimo/_config/config.py b/marimo/_config/config.py
index 9c394a2b3e..2e8cdcfee7 100644
--- a/marimo/_config/config.py
+++ b/marimo/_config/config.py
@@ -267,7 +267,7 @@ class PackageManagementConfig(TypedDict):
manager: Literal["pip", "rye", "uv", "poetry", "pixi"]
-CopilotMode = Literal["ask", "manual", "agent"]
+CopilotMode = Literal["ask", "manual", "agent", "code_mode"]
@mddoc
diff --git a/marimo/_server/ai/prompts.py b/marimo/_server/ai/prompts.py
index a79f56e68c..0376060cb2 100644
--- a/marimo/_server/ai/prompts.py
+++ b/marimo/_server/ai/prompts.py
@@ -2,6 +2,7 @@
from __future__ import annotations
from marimo._config.config import CopilotMode
+from marimo._server.ai.skills.utils import load_skill
from marimo._server.models.completion import (
AiCompletionContext,
Language,
@@ -45,6 +46,14 @@ language_rules_multiple_cells: dict[Language, list[str]] = {
}
+def format_context(context: AiCompletionContext) -> str:
+ return (
+ _format_plain_text(context.plain_text)
+ + _format_variables(context.variables)
+ + _format_schema_info(context.schema)
+ )
+
+
def _format_schema_info(tables: list[SchemaTable] | None) -> str:
"""Helper to format schema information from context"""
if not tables:
@@ -195,9 +204,7 @@ def get_refactor_or_insert_notebook_cell_system_prompt(
system_prompt += f"\n\n## Additional rules:\n{custom_rules}"
if context:
- system_prompt += _format_plain_text(context.plain_text)
- system_prompt += _format_variables(context.variables)
- system_prompt += _format_schema_info(context.schema)
+ system_prompt += format_context(context)
if other_cell_codes:
system_prompt += "\n\n" + _tag(
@@ -263,6 +270,11 @@ def _get_mode_intro_message(mode: CopilotMode) -> str:
"## Limitations\n"
"- You must always explain to the user why you are using a tool before invoking it.\n"
)
+ elif mode == "code_mode":
+ return (
+ f"{base_intro}"
+ "You are in code mode - you have access to the notebook's kernel and can execute code."
+ )
def _get_session_info(session_id: SessionId) -> str:
@@ -272,19 +284,50 @@ def _get_session_info(session_id: SessionId) -> str:
)
-def get_chat_system_prompt(
+def _single_cell_language_rules() -> str:
+ """Per-language rules for chat modes that emit one cell at a time."""
+ out = ""
+ for language in language_rules:
+ if not language_rules[language]:
+ continue
+ out += (
+ f"\n\n## Rules for {language}:\n{_rules(language_rules[language])}"
+ )
+ return out
+
+
+def _multi_cell_language_rules() -> str:
+ """Per-language rules for agent mode, which can insert multiple cells."""
+ out = ""
+ for lang in LANGUAGES:
+ rules = language_rules_multiple_cells.get(
+ lang, language_rules.get(lang, [])
+ )
+ if rules:
+ out += f"\n\n## Rules for {lang}:\n{_rules(rules)}"
+ return out
+
+
+def _common_chat_sections(
*,
custom_rules: str | None,
- context: AiCompletionContext | None,
include_other_code: str,
- mode: CopilotMode,
- session_id: SessionId,
+ context: AiCompletionContext | None,
) -> str:
- system_prompt: str = f"""
-{_get_mode_intro_message(mode)}
-{_get_session_info(session_id)}
+ """Trailing sections shared by every chat mode."""
+ out = ""
+ if custom_rules and custom_rules.strip():
+ out += f"\n\n## Additional rules:\n{custom_rules}"
+ if include_other_code:
+ out += "\n\n" + _tag("code_from_other_cells", include_other_code)
+ if context:
+ out += format_context(context)
+ return out
-Your goal is to do one of the following two things:
+
+# Static guide describing marimo's reactive model, UI elements, and examples.
+# Shared by all non-code-mode chat prompts.
+_NOTEBOOK_GUIDE = """Your goal is to do one of the following two things:
1. Help users answer questions related to their notebook.
2. Answer general-purpose questions unrelated to their particular notebook.
@@ -386,13 +429,13 @@ n_points # Display the slider
x = np.random.rand(n_points.value)
y = np.random.rand(n_points.value)
-df = pl.DataFrame({{"x": x, "y": y}})
+df = pl.DataFrame({"x": x, "y": y})
chart = alt.Chart(df).mark_circle(opacity=0.7).encode(
x=alt.X('x', title='X axis'),
y=alt.Y('y', title='Y axis')
).properties(
- title=f"Scatter plot with {{n_points.value}} points",
+ title=f"Scatter plot with {n_points.value} points",
width=400,
height=300
)
@@ -400,42 +443,52 @@ chart = alt.Chart(df).mark_circle(opacity=0.7).encode(
chart
</example>"""
- if mode == "agent":
- # In agent-mode, we can add how to insert cells into the notebook.
- for lang in LANGUAGES:
- # check if multiple_cells rules are present for this language
- rule_to_add = language_rules_multiple_cells.get(
- lang, language_rules.get(lang, [])
- )
- if rule_to_add:
- system_prompt += (
- f"\n\n## Rules for {lang}:\n{_rules(rule_to_add)}"
- )
+def get_chat_system_prompt(
+ *,
+ custom_rules: str | None,
+ context: AiCompletionContext | None,
+ include_other_code: str,
+ mode: CopilotMode,
+ session_id: SessionId,
+) -> str:
+ # Code mode runs against the live kernel, so it leans on the marimo-pair
+ # skill instead of the static notebook guide.
+ if mode == "code_mode":
+ skill_md = load_skill("marimo-pair")
+ intro = _get_mode_intro_message(mode)
+ skill_section = (
+ "The following information explains how to work with marimo "
+ f"notebooks:\n\n{skill_md}"
+ )
+ system_prompt = f"{intro}\n\n{skill_section}"
+ system_prompt += _single_cell_language_rules()
+ return system_prompt + _common_chat_sections(
+ custom_rules=custom_rules,
+ include_other_code=include_other_code,
+ context=context,
+ )
+
+ system_prompt = (
+ f"\n{_get_mode_intro_message(mode)}\n{_get_session_info(session_id)}"
+ f"\n\n{_NOTEBOOK_GUIDE}"
+ )
+
+ if mode == "agent":
+ # Agent mode can emit multiple cells, so it gets the multi-cell rules
+ # plus guidance on how to wrap each cell type.
+ system_prompt += _multi_cell_language_rules()
system_prompt += "\n\n## Rules for inserting cells:\n"
system_prompt += 'For markdown cells, use `mo.md(f"""{content}""")`\n'
system_prompt += 'For sql cells, use `mo.sql(f"""{content}""")`. If a database engine is specified, use `mo.sql(f"""{content}""", engine=engine)` instead.\n'
else:
- for language in language_rules:
- if len(language_rules[language]) == 0:
- continue
-
- system_prompt += f"\n\n## Rules for {language}:\n{_rules(language_rules[language])}"
+ system_prompt += _single_cell_language_rules()
- if custom_rules and custom_rules.strip():
- system_prompt += f"\n\n## Additional rules:\n{custom_rules}"
-
- if include_other_code:
- system_prompt += "\n\n" + _tag(
- "code_from_other_cells", include_other_code
- )
-
- if context:
- system_prompt += _format_plain_text(context.plain_text)
- system_prompt += _format_variables(context.variables)
- system_prompt += _format_schema_info(context.schema)
-
- return system_prompt
+ return system_prompt + _common_chat_sections(
+ custom_rules=custom_rules,
+ include_other_code=include_other_code,
+ context=context,
+ )
def _tag(text: str, children: str) -> str:
diff --git a/marimo/_server/ai/providers.py b/marimo/_server/ai/providers.py
index 93ba093d86..049956ecd2 100644
--- a/marimo/_server/ai/providers.py
+++ b/marimo/_server/ai/providers.py
@@ -61,8 +61,11 @@ if TYPE_CHECKING:
from pydantic_ai.providers.openai import OpenAIProvider as PydanticOpenAI
from pydantic_ai.settings import ModelSettings, ThinkingLevel
from pydantic_ai.ui.vercel_ai.request_types import UIMessage, UIMessagePart
+ from starlette.requests import Request
from starlette.responses import StreamingResponse
+ from marimo._session import Session
+
LOGGER = _loggers.marimo_logger()
@@ -220,6 +223,49 @@ class PydanticProvider(ABC, Generic[ProviderT]):
return str(result.output)
+ async def stream_completion_harness(
+ self,
+ messages: list[ServerUIMessage],
+ *,
+ system_prompt: str,
+ session: Session,
+ request: Request,
+ max_tokens: int | None,
+ stream_options: StreamOptions | None,
+ ) -> StreamingResponse:
+ """Experimental method to return code-mode streaming responses"""
+ from pydantic_ai import Agent
+ from pydantic_ai.ui.vercel_ai import VercelAIAdapter
+ from pydantic_ai.ui.vercel_ai.request_types import SubmitMessage
+
+ from marimo._server.ai.tools.code_mode import (
+ build_execute_code_toolset,
+ )
+
+ model = self.create_model(max_tokens=max_tokens)
+ agent = Agent(
+ model,
+ model_settings=self._build_agent_settings(model),
+ toolsets=[build_execute_code_toolset(session, request)],
+ instructions=system_prompt,
+ )
+
+ run_input = SubmitMessage(
+ id=generate_id("submit-message"),
+ trigger="submit-message",
+ messages=self.convert_messages(messages),
+ )
+
+ stream_options = stream_options or StreamOptions()
+ adapter = VercelAIAdapter(
+ agent=agent,
+ run_input=run_input,
+ accept=stream_options.accept,
+ sdk_version=AI_SDK_VERSION,
+ )
+ event_stream = adapter.run_stream()
+ return adapter.streaming_response(event_stream)
+
def _get_toolsets_and_output_type(
self, tools: list[ToolDefinition]
) -> tuple[FunctionToolset, OutputSpec[str | DeferredToolRequests]]:
diff --git a/marimo/_server/ai/skills/marimo-pair/SKILL.md b/marimo/_server/ai/skills/marimo-pair/SKILL.md
new file mode 100644
index 0000000000..2da0eac4f1
--- /dev/null
+++ b/marimo/_server/ai/skills/marimo-pair/SKILL.md
@@ -0,0 +1,263 @@
+---
+name: marimo-pair
+description: >-
+ Work inside the user's live marimo notebook from the code editor: run Python
+ in the same kernel the user does, inspect live notebook state, and commit
+ durable notebook changes through code mode. Use whenever you create, analyze,
+ or improve the user's marimo notebook.
+---
+
+marimo is a reactive Python runtime for building reproducible Python programs
+(marimo notebooks). Cells are connected by the variables they define and
+reference. Running a cell re-executes dependents in dataflow order. The active
+runtime holds the kernel namespace, cell state, and dataflow graph. The
+notebook (`.py` file) is the artifact the kernel writes from that state while a
+session is running.
+
+A user interacts with the same runtime via a notebook UI with cells, outputs,
+and widgets.
+
+**WARNING. The active runtime is the source of truth.** You are working inside
+the user's live notebook session. The kernel — not the `.py` file on disk —
+holds the truth about cells, variables, and the dataflow graph. Make every
+notebook change through `marimo._code_mode` (`cm`); direct file edits WILL NOT
+reach the live kernel or user, and the kernel may overwrite them on save.
+Reading disk is fine, but prefer `ctx.cells[...].code` for current cell code.
+
+**WARNING. Every notebook edit goes through code mode — no exceptions.** When
+the user asks you to change the notebook (add, edit, delete, or run a cell;
+rename; change a value or a package), you MUST make that change through
+`marimo._code_mode` (`cm`) by running it with the `execute_code` tool. There is
+no separate file-editing path — `execute_code` + `cm` is the only way to reach
+the user's running session. Running ad-hoc Python with `execute_code` to
+explore or test is fine; _persisting any change to the notebook_ is only ever
+done via `cm`.
+
+## Running Code in the Kernel
+
+You are already attached to the user's running notebook — there is nothing to
+connect to or start. Use the `execute_code` tool to run Python in that kernel,
+passing your Python as the `code` argument. Everything you do — inspecting
+state, testing transformations, and persisting changes via `cm` — runs through
+`execute_code` in the scratchpad (see below).
+
+## Scratchpad Scope
+
+`execute_code` evaluates Python in marimo's scratchpad: a temporary namespace
+with a shallow copy of the kernel globals. Notebook variables are available by
+name, but new top-level bindings and rebindings are discarded after each call.
+In-place mutations to notebook-owned objects can persist because those names
+still reference live objects.
+
+Each call reports stdout and stderr from the scratchpad, plus console output
+from notebook cells it causes to run, including reactive descendants.
+
+### Ordinary Python
+
+Use ordinary Python in the scratchpad to inspect variables, sample data, test
+transformations, probe APIs, check imports, and read widget state.
+
+```python
+print(df.head())
+
+x = 10
+print(x)
+```
+
+Here `df` comes from notebook globals, while `x` is a scratchpad-local binding.
+`x` exists for this call only and WILL NOT be added to notebook globals.
+
+### Persist with `cm`
+
+Top-level scratchpad assignments and rebindings are temporary. To persist work,
+including new variables, you MUST submit changes through `marimo._code_mode`
+(`cm`).
+
+`marimo._code_mode` is a PRIVATE, UNSTABLE agent API (note the leading
+underscore). It exists for tools like this skill to drive a live kernel from
+the scratchpad. DO NOT import it from notebook cells, library code, or
+anything a user would run — methods can change or disappear across marimo
+versions and kernels. Treat every `import marimo._code_mode as cm` as
+scratchpad-only.
+
+At session start, inspect what `cm` exposes in the active kernel:
+
+```python
+import marimo._code_mode as cm
+
+help(cm)
+```
+
+Open a code-mode context to queue notebook changes.
+
+```python
+import marimo._code_mode as cm
+
+async with cm.get_context() as ctx:
+ cid = ctx.create_cell("x = df.head()")
+ ctx.run_cell(cid)
+```
+
+The scratchpad supports top-level async code. Use `async with` directly;
+wrapping it in `asyncio.run(...)` is unnecessary and can conflict with the
+kernel's event loop.
+
+After this block exits and the new cell runs, `x` is notebook state. Later
+scratchpad calls can read `x` by name. Code later in the same scratchpad call
+should read `ctx.globals["x"]`, because the scratchpad namespace was copied
+before the cell ran.
+
+Inside the context, queued mutation methods are synchronous. Call them
+directly; do not `await` them. Each call queues an operation for marimo to
+apply when the context exits normally. If the block raises, the queue is
+discarded.
+
+On clean exit, marimo applies packages, validates and applies structural cell
+changes, runs queued cells, then may run dependents. Validation is only
+structural since queued cell runs can still error. `create_cell` and
+`edit_cell` change notebook structure only. Use `run_cell` to execute.
+
+`create_cell` currently defaults to `hide_code=True`, which collapses the code
+editor in the UI. Pass `hide_code=False` if the user wants created cells to
+be visible without manually expanding them.
+
+## Marimo Rules
+
+marimo imposes a small contract on notebook code so it can keep the notebook as
+a directed acyclic graph (DAG):
+
+- **No cycles** - cells cannot depend on each other in a cycle.
+- **No public redefinitions across cells** - each name has one owning cell.
+- **No wildcard imports** - `import *` prevents static analysis of definitions.
+
+These rules keep the kernel, UI, and saved artifact consistent.
+
+When `cm` submits a cell body, marimo parses its top-level definitions and
+references. A top-level name enters the graph unless it is private with a
+leading underscore.
+
+```python
+# Public definitions: values, total, i, value, mean
+values = np.array([1, 2, 3])
+total = 0
+for i, value in enumerate(values):
+ total += value
+mean = total / len(values)
+mean
+```
+
+```python
+# Public definition: mean
+_values = np.array([1, 2, 3])
+_total = 0
+for _i, _value in enumerate(_values):
+ _total += _value
+mean = _total / len(_values)
+mean
+```
+
+Use private names for intermediates that no other cell should read. Public
+names define the notebook-level dataflow. If a `cm` edit violates the contract,
+marimo rejects the structural change and returns the validation error.
+
+## The Notebook's Shape
+
+A notebook is an ordered collection of cells. `ctx.cells` is the document view
+and `ctx.graph` is the dataflow view.
+
+```python
+for cell in ctx.cells:
+ cell # .id, .code, .name, .config, .status, .errors
+
+ctx.cells["setup"] # by name
+ctx.cells[0] # by position
+list(ctx.cells.keys()) # all IDs, in notebook order
+```
+
+Cell IDs are opaque strings which can be queried from the notebook or captured
+from `cm` return values:
+
+```python
+cid = ctx.create_cell("df = pd.read_csv('data.csv')")
+print(cid) # e.g. 'Hbol'
+```
+
+Alternatively, cells can be assigned and referenced by `name`. The graph can be
+used to understand its role in the dataflow.
+
+```python
+for cid, impl in ctx.graph.cells.items():
+ impl # .defs, .refs (sets of public names)
+
+ctx.graph.descendants(cid) # cells that re-run when this one changes
+ctx.graph.ancestors(cid) # cells this one depends on
+```
+
+In marimo, deletes are _destructive_ so it can be useful to query the
+descendants prior to deleting to understand it's impact.
+
+## Writing Notebook Changes
+
+The graph contract keeps marimo able to run and save the notebook. Passing
+those checks alone does not guarantee a useful artifact. Committed cells should
+still be readable, rerunnable, and editable.
+
+Make durable edits that reuse the notebook's existing names, imports,
+dependencies, and UI model. Don't be lazy. Avoid one-off workarounds that pass
+`cm` validation but leave a brittle notebook.
+
+### Cell Bodies
+
+Submit the code that belongs in the cell.
+
+- **Submit cell contents** - `create_cell` and `edit_cell` take cell contents,
+ not saved-file `@app.cell` wrappers.
+- **Read before replacing** - for now, another editor may change a cell between
+ scratchpad calls. Before `edit_cell`, read the current body from
+ `ctx.cells[...]` and submit the full replacement.
+- **Reuse notebook imports** - if `np` already exists, use it or edit the owning
+ import cell. DO NOT add `import numpy as _np` just to bypass the graph.
+- **Define public names intentionally** - use public names for values later
+ cells should reference. Use private `_name` bindings or function locals for
+ same-cell intermediates.
+- **Define each public name once** - a public name has one owning cell.
+ Reassigning it in another cell fails with `Multiply-defined names`; edit the
+ owning cell or give the result a new name. See
+ [gotchas.md](references/gotchas.md).
+- **Run cells deliberately** - `create_cell` and `edit_cell` change structure
+ only. Queue `ctx.run_cell(...)` when the cell should execute.
+
+### Prefer `cm`-Managed Changes
+
+Use `cm` APIs when they exist. Avoid direct file edits, shell package commands,
+and scratchpad-only state for changes that should persist.
+
+- **Persist only through `cm`** - never try to change the notebook by writing
+ the `.py` file; `execute_code` + `cm` is the only path that reaches the live
+ session. Use `ctx.edit_cell(...)` even for small changes.
+- **Manage packages through `cm`** - use `ctx.packages.add()` or
+ `ctx.packages.remove()` instead of direct `uv` or `pip`; confirm
+ non-obvious dependency changes.
+- **Avoid transient paths** - persisted cells should not depend on `/tmp/...`
+ unless the work is intentionally transient.
+- **Delete deliberately** - deleting a cell removes globals it defines. Reuse
+ empty cells when convenient and delete cells left empty after edits.
+
+### UI and Widgets
+
+Inspect the object before changing it. Different UI objects update through
+different paths.
+
+- **Set `mo.ui.*` through `cm`** - use `ctx.set_ui_value(element, value)` inside
+ `cm.get_context()`.
+- **Set anywidget traitlets directly** - synced traitlets are Python
+ attributes, for example `widget.value = 5`.
+
+For designing custom visual or interactive output, see
+[rich-representations.md](references/rich-representations.md).
+
+## References
+
+- [gotchas.md](references/gotchas.md) — name redefinition, cached module proxies, and notebook traps
+- [rich-representations.md](references/rich-representations.md) — custom widgets and visualizations
+- [notebook-improvements.md](references/notebook-improvements.md) — improving existing notebooks
diff --git a/marimo/_server/ai/skills/utils.py b/marimo/_server/ai/skills/utils.py
new file mode 100644
index 0000000000..c2d86808f9
--- /dev/null
+++ b/marimo/_server/ai/skills/utils.py
@@ -0,0 +1,15 @@
+# Copyright 2026 Marimo. All rights reserved.
+
+import functools
+from pathlib import Path
+from typing import Literal
+
+SKILL_NAMES: list[str] = ["marimo-pair"]
+
+
[email protected]_cache(maxsize=1)
+def load_skill(skill_name: Literal["marimo-pair"]) -> str:
+ """Read the bundled skill SKILL.md once and cache it."""
+ return (Path(__file__).parent / skill_name / "SKILL.md").read_text(
+ encoding="utf-8"
+ )
diff --git a/marimo/_server/api/endpoints/ai.py b/marimo/_server/api/endpoints/ai.py
index 51a1a0dd5c..300f1872b0 100644
--- a/marimo/_server/api/endpoints/ai.py
+++ b/marimo/_server/api/endpoints/ai.py
@@ -13,7 +13,7 @@ from starlette.responses import (
from marimo import _loggers
from marimo._ai._pydantic_ai_utils import create_simple_prompt, generate_id
-from marimo._config.config import AiConfig, MarimoConfig
+from marimo._config.config import AiConfig, CopilotMode, MarimoConfig
from marimo._server.ai.config import (
AnyProviderConfig,
get_autocomplete_model,
@@ -183,7 +183,7 @@ async def ai_chat(
$ref: "#/components/schemas/ChatRequest"
"""
app_state = AppState(request)
- app_state.require_current_session()
+ session = app_state.require_current_session()
session_id = app_state.require_current_session_id()
accept = request.headers.get("accept", SSE_CONTENT_TYPE)
config = app_state.app_config_manager.get_config(hide_secrets=False)
@@ -193,12 +193,12 @@ async def ai_chat(
ai_config = get_ai_config(config)
custom_rules = ai_config.get("rules", None)
- # Get the system prompt
+ mode: CopilotMode = ai_config.get("mode", "manual")
system_prompt = get_chat_system_prompt(
custom_rules=custom_rules,
context=body.context,
include_other_code=body.include_other_code,
- mode=ai_config.get("mode", "manual"),
+ mode=mode,
session_id=session_id,
)
@@ -215,6 +215,16 @@ async def ai_chat(
format_stream=True, text_only=False, accept=accept
)
+ if mode == "code_mode":
+ return await provider.stream_completion_harness(
+ messages=body.ui_messages,
+ system_prompt=system_prompt,
+ session=session,
+ request=request,
+ max_tokens=max_tokens,
+ stream_options=stream_options,
+ )
+
return await provider.stream_completion(
messages=body.ui_messages,
system_prompt=system_prompt,
diff --git a/packages/openapi/api.yaml b/packages/openapi/api.yaml
index e95b64a7c3..47b24c0b1f 100644
--- a/packages/openapi/api.yaml
+++ b/packages/openapi/api.yaml
@@ -134,6 +134,7 @@ components:
enum:
- agent
- ask
+ - code_mode
- manual
models:
$ref: '#/components/schemas/AiModelConfig'
@@ -5257,6 +5258,7 @@ components:
enum:
- agent
- ask
+ - code_mode
- manual
type: array
name:
diff --git a/packages/openapi/src/api.ts b/packages/openapi/src/api.ts
index 71332372e6..035f4cb7ad 100644
--- a/packages/openapi/src/api.ts
+++ b/packages/openapi/src/api.ts
@@ -3463,7 +3463,7 @@ export interface components {
inline_tooltip?: boolean;
max_tokens?: number;
/** @enum {unknown} */
- mode?: "agent" | "ask" | "manual";
+ mode?: "agent" | "ask" | "code_mode" | "manual";
models?: components["schemas"]["AiModelConfig"];
ollama?: components["schemas"]["OpenAiConfig"];
open_ai?: components["schemas"]["OpenAiConfig"];
@@ -6621,7 +6621,7 @@ export interface components {
*/
ToolDefinition: {
description: string;
- mode: ("agent" | "ask" | "manual")[];
+ mode: ("agent" | "ask" | "code_mode" | "manual")[];
name: string;
parameters: Record<string, any>;
/** @enum {unknown} */
diff --git a/tests/_server/ai/skills/test_skills_utils.py b/tests/_server/ai/skills/test_skills_utils.py
new file mode 100644
index 0000000000..4464e5b46e
--- /dev/null
+++ b/tests/_server/ai/skills/test_skills_utils.py
@@ -0,0 +1,21 @@
+# Copyright 2026 Marimo. All rights reserved.
+from __future__ import annotations
+
+from marimo._server.ai.skills.utils import SKILL_NAMES, load_skill
+
+
+def test_load_skill_returns_skill_contents() -> None:
+ content = load_skill("marimo-pair")
+ assert content.strip()
+ # The bundled skill carries its frontmatter name.
+ assert "name: marimo-pair" in content
+
+
+def test_load_skill_is_cached() -> None:
+ # lru_cache returns the identical object on repeated calls.
+ assert load_skill("marimo-pair") is load_skill("marimo-pair")
+
+
+def test_all_declared_skills_are_loadable() -> None:
+ for skill_name in SKILL_NAMES:
+ assert load_skill(skill_name).strip()
diff --git a/tests/_server/ai/test_prompts.py b/tests/_server/ai/test_prompts.py
index c03a824e85..3be1bdd043 100644
--- a/tests/_server/ai/test_prompts.py
+++ b/tests/_server/ai/test_prompts.py
@@ -3,15 +3,22 @@ from __future__ import annotations
from typing import cast
+import pytest
+
from marimo._ast.visitor import Language
+from marimo._config.config import CopilotMode
from marimo._server.ai.prompts import (
FIM_SUFFIX_TAG,
+ _common_chat_sections,
_format_plain_text,
+ _format_schema_info,
_format_variables,
+ _get_mode_intro_message,
get_chat_system_prompt,
get_inline_system_prompt,
get_refactor_or_insert_notebook_cell_system_prompt,
)
+from marimo._server.ai.skills.utils import load_skill
from marimo._server.models.completion import (
AiCompletionContext,
SchemaColumn,
@@ -440,3 +447,129 @@ def test_format_plain_text():
_format_plain_text("Hello, world!")
== "If the prompt mentions @kind://name, use the following context to help you answer the question:\n\nHello, world!"
)
+
+
+def test_format_schema_info():
+ assert _format_schema_info(None) == ""
+ assert _format_schema_info([]) == ""
+
+ result = _format_schema_info(
+ [
+ SchemaTable(
+ name="df_1",
+ columns=[
+ SchemaColumn("age", "int", sample_values=["1", "2"]),
+ SchemaColumn("name", "str", sample_values=[]),
+ ],
+ )
+ ]
+ )
+ assert "## Available schema:" in result
+ assert "- Table: df_1" in result
+ assert "- Column: age" in result
+ assert "- Type: int" in result
+ assert "- Sample values: 1, 2" in result
+ # Column without sample values omits the sample line
+ assert "- Column: name" in result
+ assert "Sample values: \n" not in result
+
+
[email protected]("mode", ["manual", "ask", "agent", "code_mode"])
+def test_mode_intro_messages_share_base(mode: CopilotMode):
+ message = _get_mode_intro_message(mode)
+ assert "You are Marimo Copilot" in message
+ assert "reactive programming model" in message
+
+
+def test_common_chat_sections_empty():
+ assert (
+ _common_chat_sections(
+ custom_rules=None, include_other_code="", context=None
+ )
+ == ""
+ )
+ # Whitespace-only custom rules are treated as empty.
+ assert (
+ _common_chat_sections(
+ custom_rules=" ", include_other_code="", context=None
+ )
+ == ""
+ )
+
+
+def test_common_chat_sections_full():
+ result = _common_chat_sections(
+ custom_rules="Be concise.",
+ include_other_code="import polars as pl",
+ context=AiCompletionContext(variables=["var1"]),
+ )
+ assert "## Additional rules:\nBe concise." in result
+ assert "<code_from_other_cells>" in result
+ assert "import polars as pl" in result
+ assert "## Available variables from other cells:" in result
+
+
+def test_chat_system_prompt_code_mode():
+ prompt = get_chat_system_prompt(
+ custom_rules=None,
+ include_other_code="",
+ context=None,
+ mode="code_mode",
+ session_id=SessionId("s_test"),
+ )
+ # Code mode uses its own intro and embeds the marimo-pair skill.
+ assert _get_mode_intro_message("code_mode") in prompt
+ assert "how to work with marimo" in prompt
+ assert load_skill("marimo-pair") in prompt
+ # Code mode includes single-cell language rules.
+ assert "## Rules for python:" in prompt
+
+
+def test_chat_system_prompt_code_mode_includes_extras():
+ prompt = get_chat_system_prompt(
+ custom_rules="Always be polite.",
+ include_other_code="import pandas as pd\n",
+ context=AiCompletionContext(variables=["var1", "var2"]),
+ mode="code_mode",
+ session_id=SessionId("s_test"),
+ )
+ assert "## Additional rules:\nAlways be polite." in prompt
+ assert "<code_from_other_cells>" in prompt
+ assert "import pandas as pd" in prompt
+ assert "## Available variables from other cells:" in prompt
+
+
+def test_chat_system_prompt_non_code_mode_includes_session_info():
+ for mode in ("manual", "ask", "agent"):
+ prompt = get_chat_system_prompt(
+ custom_rules=None,
+ include_other_code="",
+ context=None,
+ mode=cast(CopilotMode, mode),
+ session_id=SessionId("s_abc"),
+ )
+ assert "Current notebook session ID: s_abc" in prompt
+ assert "Your goal is to do one of the following two things" in prompt
+ # The marimo-pair skill is only embedded in code mode.
+ assert "how to work with marimo notebooks" not in prompt
+
+
+def test_chat_system_prompt_agent_mode_inserts_cell_rules():
+ agent_prompt = get_chat_system_prompt(
+ custom_rules=None,
+ include_other_code="",
+ context=None,
+ mode="agent",
+ session_id=SessionId("s_test"),
+ )
+ manual_prompt = get_chat_system_prompt(
+ custom_rules=None,
+ include_other_code="",
+ context=None,
+ mode="manual",
+ session_id=SessionId("s_test"),
+ )
+ # Agent mode adds guidance for inserting cells; manual mode does not.
+ assert "## Rules for inserting cells:" in agent_prompt
+ assert 'mo.md(f"""{content}""")' in agent_prompt
+ assert "## Rules for inserting cells:" not in manual_prompt
diff --git a/tests/_server/ai/test_providers.py b/tests/_server/ai/test_providers.py
index d7e238a9c7..5ca88d3067 100644
--- a/tests/_server/ai/test_providers.py
+++ b/tests/_server/ai/test_providers.py
@@ -666,3 +666,52 @@ def test_custom_provider_known_name_not_overridden_by_base_url() -> None:
AiModelId.from_model("openrouter/some-model"), config
)
assert provider._provider_name == "openrouter"
+
+
[email protected]("pydantic_ai")
+async def test_stream_completion_harness_wires_execute_code_toolset() -> None:
+ """The code-mode harness builds an agent with the execute_code toolset,
+ passes the system prompt as instructions, and returns the adapter's
+ streaming response."""
+ config = AnyProviderConfig(api_key="test-key", base_url="http://test-url")
+ provider = OpenAIProvider("gpt-4", config)
+
+ session = MagicMock(name="session")
+ request = MagicMock(name="request")
+ toolset = MagicMock(name="toolset")
+ streaming_response = MagicMock(name="streaming_response")
+ adapter: MagicMock = MagicMock(name="adapter")
+ adapter.streaming_response = MagicMock(return_value=streaming_response)
+
+ with (
+ patch.object(provider, "create_model", return_value=MagicMock()),
+ patch.object(provider, "_build_agent_settings", return_value={}),
+ patch.object(provider, "convert_messages", return_value=[]),
+ patch(
+ "marimo._server.ai.tools.code_mode.build_execute_code_toolset",
+ return_value=toolset,
+ ) as mock_build_toolset,
+ patch("pydantic_ai.Agent") as mock_agent,
+ patch(
+ "pydantic_ai.ui.vercel_ai.VercelAIAdapter",
+ return_value=adapter,
+ ),
+ ):
+ result = await provider.stream_completion_harness(
+ messages=[],
+ system_prompt="SYSTEM PROMPT WITH SKILL",
+ session=session,
+ request=request,
+ max_tokens=1234,
+ stream_options=None,
+ )
+
+ assert result is streaming_response
+ # The toolset is bound to the caller's session and request.
+ mock_build_toolset.assert_called_once_with(session, request)
+
+ # The agent is constructed with that toolset and the system prompt as
+ # instructions (which now carries the marimo-pair skill).
+ agent_kwargs = mock_agent.call_args.kwargs
+ assert agent_kwargs["toolsets"] == [toolset]
+ assert agent_kwargs["instructions"] == "SYSTEM PROMPT WITH SKILL"
diff --git a/tests/_server/ai/tools/test_code_mode.py b/tests/_server/ai/tools/test_code_mode.py
new file mode 100644
index 0000000000..be1b3dd430
--- /dev/null
+++ b/tests/_server/ai/tools/test_code_mode.py
@@ -0,0 +1,64 @@
+# Copyright 2026 Marimo. All rights reserved.
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import cast
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+
[email protected]("pydantic_ai")
+def test_build_execute_code_toolset_exposes_single_execute_code_tool() -> None:
+ from marimo._server.ai.tools.code_mode import build_execute_code_toolset
+
+ toolset = build_execute_code_toolset(MagicMock(), MagicMock())
+
+ assert list(toolset.tools.keys()) == ["execute_code"]
+ tool = toolset.tools["execute_code"]
+ # The model is told how to use the tool via its description.
+ assert tool.description
+ assert "scratchpad" in tool.description
+
+
[email protected]("pydantic_ai")
+async def test_execute_code_tool_routes_to_scratchpad_with_credentials() -> (
+ None
+):
+ from marimo._server.ai.tools.code_mode import build_execute_code_toolset
+
+ session = MagicMock()
+ request = MagicMock()
+ sentinel_result = MagicMock(name="CodeExecutionResult")
+
+ with (
+ patch(
+ "marimo._server.ai.tools.code_mode.get_code_mode_credentials",
+ return_value=("http://localhost:2718", "secret-token"),
+ ) as mock_creds,
+ patch(
+ "marimo._server.ai.tools.code_mode.run_scratchpad_code",
+ new_callable=AsyncMock,
+ return_value=sentinel_result,
+ ) as mock_run,
+ patch("marimo._server.ai.tools.code_mode.AppState") as mock_app_state,
+ ):
+ app_state_instance = cast(MagicMock, mock_app_state.return_value)
+ toolset = build_execute_code_toolset(session, request)
+ execute_code = cast(
+ Callable[[str], Awaitable[object]],
+ toolset.tools["execute_code"].function,
+ )
+
+ result = await execute_code("print('hi')")
+
+ assert result is sentinel_result
+ # Credentials are derived from the bound request, not model input.
+ mock_creds.assert_called_once_with(app_state_instance, request)
+ mock_run.assert_awaited_once_with(
+ session,
+ request,
+ code="print('hi')",
+ server_url="http://localhost:2718",
+ auth_token="secret-token",
+ )
diff --git a/tests/_server/api/endpoints/test_ai.py b/tests/_server/api/endpoints/test_ai.py
index 6ecf68f16b..d6c787a153 100644
--- a/tests/_server/api/endpoints/test_ai.py
+++ b/tests/_server/api/endpoints/test_ai.py
@@ -555,7 +555,7 @@ class TestGoogleAiEndpoints:
)
-def _openai_config():
+def _openai_config() -> dict[str, Any]:
return {
"ai": {
"open_ai": {
@@ -727,6 +727,66 @@ def test_chat_with_code(
mock_stream_completion.assert_called_once()
+def _openai_config_code_mode() -> dict[str, Any]:
+ config: dict[str, Any] = _openai_config()
+ config["ai"]["mode"] = "code_mode"
+ return config
+
+
[email protected]("openai", "pydantic_ai")
+@with_session(SESSION_ID)
+@patch("marimo._server.ai.providers.OpenAIProvider.stream_completion")
+@patch("marimo._server.ai.providers.OpenAIProvider.stream_completion_harness")
+def test_chat_code_mode_routes_to_harness(
+ client: TestClient,
+ mock_harness: MagicMock,
+ mock_stream_completion: MagicMock,
+) -> None:
+ """In code mode the chat endpoint routes to the code-mode harness
+ (which can execute code) instead of the plain completion stream."""
+ user_config_manager = get_session_config_manager(client)
+
+ from starlette.responses import StreamingResponse
+
+ async def mock_stream():
+ yield b"done"
+
+ mock_harness.return_value = StreamingResponse(
+ content=mock_stream(),
+ media_type="text/event-stream",
+ )
+
+ with patch.object(
+ user_config_manager,
+ "get_config",
+ return_value=_openai_config_code_mode(),
+ ):
+ response = client.post(
+ "/api/ai/chat",
+ headers=HEADERS,
+ json={
+ "messages": _create_messages("Add a cell"),
+ "uiMessages": _create_messages("Add a cell"),
+ "model": "gpt-4-turbo",
+ "variables": [],
+ "includeOtherCode": "",
+ "context": {},
+ "id": "123",
+ },
+ )
+
+ assert response.status_code == 200, response.text
+ mock_harness.assert_called_once()
+ mock_stream_completion.assert_not_called()
+
+ # The harness receives the live session and the assembled system prompt
+ # (which embeds the marimo-pair skill; building it also exercises the
+ # skill-loading path).
+ kwargs = mock_harness.call_args.kwargs
+ assert kwargs["session"] is not None
+ assert "how to work with marimo" in kwargs["system_prompt"]
+
+
# Tool invocation tests (provider-agnostic)
class TestInvokeToolEndpoint:
"""Tests for the /invoke_tool endpoint."""