Author with a coding agent

Marimo Studio ships an Agent Skill, a portable set of instructions that teaches a coding agent how to use Studio, and a Python API bound to the current Marimo code mode notebook and Studio tab. Code mode gives the agent a Python execution inside the live notebook kernel. The agent works with the same source documents, builds, and Preview that a person sees.

Use this loop:

inspect -> edit -> build -> show -> verify

Point to a result with Marimo Lens

Marimo Lens is an optional companion for selecting a rendered result, adding a note, and giving a coding agent its producing notebook context and image. For feedback in a Server view, install version 0.1.0 or newer in the notebook's Python environment:

uv pip install "marimo-lens>=0.1.0"

For sandboxed notebooks, also declare marimo-lens>=0.1.0 in the script's dependencies. Restart a running notebook after installing or upgrading Lens.

Define one Lens value in a notebook cell:

from marimo_lens import Lens
from marimo_studio import STUDIO_RESULT_SELECTOR

studio_lens = Lens(dom_selector=STUDIO_RESULT_SELECTOR)
None

Project it into the view:

<marimo-output value="studio_lens"></marimo-output>

The final None keeps the notebook cell's output empty so the dock appears on the projected view. Select mode shows the cell or value source beside the pointed result. An agent can inspect the selection through Lens in the same live kernel, edit through Studio, verify the result, and resolve the note.

Native cell, rich-output, and value projections carry their sources automatically. For React, Svelte, or other custom JavaScript rendering, link each meaningful result to its actual projection inputs as described in Trace custom JavaScript rendering. The Lens package supplies the selection workflow. Studio supplies the projection metadata.

Use the public Lens documentation for its agent API and feedback workflow. The source repository currently requires organization access.

Open the current workspace

Create the handles once in each code-mode execution:

import marimo_studio.agent as studio_agent

workspace = studio_agent.current_workspace()
view = workspace.view("dashboard")

The remaining snippets use these handles within the same execution. Reimport marimo_studio.agent and reacquire the handles in every new execution.

For a new view, project an existing notebook result, build, and show it before expanding the analysis or layout. Continue with small visible changes through the same loop.

Inspect before editing

Read the notebook inventory:

notebook = await workspace.inspect_notebook()
print(notebook.notebook.named_cells())

When a request reaches into a result's computation, inspect the producing cell and its upstream context:

producer = await workspace.inspect_notebook(
    selectors=("sales_summary",),
    include_code=True,
    context="upstream",
)

Inspect the selected view to find the source documents exposed by its view provider:

inspection = await view.inspect()
for document in inspection.documents:
    print(document.path, document.language, document.access)

Read AGENTS.md and DESIGN.md when present before changing the project. Use Studio's guarded writes for catalog documents with access="edit", or edit source directly under inspection.root with filesystem tools. Reinspect after either editing path. files records the observed source and build-input files, and changes_since(previous) compares two complete inventories for the same view owner.

For a multi-file edit, use view.hold_publication(owner="source-refactor") and retain its token across executions. Release with view.release_publication(token) when the source is ready, then build. The hold expires after 300 seconds by default. It delays replacement publication while files remain editable. See Manage view source for filesystem editing, hold duration, and checkpoint recovery.

Write against the current revision

Read a source document immediately before replacing it:

document = await view.read("index.html")
updated = document.content.replace("Current heading", "Quarterly revenue")

await view.write(
    "index.html",
    updated,
    expected_revision=document.revision,
)

If another author saved first, Studio raises SourceConflictError and keeps the newer source. Read it again, incorporate both changes, and write against the new revision.

Build and show

build = await view.build()
print(build.revision)

Studio validates the complete candidate before publishing it. A failed build keeps the last successful artifact in Preview. Inspect latest_build and its diagnostics for the failed attempt. build identifies the retained artifact, and published_project_revision identifies its source inputs.

Run show() in the next code-mode execution so the Studio tab can complete the transition:

import marimo_studio.agent as studio_agent

view = studio_agent.current_workspace().view("dashboard")
await view.show()

Exercise controls, navigation, conditional content, and dynamic results in the same Studio tab.

Verify the rendered view

Run browser validation after the relevant interactions settle:

import marimo_studio.agent as studio_agent

report = await studio_agent.current_workspace().view("dashboard").validate(
    level="browser"
)
if not report.ok:
    for issue in report.issues:
        print(issue.message, issue.advice)

The report belongs to the current saved notebook, source revisions, runtime, Studio tab, and presentation. A concurrent source edit invalidates that evidence. Read the current source and repeat validation after it settles.

Browser validation checks runtime and projection readiness. Inspect the rendered page at desktop and narrow widths for spacing, overflow, and interaction. Repair each issue, then repeat build, show, interaction, and validation.

Verify the delivery visitors will use

Use Run or export a view to select Python, Browser, or Prepared delivery. A live Python preview does not prove a static export's behavior. For Prepared delivery, declare the finite control states, run preflight, serve the completed export over HTTP, and exercise those states in the browser. Include a failed state change when the interface needs recovery.

Use marimo_studio.authoring for scripts that open a saved notebook outside code mode. Use the CLI reference for terminal automation.