Editing and Verification Enforcement
Key Concepts
Cell Structure
Editing Rules
Core CLI Commands
Export Commands
Live Session (marimo-pair)
Data and Visualization
Debugging Workflow
Common Issues
Additional Resources

Marimo Reactive Notebooks

Marimo is a reactive Python notebook where cells form a DAG and auto-execute on dependency changes. Notebooks are stored as pure .py files.

Editing and Verification Enforcement

IRON LAW #1: NEVER MODIFY CELL DECORATORS OR SIGNATURES

Only edit code INSIDE @app.cell function bodies. This is not negotiable.

NEVER modify:

Cell decorators (@app.cell)
Function signatures (def _(deps):)
Return statements structure (trailing commas required)

ALWAYS verify:

All used variables are in function parameters
All created variables are in return statement
Trailing comma for single returns: return var,

IRON LAW #2: NO EXECUTION CLAIM WITHOUT OUTPUT VERIFICATION

Before claiming ANY marimo notebook works:

VALIDATE syntax and structure: marimo check notebook.py
EXECUTE with outputs: marimo export ipynb notebook.py -o __marimo__/notebook.ipynb --include-outputs
VERIFY using notebook-debug skill's verification checklist
CLAIM success only after verification passes

This is not negotiable. Skipping execution and output inspection is NOT HELPFUL — the user gets a notebook that fails when they open it.

Marimo Facts

marimo check validates syntax and structure only — it never executes cells. Claiming a notebook works because check passed is an unverified claim presented as fact.
Reactivity propagates every edit through the DAG: a one-line change re-executes all dependent cells. Verifying only the edited cell misses downstream breakage — counterproductive on its own terms.
Wrong dependencies or missing returns break reactivity silently: no error at edit time, only a NameError when a dependent cell runs. Validate that all used variables are in params AND all created variables are in returns.
A variable created but not returned raises NameError in every cell that depends on it.
Python treats return var as returning the bare value, which breaks unpacking — single returns require the trailing comma (return var,).

Red Flags — STOP If About To:

Edit a @app.cell decorator or def _(...) signature → STOP. Marimo manages these; edit only the function body.
Claim done after only marimo check → STOP. Execution with --include-outputs is required.
Claim the notebook works from reading the code → STOP. Reactive correctness shows only at runtime.
Define a variable that another cell already defines → STOP. One variable = one cell.

Editing Checklist

Before every marimo edit:

Structure Validation:

[ ] Only edit code INSIDE @app.cell function bodies
[ ] Do NOT modify decorators or signatures
[ ] Verify all used variables are in function parameters
[ ] Verify all created variables are in return statement
[ ] Ensure trailing comma used for single returns
[ ] Ensure no variable redefinitions across cells

Syntax Validation:

[ ] Execute marimo check notebook.py
[ ] Verify no syntax errors reported
[ ] Verify no undefined variable warnings
[ ] Verify no redefinition warnings

Runtime Verification:

[ ] Execute with marimo export ipynb notebook.py -o __marimo__/notebook.ipynb --include-outputs
[ ] Verify export succeeded (exit code 0)
[ ] Verify output ipynb exists and is non-empty
[ ] Apply notebook-debug verification checklist
[ ] Verify no tracebacks in any cell
[ ] Verify all cells executed (execution_count not null)
[ ] Verify outputs match expectations

Only after ALL checks pass:

[ ] Claim "notebook works"

Gate Function: Marimo Verification

Follow this sequence for EVERY marimo task:

1. EDIT     → Modify code inside @app.cell function bodies only
2. CHECK    → marimo check notebook.py
3. EXECUTE  → marimo export ipynb notebook.py -o __marimo__/notebook.ipynb --include-outputs
4. INSPECT  → Use notebook-debug verification
5. VERIFY   → Outputs match expectations
6. CLAIM    → "Notebook works" only after all gates passed

NEVER skip verification gates. Marimo's reactivity means changes propagate unpredictably.

Key Concepts

Reactive execution: Cells auto-update when dependencies change
No hidden state: Each variable defined in exactly one cell
Pure Python: .py files, version control friendly
Cell structure: @app.cell decorator pattern

Cell Structure

import marimo

app = marimo.App()

@app.cell
def _(pl):  # Dependencies as parameters
    df = pl.read_csv("data.csv")
    return df,  # Trailing comma required for single return

@app.cell
def _(df, pl):
    summary = df.describe()
    filtered = df.filter(pl.col("value") > 0)
    return summary, filtered  # Multiple returns

Editing Rules

