Getting started

This page takes you from an empty notebook to a first reviewed change. You need Python 3.10 through 3.14, uv, and an agent that can run Python in the live marimo kernel. marimo pair and the editor's Code Mode (beta) sidebar both qualify.

Open the sample notebook

Save this file as notebook.py. Its inline script metadata declares Lens and marimo with its recommended extras, which include Altair for the chart and the packages marimo's AI assistant needs, so uv installs everything for you. To skip the local setup, open the same notebook in molab:

notebook.py

# /// script
# requires-python = ">=3.10"
# dependencies = [
#     "marimo[recommended]>=0.25.0",
#     "marimo-lens",
# ]
# ///

import marimo

__generated_with = "0.25.0"
app = marimo.App()


@app.cell
def _():
    import altair as alt
    import marimo as mo

    return alt, mo


@app.cell
def _(mo):
    revenue = [
        {"month": "January", "revenue": 42},
        {"month": "February", "revenue": 58},
        {"month": "March", "revenue": 39},
    ]
    mo.ui.table(revenue, selection=None)
    return (revenue,)


@app.cell
def _(alt, mo, revenue):
    chart = (
        alt.Chart(alt.Data(values=revenue))
        .mark_bar(color="#1D7363")
        .encode(
            x=alt.X("month:N", sort=None, title="Month"),
            y=alt.Y("revenue:Q", title="Revenue (USD thousands)"),
            tooltip=["month:N", "revenue:Q"],
        )
        .properties(title="Monthly revenue", width="container", height=220)
    )
    mo.ui.altair_chart(chart)
    return


@app.cell
def _(mo, revenue):
    peak = max(revenue, key=lambda row: row["revenue"])
    mo.md(
        f"**{peak['month']} leads with {peak['revenue']} thousand dollars.** "
        "These are revenue totals, not profit."
    )
    return


if __name__ == "__main__":
    app.run()

Start it in a sandbox that resolves those dependencies:

uvx marimo edit notebook.py --sandbox

The editor opens in your browser with three outputs, the data, the chart, and the conclusion, and the Lens dock at the bottom of the page. The three outputs give your agent a route from data to chart to conclusion.

Use an existing uv project

Add the dependencies to the project instead of using a sandbox, then open the same file:

uv add marimo-lens altair
uv run marimo edit notebook.py

For an already-running notebook, ask your connected agent to install Lens in its active Python environment and add the dock. Keep using the same session.

Connect your agent

You have two ways to bring an agent into the notebook. Pick one:

• Use marimo's built-in AI sidebar. Open the AI panel from the left sidebar, choose Code Mode (beta) in the mode menu, and pick a configured model. This needs a provider set up in marimo's AI settings, and the sample notebook's marimo[recommended] dependency already includes everything code mode needs.
• Use your own agent. If you would rather work with an agent you already use, such as Claude Code or Codex, open Settings → Pair with an agent, choose it, and follow the connection instructions. If you already use marimo pair, keep that connection.

Either way, check the connection by asking:

Which notebook are you connected to?

Continue when it identifies notebook.py and can inspect its live cells.

Add Lens

marimo mounts Lens automatically once a cell that imports marimo runs, so the sample notebook shows the dock without a Lens cell. In a notebook of your own that shows no dock after it runs, tell your connected agent:

Add Lens to this notebook.

The agent reuses an existing Lens or adds and runs a Lens cell. Continue when you can see the dock.

Ask for a walkthrough

Ask your agent:

Use Lens to walk me through this notebook, from the inputs to the main result.

The agent reads the relevant cells and values, then shows a Trail: an ordered explanation attached to the notebook's outputs. Use Next and Previous to follow it at your own pace, or dismiss it when finished. A walkthrough explains the existing notebook and needs no selection.

Address a selection

Press Select in the dock, click a point or drag a region on an output, and add a note. For the revenue chart, click February and write:

Make this bar orange and keep the other bars green

Then send this in the connected agent chat:

Address current Lens selection

Saving a note keeps the selection in Open until an agent reads it. The chat request starts the work. The agent loads its installed Lens instructions, checks the selected output and its producing code, makes the change, and verifies it.

Review the result when the agent brings it into view. In the sample, February should be orange while January and March remain green. The verified request moves to History with a summary. Reopen it to refine the result. Requests the agent cannot verify stay open with an explanation.

The agent cannot find Lens or my selection

Confirm that it is connected to this notebook and that the dock is mounted. Ask the agent to check that Lens is installed in that kernel, read help(marimo_lens.agent), and add the dock if it is missing.

A terminal can read the packaged briefing with uvx --with marimo-lens agent-plugins read marimo-lens. That command reads an isolated installation. Working with your notebook requires the live connection. Agent integration covers discovery and resource access.

Try it here

About this demo

This demo runs in your browser with scripted actions and no language model. It shows the Lens interactions and the tools a connected agent uses to explain a notebook and return results for review.

Press Show a walkthrough to visit the data, chart, and conclusion. The three steps explain which month leads and what the numbers measure. Use Next, Previous, and dismiss to control the Trail.

You can also press Select, mark a bar, and add a note to inspect the captured request. In your notebook, the agent chooses its actions from your request, code, and live results.

Next steps

• Selections covers gestures, notes, images, History, and reopening.
• How Lens works explains what your agent receives and how it returns results.
• Custom targets makes cards, dashboards, and custom views selectable.