Skip to content

Commit 1e5a7bf

Browse files
Add internal code mode module for programmatic notebook control (marimo-team#8670)
This introduces `marimo._code_mode`, an internal agent-only API that gives programmatic access to a running marimo notebook. The motivating use case is letting agents (e.g. from a scratchpad) insert, delete, replace, and reorder cells without going through the frontend UI. e.g., ```python import marimo._code_mode as cm async with cm.get_context() as ctx: # Install packages (queued, installed before cell ops) ctx.install_packages("pandas", "polars>=0.20") # Cell ops (appends at end by default) cid = ctx.create_cell("import pandas as pd") ctx.create_cell("df = pd.DataFrame()", after=cid) ctx.create_cell("setup()", before=cid, hide_code=True, disabled=True) ctx.update_cell("my_cell", code="x = 42") ctx.update_cell("other", hide_code=False, disabled=True) ctx.delete_cell("old_cell") ctx.move_cell("my_cell", after="other_cell") # Set UI element values (batched) ctx.set_ui_value(slider, 10) # Dry-run compile check is on by default; disable with: async with cm.get_context(check=False) as ctx: ... ``` --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
1 parent 9dd70d2 commit 1e5a7bf

18 files changed

Lines changed: 2268 additions & 26 deletions

File tree

marimo/_code_mode/__init__.py

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Copyright 2026 Marimo. All rights reserved.
2+
"""Code mode: programmatic notebook editing via async context manager.
3+
4+
.. warning::
5+
6+
**Internal, agent-only API.** Not part of marimo's public API.
7+
No versioning guarantees. May change or be removed without notice.
8+
9+
Usage::
10+
11+
import marimo._code_mode as cm
12+
13+
async with cm.get_context() as ctx:
14+
# Create cells (appends at end by default)
15+
cid = ctx.create_cell("x = 1")
16+
ctx.create_cell("y = x + 1", after=cid)
17+
18+
# Update cells by ID or name
19+
ctx.edit_cell("my_cell", code="z = 42")
20+
21+
# Delete cells
22+
ctx.delete_cell("old_cell")
23+
24+
# Move cells
25+
ctx.move_cell("my_cell", after="other_cell")
26+
27+
# Read cells (works outside the context manager too)
28+
ctx = cm.get_context()
29+
ctx.cells[0] # by index
30+
ctx.cells["my_cell"] # by name
31+
"""
32+
33+
from __future__ import annotations
34+
35+
from marimo._code_mode._context import (
36+
AsyncCodeModeContext,
37+
NotebookCellData,
38+
get_context,
39+
)
40+
41+
__all__ = [
42+
"AsyncCodeModeContext",
43+
"NotebookCellData",
44+
"get_context",
45+
]

0 commit comments

Comments
 (0)