Edit code INSIDE @app.cell functions only
Never modify cell decorators or function signatures
Variables cannot be redefined across cells
All used variables must be returned from their defining cell
Markdown cells: Always wrap $ in backticks - mo.md("Cost: $50") not mo.md("Cost: $50")

Core CLI Commands

| Command | Purpose | |---------|---------| | marimo edit notebook.py | marimo: Open notebook in browser editor for interactive development | | marimo run notebook.py | marimo: Run notebook as executable app | | marimo check notebook.py | marimo: Validate notebook structure and syntax without execution | | marimo convert notebook.ipynb | marimo: Convert Jupyter notebook to marimo format |

Export Commands

# marimo: Export to ipynb with code only
marimo export ipynb notebook.py -o __marimo__/notebook.ipynb

# marimo: Export to ipynb with outputs (runs notebook first)
marimo export ipynb notebook.py -o __marimo__/notebook.ipynb --include-outputs

# marimo: Export to HTML (runs notebook by default)
marimo export html notebook.py -o __marimo__/notebook.html

# marimo: Export to HTML with auto-refresh on changes (live preview)
marimo export html notebook.py -o __marimo__/notebook.html --watch

Key difference: HTML export runs the notebook by default. ipynb export does NOT - use --include-outputs to run and capture outputs.

Tip: Use __marimo__/ folder for all exports (ipynb, html). The editor can auto-save there.

Live Session (marimo-pair)

For working inside a running marimo notebook kernel — executing code, creating/editing cells, and building notebooks interactively — use the marimo-pair protocol. Full details: marimo-pair/SKILL.md.

Starting a Server

See marimo-pair/reference/finding-marimo.md for the full decision tree. Quick start:

# pixi project (our standard)
pixi run marimo edit notebook.py --no-token --watch

# uv project
uv run marimo edit notebook.py --no-token --watch

# standalone / sandbox
uvx marimo@latest edit notebook.py --no-token --watch --sandbox

Always use --watch so the server detects file edits and reloads automatically. Without it, file changes are invisible to the browser and the user sees stale content.

Always start as a background task (run_in_background) so the server doesn't block the conversation. Do NOT use --headless unless asked — let marimo open the browser.

Discovery and Execution

# Discover running servers
bash ${CLAUDE_SKILL_DIR}/marimo-pair/scripts/discover-servers.sh

# Execute code in the kernel (one-liner)
bash ${CLAUDE_SKILL_DIR}/marimo-pair/scripts/execute-code.sh -c "df.head()"

# Execute code (multiline — use heredoc to avoid shell escaping)
bash ${CLAUDE_SKILL_DIR}/marimo-pair/scripts/execute-code.sh <<'EOF'
import marimo._code_mode as cm

async with cm.get_context() as ctx:
    cid = ctx.create_cell("x = 1")
    ctx.run_cell(cid)
EOF

Use --port to target a specific server, --session for a specific notebook, --url for remote servers.

Key Concepts

Scratchpad execution: Code runs in the kernel with all cell variables in scope, but nothing persists between calls. Use this to explore and validate.
Cell mutations: Use marimo._code_mode with async with cm.get_context() as ctx: to create/edit/delete cells and install packages. All ctx.* methods are synchronous — do NOT await them.
Cells are not auto-executed: create_cell and edit_cell are structural only — call ctx.run_cell(cid) to execute.
Install packages via ctx.install_packages(), not uv add or pip.
NEVER write to the .py file directly while a session is running — the kernel owns it.

marimo-pair References

marimo-pair/reference/finding-marimo.md — How to find and invoke the right marimo binary
marimo-pair/reference/gotchas.md — Cached module proxies and other traps
marimo-pair/reference/rich-representations.md — Custom anywidgets, _display_(), Arrow IPC for large data
marimo-pair/reference/notebook-improvements.md — Setup cells, lifting functions, mo.persistent_cache

Data and Visualization

Prefer polars over pandas for performance
Use mo.ui for interactive widgets
SQL cells: mo.sql(df, "SELECT * FROM df")
Display markdown: mo.md("# Heading")

Debugging Workflow

1. Pre-execution validation:

# scripts: Validate notebook syntax and cell structure
scripts/check_notebook.sh notebook.py

Runs syntax check, marimo validation, and cell structure overview in one command.

2. Runtime errors: Export with outputs, then use notebook-debug skill:

# marimo: Export to ipynb with outputs for inspection
marimo export ipynb notebook.py -o __marimo__/notebook.ipynb --include-outputs

Common Issues

