Skip to content

pipeio nb_snapshot: marimo session capture for agent-human shared output

Problem

In the marimo --watch workflow, the human sees live outputs in the browser but the agent is blind -- it can edit the .py but cannot see prints, errors, or rendered plots. This breaks joint debugging and iterative exploration.

The agent conversation from pixecog confirmed this gap: "can you see the outputs?" / "No, I can't see the marimo UI or its outputs."

Discovery

Marimo has marimo export session which writes a JSON snapshot (__marimo__/session/<name>.json) containing full cell execution state:

NotebookSessionV1:
  cells: list[Cell]

Cell:
  id: str
  code_hash: str | None
  outputs: list[ErrorOutput | DataOutput]     # cell visual output
  console: list[StreamOutput | StreamMediaOutput]  # stdout/stderr

StreamOutput:
  type: "stream"
  name: "stdout" | "stderr"
  text: str

ErrorOutput:
  type: "error"
  ename: str      # e.g. "ValueError"
  evalue: str
  traceback: list[str]

DataOutput:
  type: "data"
  data: dict[str, Any]  # MIME bundles: {"text/html": "...", "image/png": "base64..."}

Source: marimo._schemas.session (stable, backwards-compatible schema with OpenAPI generation and CI checks).

Proposed tool: pipeio_nb_snapshot

Runs marimo export session, reads the JSON, returns structured cell outputs. Strips large binary MIME data (base64 images) to keep response manageable -- preserves text/plain, text/html (truncated), errors, and console output.

Workflow

  1. Human runs conda run -n cogpy marimo edit notebook.py --watch (sees live UI)
  2. Agent edits the .py file (human sees changes live via --watch)
  3. Agent runs pipeio_nb_snapshot(flow, name) (reads session JSON, sees outputs)
  4. Agent iterates based on actual cell results -- prints, errors, data summaries

This closes the feedback loop: both human and agent see the same execution state.