Notebook sessions

Use: pi-marimo. Add pi-bg for process management and waiting. Use the separate marimo-pair workflow to inspect and edit notebooks.

Pi-marimo observes notebook state. Its kiosk SSE connection does not run or edit code and does not take the browser’s editing session over. Its explicit interrupt control is a separate action.

Start a local notebook server

If marimo is already installed in your Python environment, ask Pi to start a service:

{
  "command": "marimo edit --no-token notebooks/fit.py",
  "kind": "service",
  "name": "fit notebook"
}

This is a bg_run example. Use the command that actually selects your project’s environment, such as uv run marimo edit, if needed. Pi-bg recognizes common marimo server commands and can detect readiness from their URL output.

Confirm what Pi is following

/marimo
/marimo show

The first opens a checklist to pin notebooks. The second prints the state block the model sees. Automatic discovery follows up to eight open notebooks under the current working directory, excluding hidden directories such as other worktree checkouts.

/marimo auto returns to automatic following.
/marimo off stops following.
/marimo view opens the full-screen notebook view.
Tab cycles followed notebooks in that view; o opens one in the browser.

A notebook outside the current directory may need pinning. “Not open” means there is no matching open session; starting a server and opening the notebook are distinct from having a busy kernel.

Make a change through the editing workflow

Ask the agent to use marimo-pair, not to treat pi-marimo as an editing tool:

Use marimo-pair to inspect the notebook. Add one small section, run it, and wait for its cells to finish. Tell me about errors before doing more.

Pi-marimo detects supported marimo-pair tool calls to identify the current notebook. It follows kernel events continuously, but inserts a single state snapshot per user prompt, held stable for the rest of the turn. That avoids rewriting the prefix under the model’s existing thinking on every request.

For the latest output during a turn, the agent should use marimo-pair’s results. The observation block is intentionally not a substitute for them. Outputs are dropped from the SSE observer; outlines, state, variables and errors are what matter.

Wait for cells, not just the server

When cells run or queue, a followed notebook can be waited on through pi-bg:

{ "id": "marimo:notebooks/fit.py" }

This is a bg_wait call. The ID uses the notebook’s path relative to Pi’s cwd (absolute for notebooks outside it). The basename form, such as marimo:fit.py, is accepted only when unambiguous.

With both plugins enabled, a recognized server row is annotated with its notebook state. Once the server is up, waiting on that server task can wait for the running cells rather than immediately returning “ready.”

Long marimo-pair execute calls may themselves run as background jobs. Those calls block until their cells finish; other execute calls against the same notebook can queue behind them. Do not launch concurrent edits as a way around a running cell.

Stop the right thing

Stopping a marimo-pair client job stops that command, not the cells it already requested.
Double-x in the notebook view explicitly interrupts the kernel, like the browser stop button.
Killing the server service stops the server process group.
Esc from bg_wait only stops waiting.

New cell errors make the observed run fail; old errors present before the run are not counted as new failures. A disconnection longer than eight seconds can also end the observed run as failed.

Add UI integrations only if useful

Pi-subagents can host the notebook pill. Pi-bg can include notebook entries in its task view. Status-footer gives the notebook a dedicated row. Inside Herdr, pi-herdr can show a notebook token and completion notice without claiming ownership of the pane’s state.

None of those siblings is required for the basic notebook observer. See requirements for external tools and the reference for connection limitations.