| Issue | Fix | |-------|-----| | Variable redefinition | Rename one variable or merge cells | | Circular dependency | Break cycle by merging or restructuring | | Missing return | Add return var, with trailing comma | | Import not available | Ensure import cell returns the module |

Additional Resources

Reference Files

For detailed patterns and advanced techniques, consult:

references/reactivity.md - DAG execution, variable rules, dependency detection patterns
references/debugging.md - Error patterns, runtime debugging, environment-specific issues
references/widgets.md - Interactive UI components and mo.ui patterns
references/sql.md - SQL cells and database integration techniques
marimo-pair/reference/finding-marimo.md - How to find and invoke marimo across project types
marimo-pair/reference/gotchas.md - Cached module proxies (e.g., polars + pyarrow mid-session)
marimo-pair/reference/rich-representations.md - Custom anywidgets, Arrow IPC, _display_() protocol
marimo-pair/reference/notebook-improvements.md - Setup cells, lifting functions, mo.persistent_cache

Examples

Working examples available in examples/:

examples/basic_notebook.py - Minimal marimo notebook structure
examples/data_analysis.py - Data loading, filtering, and visualization patterns
examples/interactive_widgets.py - Interactive UI component usage

Scripts

Validation and live-session utilities:

scripts/check_notebook.sh - Primary validation: syntax check, marimo validation, cell structure overview
scripts/get_cell_map.py - Extract cell metadata (invoked by check_notebook.sh)
marimo-pair/scripts/discover-servers.sh - Find running marimo servers
marimo-pair/scripts/execute-code.sh - Execute code in a running marimo kernel

Related Skills

notebook-debug - Debugging executed ipynb files with tracebacks and output inspection
marimo-pair/SKILL.md - Full marimo-pair protocol for live kernel interaction

Editing and Verification Enforcement
Key Concepts
Cell Structure
Editing Rules
Core CLI Commands
Export Commands
Live Session (marimo-pair)
Data and Visualization
Debugging Workflow
Common Issues
Additional Resources

Marimo Reactive Notebooks

Marimo is a reactive Python notebook where cells form a DAG and auto-execute on dependency changes. Notebooks are stored as pure .py files.

Editing and Verification Enforcement

IRON LAW #1: NEVER MODIFY CELL DECORATORS OR SIGNATURES

Only edit code INSIDE @app.cell function bodies. This is not negotiable.

NEVER modify:

Cell decorators (@app.cell)
Function signatures (def _(deps):)
Return statements structure (trailing commas required)

ALWAYS verify:

All used variables are in function parameters
All created variables are in return statement
Trailing comma for single returns: return var,

IRON LAW #2: NO EXECUTION CLAIM WITHOUT OUTPUT VERIFICATION

Before claiming ANY marimo notebook works:

VALIDATE syntax and structure: marimo check notebook.py
EXECUTE with outputs: marimo export ipynb notebook.py -o __marimo__/notebook.ipynb --include-outputs
VERIFY using notebook-debug skill's verification checklist
CLAIM success only after verification passes

This is not negotiable. Skipping execution and output inspection is NOT HELPFUL — the user gets a notebook that fails when they open it.

Marimo Facts

marimo check validates syntax and structure only — it never executes cells. Claiming a notebook works because check passed is an unverified claim presented as fact.
Reactivity propagates every edit through the DAG: a one-line change re-executes all dependent cells. Verifying only the edited cell misses downstream breakage — counterproductive on its own terms.
Wrong dependencies or missing returns break reactivity silently: no error at edit time, only a NameError when a dependent cell runs. Validate that all used variables are in params AND all created variables are in returns.
A variable created but not returned raises NameError in every cell that depends on it.
Python treats return var as returning the bare value, which breaks unpacking — single returns require the trailing comma (return var,).

Red Flags — STOP If About To:

Edit a @app.cell decorator or def _(...) signature → STOP. Marimo manages these; edit only the function body.
Claim done after only marimo check → STOP. Execution with --include-outputs is required.
Claim the notebook works from reading the code → STOP. Reactive correctness shows only at runtime.
Define a variable that another cell already defines → STOP. One variable = one cell.

Editing Checklist

Before every marimo edit:

Structure Validation:

[ ] Only edit code INSIDE @app.cell function bodies
[ ] Do NOT modify decorators or signatures
[ ] Verify all used variables are in function parameters
[ ] Verify all created variables are in return statement
[ ] Ensure trailing comma used for single returns
[ ] Ensure no variable redefinitions across cells

Syntax Validation:

