How Lens works
A Lens workflow keeps human attention, notebook code, and the returned result connected through one selection. The selection records a point or region on a target. Lens links that target to its producing cells, builds bounded notebook context, and attempts to capture a selection image. A code-mode agent uses those forms of evidence to inspect, change, and verify the notebook.
The agent then reveals the selected target for review and resolves the selection. Resolution moves it from Open to History. Reopening restores the selection as current.
The collaboration loop
- Mark the resultThe person selects evidence and describes what should change.
- Ground the requestLens connects the mark to its producing cell and graph context.
- Revise and verifyThe agent changes notebook code and checks the affected result.
- Review or reopenLens brings the result into view and preserves the selection for another pass.
Try the collaboration loop
Press Select, mark one bar, and add a note such as "Make this blue." The panel reads the same Lens state available to a code-mode agent. Click the API cards in order to send activity and review feedback back to the notebook.
Each card calls the method printed on it. A real agent keeps the activity handle while code mode inspects, edits, runs, and verifies the producing cells.
Lens context keeps three forms of evidence together
Lens returns three connected forms of evidence:
| Context property | Agent use |
|---|---|
references | Identifies each point or region, target, note, and producing cells. |
text | Supplies bounded source, graph relationships, and eligible control values. |
images | Supplies selection images when browser capture succeeded. |
The graph determines computational relevance. A selection image preserves capture-time visual focus. The selection remains usable when image capture is pending or fails because its reference, note, and available notebook context are independent evidence.
Code mode carries the notebook work
marimo_lens.agent connects to an existing Lens from code-mode globals or the active runtime's browser-ready registry. Its stable handle reads Lens state and sends notebook feedback across kernel calls. Code mode owns cell inspection, edits, execution, and runtime verification.
Follow the Agent workflow to connect a compatible agent. Read Context and evidence for the data boundary. The Python API reference defines method signatures.
Browser and Python responsibilities
Lens uses anywidget to connect its browser interface to a Python model in the notebook kernel.
| Browser | Python |
|---|---|
| Finds rendered outputs and handles pointer or keyboard input | Stores Open selections and History entries |
| Positions markers, selection UI, and agent feedback | Reads the live marimo graph and builds LensContext |
| Captures selection images of selected targets | Validates selection changes, activity, reveal, and resolution |
The two sides exchange compact selection records and explicit commands through the widget connection. PNG bytes travel separately from ordinary selection state.
Start with Getting started to mount Lens and create one selection. The Selections guide covers point and region gestures, multiple selections, History, and reopening.