---
url: https://marimo-team.github.io/marimo-lens/getting-started.md
description: >-
  Install Lens, connect a notebook agent, make a first selection, and review the
  first change.
---

# Getting started

This page takes you from an empty notebook to a first reviewed change. You need
Python 3.10 through 3.14, [uv](https://docs.astral.sh/uv/), and an agent that
can run Python in the live marimo kernel. [marimo pair](https://marimo.io/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:

[![Open in molab](https://molab.marimo.io/molab-shield.svg)](https://molab.marimo.io/notebooks/nb_MimGXwYTcvjfb1sdUdaTyn)

::: details notebook.py

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

import marimo

__generated_with = "0.25.2"
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:

```sh
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.

::: details Use an existing uv project

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

```sh
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 → Connect your agent**,
  choose it, and follow the connection instructions. If you already use
  [marimo pair](https://marimo.io/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 agent resolves the
verified request, and a resolution receipt shows its summary. Requests the
agent cannot verify stay open with an explanation.

::: details 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._capability)`, 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](./agents) covers discovery and resource access.

:::

## Keep a record

The dock marimo mounts keeps no record of resolved requests. To keep one, add
a cell that constructs a Lens with `record`:

```python
from marimo_lens import Lens

lens = Lens(record=True)
lens
```

This Lens replaces the automatic one. Each resolved request now appends a line
to `__marimo__/lens/notebook.py.jsonl` with the code of every cell it changed,
and Lens stores the selection's image beside it. The dock gains a **History**
tab where you review resolved requests and reopen one to refine the result, and
your agent can ask which earlier changes still hold.

Pass a dict to change what the record keeps:

```python
Lens(record={"keep": "session"})  # kernel memory only, no files
Lens(record={"images": False})  # record lines without images
Lens(record={"history": False})  # no History tab, agents still read the record
```

Read [Data and trust](./data-and-trust#request-record) before committing the
`__marimo__/lens/` folder, and [`Record`](./api#record) for every option.

## Try it here

::: info 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.

The demo shows three monthly revenue values: January 42, February 58, and
March 39, in USD thousands. Its Trail visits the data table, compares the bars,
then explains that February has the highest revenue and that revenue is not
profit. The reader controls the steps. A walkthrough leaves selections
unchanged.

## Next steps

* [Selections](./selections) covers gestures, notes, images, receipts, History, and reopening.
* [How Lens works](./how-lens-works) explains what your agent receives and how it returns results.
* [Custom targets](./custom-targets) makes cards, dashboards, and custom views selectable.