[ ] Execute marimo check notebook.py
[ ] Verify no syntax errors reported
[ ] Verify no undefined variable warnings
[ ] Verify no redefinition warnings

Runtime Verification:

[ ] Execute with marimo export ipynb notebook.py -o __marimo__/notebook.ipynb --include-outputs
[ ] Verify export succeeded (exit code 0)
[ ] Verify output ipynb exists and is non-empty
[ ] Apply notebook-debug verification checklist
[ ] Verify no tracebacks in any cell
[ ] Verify all cells executed (execution_count not null)
[ ] Verify outputs match expectations

Only after ALL checks pass:

[ ] Claim "notebook works"

Gate Function: Marimo Verification

Follow this sequence for EVERY marimo task:

1. EDIT     → Modify code inside @app.cell function bodies only
2. CHECK    → marimo check notebook.py
3. EXECUTE  → marimo export ipynb notebook.py -o __marimo__/notebook.ipynb --include-outputs
4. INSPECT  → Use notebook-debug verification
5. VERIFY   → Outputs match expectations
6. CLAIM    → "Notebook works" only after all gates passed

NEVER skip verification gates. Marimo's reactivity means changes propagate unpredictably.

Key Concepts

Reactive execution: Cells auto-update when dependencies change
No hidden state: Each variable defined in exactly one cell
Pure Python: .py files, version control friendly
Cell structure: @app.cell decorator pattern

Cell Structure

import marimo

app = marimo.App()

@app.cell
def _(pl):  # Dependencies as parameters
    df = pl.read_csv("data.csv")
    return df,  # Trailing comma required for single return

@app.cell
def _(df, pl):
    summary = df.describe()
    filtered = df.filter(pl.col("value") > 0)
    return summary, filtered  # Multiple returns

Editing Rules

Edit code INSIDE @app.cell functions only
Never modify cell decorators or function signatures
Variables cannot be redefined across cells
All used variables must be returned from their defining cell
Markdown cells: Always wrap $ in backticks - mo.md("Cost: $50") not mo.md("Cost: $50")

Core CLI Commands

Export Commands

# marimo: Export to ipynb with code only
marimo export ipynb notebook.py -o __marimo__/notebook.ipynb

# marimo: Export to ipynb with outputs (runs notebook first)
marimo export ipynb notebook.py -o __marimo__/notebook.ipynb --include-outputs

# marimo: Export to HTML (runs notebook by default)
marimo export html notebook.py -o __marimo__/notebook.html

# marimo: Export to HTML with auto-refresh on changes (live preview)
marimo export html notebook.py -o __marimo__/notebook.html --watch

Key difference: HTML export runs the notebook by default. ipynb export does NOT - use --include-outputs to run and capture outputs.

Tip: Use __marimo__/ folder for all exports (ipynb, html). The editor can auto-save there.

Live Session (marimo-pair)

Starting a Server

See marimo-pair/reference/finding-marimo.md for the full decision tree. Quick start:

# pixi project (our standard)
pixi run marimo edit notebook.py --no-token --watch

# uv project
uv run marimo edit notebook.py --no-token --watch

# standalone / sandbox
uvx marimo@latest edit notebook.py --no-token --watch --sandbox

Always use --watch so the server detects file edits and reloads automatically. Without it, file changes are invisible to the browser and the user sees stale content.

Always start as a background task (run_in_background) so the server doesn't block the conversation. Do NOT use --headless unless asked — let marimo open the browser.

Discovery and Execution

# Discover running servers
bash ${CLAUDE_SKILL_DIR}/marimo-pair/scripts/discover-servers.sh

# Execute code in the kernel (one-liner)
bash ${CLAUDE_SKILL_DIR}/marimo-pair/scripts/execute-code.sh -c "df.head()"

# Execute code (multiline — use heredoc to avoid shell escaping)
bash ${CLAUDE_SKILL_DIR}/marimo-pair/scripts/execute-code.sh <<'EOF'
import marimo._code_mode as cm

async with cm.get_context() as ctx:
    cid = ctx.create_cell("x = 1")
    ctx.run_cell(cid)
EOF

Use --port to target a specific server, --session for a specific notebook, --url for remote servers.

Key Concepts

Scratchpad execution: Code runs in the kernel with all cell variables in scope, but nothing persists between calls. Use this to explore and validate.
Cell mutations: Use marimo._code_mode with async with cm.get_context() as ctx: to create/edit/delete cells and install packages. All ctx.* methods are synchronous — do NOT await them.
Cells are not auto-executed: create_cell and edit_cell are structural only — call ctx.run_cell(cid) to execute.
Install packages via ctx.install_packages(), not uv add or pip.
NEVER write to the .py file directly while a session is running — the kernel owns it.

marimo-pair References

marimo-pair/reference/finding-marimo.md — How to find and invoke the right marimo binary
marimo-pair/reference/gotchas.md — Cached module proxies and other traps
marimo-pair/reference/rich-representations.md — Custom anywidgets, _display_(), Arrow IPC for large data
marimo-pair/reference/notebook-improvements.md — Setup cells, lifting functions, mo.persistent_cache

Data and Visualization

Prefer polars over pandas for performance
Use mo.ui for interactive widgets
SQL cells: mo.sql(df, "SELECT * FROM df")
Display markdown: mo.md("# Heading")

Debugging Workflow

1. Pre-execution validation:

# scripts: Validate notebook syntax and cell structure
scripts/check_notebook.sh notebook.py

Runs syntax check, marimo validation, and cell structure overview in one command.

2. Runtime errors: Export with outputs, then use notebook-debug skill:

# marimo: Export to ipynb with outputs for inspection
marimo export ipynb notebook.py -o __marimo__/notebook.ipynb --include-outputs

Common Issues

Additional Resources

Reference Files

For detailed patterns and advanced techniques, consult:

references/reactivity.md - DAG execution, variable rules, dependency detection patterns
references/debugging.md - Error patterns, runtime debugging, environment-specific issues
references/widgets.md - Interactive UI components and mo.ui patterns
references/sql.md - SQL cells and database integration techniques
marimo-pair/reference/finding-marimo.md - How to find and invoke marimo across project types
marimo-pair/reference/gotchas.md - Cached module proxies (e.g., polars + pyarrow mid-session)
marimo-pair/reference/rich-representations.md - Custom anywidgets, Arrow IPC, _display_() protocol
marimo-pair/reference/notebook-improvements.md - Setup cells, lifting functions, mo.persistent_cache

Examples

Working examples available in examples/:

examples/basic_notebook.py - Minimal marimo notebook structure
examples/data_analysis.py - Data loading, filtering, and visualization patterns
examples/interactive_widgets.py - Interactive UI component usage

Scripts

Validation and live-session utilities:

scripts/check_notebook.sh - Primary validation: syntax check, marimo validation, cell structure overview
scripts/get_cell_map.py - Extract cell metadata (invoked by check_notebook.sh)
marimo-pair/scripts/discover-servers.sh - Find running marimo servers
marimo-pair/scripts/execute-code.sh - Execute code in a running marimo kernel

Related Skills

notebook-debug - Debugging executed ipynb files with tracebacks and output inspection
marimo-pair/SKILL.md - Full marimo-pair protocol for live kernel interaction

Adoption

edwinhu/marimo

$ install --global

Security Scan Results

SKILL.md

Contents

Marimo Reactive Notebooks

Editing and Verification Enforcement

IRON LAW #1: NEVER MODIFY CELL DECORATORS OR SIGNATURES

IRON LAW #2: NO EXECUTION CLAIM WITHOUT OUTPUT VERIFICATION

Marimo Facts

Red Flags — STOP If About To:

Editing Checklist

Gate Function: Marimo Verification

Key Concepts

Cell Structure

Editing Rules

Core CLI Commands

Export Commands

Live Session (marimo-pair)

Starting a Server

Discovery and Execution

Key Concepts

marimo-pair References

Data and Visualization

Debugging Workflow

Common Issues

Additional Resources

Reference Files

Examples

Scripts

Related Skills

Related Skills

edwinhu/dewey

edwinhu/hpc

edwinhu/writing-lit-review

edwinhu/paperpile

edwinhu/marimo

$ install --global

Security Scan Results

SKILL.md

Contents

Marimo Reactive Notebooks

Editing and Verification Enforcement

IRON LAW #1: NEVER MODIFY CELL DECORATORS OR SIGNATURES

IRON LAW #2: NO EXECUTION CLAIM WITHOUT OUTPUT VERIFICATION

Marimo Facts

Red Flags — STOP If About To:

Editing Checklist

Gate Function: Marimo Verification

Key Concepts

Cell Structure

Editing Rules

Core CLI Commands

Export Commands

Live Session (marimo-pair)

Starting a Server

Discovery and Execution

Key Concepts

marimo-pair References

Data and Visualization

Debugging Workflow

Common Issues

Additional Resources

Reference Files

Examples

Scripts

Related Skills

Related Skills

edwinhu/dewey

edwinhu/hpc

edwinhu/writing-lit-review

edwinhu/paperpile