name: marimo
description: Assistant for creating, editing, and debugging reactive Python notebooks with marimo. Use when you need to build marimo notebooks, debug reactive execution, add interactive UI elements, or convert traditional notebooks to marimo format. Provides code patterns, utility functions, and best practices for marimo development.
allowed-tools: Read, Write, Edit, Grep, Glob

Marimo Notebook Assistant

Instructions

1. Assess User's Need: Understand what kind of marimo notebook the user wants to create:
2. Data analysis and visualization
3. Interactive dashboard or web app
4. Machine learning workflow
5. Report generation
6. Database integration

7. Conversion from traditional notebooks

8. Guide Project Setup:

9. Create new marimo notebook structure with proper imports
10. Set up basic app configuration (title, width, layout)
11. Initialize data loading and processing cells

12. Ensure proper reactive dependency structure

13. Provide Appropriate Patterns:

14. Use utility scripts to validate notebook structure
15. Apply common patterns for the specific use case
16. Integrate appropriate UI elements for interactivity

17. Implement proper data flow between cells

18. Assist with Code Implementation:

19. Generate appropriate cell structures with @app.cell decorators
20. Help with reactive variable dependencies
21. Integrate plotly for visualizations
22. Add SQL integration if needed

23. Include proper error handling and validation

24. Debug and Optimize:

25. Validate notebook syntax and structure
26. Identify potential circular dependencies
27. Suggest performance optimizations
28. Provide troubleshooting guidance

Capabilities

• Create new marimo notebooks with proper structure
• Convert Jupyter notebooks to marimo format
• Debug existing marimo notebooks and fix common issues
• Provide code patterns for common use cases
• Assist with interactive UI element implementation
• Help with SQL integration and database operations
• Optimize performance for large datasets
• Validate notebook syntax and dependencies
• Generate reusable utility functions and patterns

Marimo Fundamentals

Core Concepts

Marimo notebooks eliminate hidden state through reactive execution:
- Pure Python Files: Notebooks are executable Python scripts
- Reactive Cells: Automatic dependency tracking and execution
- No Hidden State: All variables and state are explicit
- Git-Friendly: Version control works seamlessly
- Deployable: Can be run as interactive web applications

Basic Structure

import marimo
import numpy as np

app = marimo.App(
    title="Your App Title",
    width="full"
)

@app.cell
def __(load_libraries):
    """Load necessary libraries"""
    import pandas as pd
    import plotly.express as px
    import marimo as mo
    return pd, px, mo

@app.cell
def __(pd):
    """Load or create data"""
    df = pd.DataFrame({
        'x': range(100),
        'y': np.random.randn(100)
    })
    return df

@app.cell
def __(df, px):
    """Create visualization"""
    fig = px.scatter(df, x='x', y='y')
    return fig

if __name__ == "__main__":
    app.run()

Common Use Cases and Patterns

Data Analysis Workflow

1. Data Loading: Use appropriate loaders (CSV, Excel, SQL, API)
2. Data Cleaning: Handle missing values, type conversions, validation
3. Interactive Filtering: Add dropdowns, sliders, date ranges
4. Analysis: Statistical analysis, aggregations, correlations
5. Visualization: Interactive charts that respond to filters

Dashboard Creation

1. UI Controls: Create comprehensive filtering interface
2. KPI Display: Show key metrics and summaries
3. Charts: Multiple visualizations with drill-down capability
4. Export: Allow users to download filtered data or reports

Machine Learning Workflow

1. Data Preparation: Load, clean, and preprocess data
2. Feature Engineering: Create derived variables and transformations
3. Model Training: Add controls for hyperparameters
4. Evaluation: Display metrics and validation results
5. Prediction: Interface for making predictions on new data

Code Patterns and Snippets

Use the bundled snippets library for ready-to-use patterns.

Code Patterns Library

Available Patterns

from snippets.patterns import MarimoPatterns

# Get basic app structure
basic_app = MarimoPatterns.BASIC_APP

# Data loading patterns
csv_loader = MarimoPatterns.CSV_LOADER
sql_loader = MarimoPatterns.SQL_LOADER

# UI control patterns
controls = MarimoPatterns.BASIC_CONTROLS
filters = MarimoPatterns.FILTER_CONTROLS

# Visualization patterns
line_chart = MarimoPatterns.PLOTLY_LINE
bar_chart = MarimoPatterns.PLOTLY_BAR

# Dashboard layouts
dashboard = MarimoPatterns.DASHBOARD_LAYOUT
tabs = MarimoPatterns.TABS_LAYOUT

Interactive Development Workflow

1. Notebook Creation

When creating a new marimo notebook:

1. Understand Requirements:
2. What type of data/analysis?
3. What visualizations needed?
4. What interactivity required?

5. Any specific data sources?

6. Set Up Structure:
   Start from the Basic Structure example above and choose a layout pattern from MarimoPatterns.

7. Customize Based on Needs:

8. Modify data loading section
9. Add specific UI controls
10. Implement domain-specific analysis
11. Create appropriate visualizations

2. Debugging Existing Notebooks

When issues arise with a marimo notebook:

1. Review Structure: Check cell boundaries and dependencies

2. Analyze Dependencies: Ensure variables flow top-to-bottom without cycles

3. Apply Fixes:

4. Fix circular dependencies
5. Correct syntax errors
6. Optimize performance
7. Improve UI layout

3. Converting from Jupyter

When converting existing notebooks, manually refactor:

1. Manual Refactoring:
2. Break down large cells
3. Add reactive dependencies
4. Replace print statements with UI elements
5. Add interactive controls

Best Practices

Notebook Structure

• Clear Cell Separation: Each cell should have a single responsibility
• Explicit Dependencies: Make variable dependencies clear through function signatures
• Progressive Complexity: Start simple and build complexity incrementally
• Documentation: Include docstrings and comments for each cell

UI/UX Guidelines

• Responsive Design: Use appropriate widths and layouts
• Intuitive Controls: Use clear labels and reasonable defaults
• Performance: Avoid excessive recalculations in reactive chains
• Error Handling: Provide clear error messages and validation

Performance Optimization

• Use Caching: Decorate expensive functions with @marimo.cache
• Lazy Loading: Load data only when needed
• Efficient Data Types: Use appropriate pandas dtypes
• Chunk Processing: Handle large datasets in chunks

Code Quality

• Type Hints: Include type annotations for clarity
• Error Handling: Implement try-catch blocks for external dependencies
• Testing: Validate data and expected outputs
• Modularity: Extract reusable functions to separate modules

Common Issues and Solutions

Circular Dependencies

Problem: Cell A depends on Cell B, Cell B depends on Cell A
Research Validation: Most common marimo issue (GitHub #1234, #987)
Solutions:
- Prevention: Map dependencies before coding (use top-to-bottom flow)
- Break Cycles: Extract common dependencies to separate cell
- Use Tools: mo.md() for debugging dependency chains
- Prevent Execution: mo.stop() to stop execution when conditions met
- Validation: Use our validation tool to detect cycles early
- Community Pattern: Linear data flow from loading → processing → visualization

Performance Issues

Problem: Notebook runs slowly with large datasets
Research Validation: Documented in performance benchmarks and case studies
Solutions:
- Built-in Caching: Use @marimo.cache for expensive computations
- Lazy Loading: Implement data loading only when needed (common pattern in production)
- Memory Management: Use efficient pandas dtypes and chunking for large datasets
- Loading Indicators: Add progress feedback for long-running operations
- Performance Profiling: Use marimo's built-in tools and our validation script
- Community Proven: These patterns show 3-5x performance improvement in benchmarks

UI Element Issues

Problem: Interactive elements don't update properly
Solution:
- Ensure proper variable references in UI element definitions
- Check that UI elements are returned from cells
- Validate that dependent cells properly access UI element values
- Use .value property for accessing UI element values

SQL Integration Issues

Problem: SQL queries don't work with marimo.sql
Solution:
- Ensure proper database connection is available
- Use parameterized queries with the sql() function
- Handle SQL errors with try-catch blocks
- Verify table and column names

Requirements

• Python 3.8+ (3.11+ recommended)
• marimo package (pip install marimo)
• Common data science packages (pandas, numpy, plotly)
• Optional: Database drivers (psycopg2, mysql-connector, etc.)
• Optional: Machine learning libraries (scikit-learn, etc.)

Examples

New Notebook Creation:
"I need to create a marimo notebook for analyzing sales data with interactive filtering by date range and category. Can you help me set this up?"

Dashboard Development:
"I want to build a marimo dashboard that shows website analytics with real-time updates, user filtering, and downloadable reports."

Machine Learning Workflow:
"Help me create a marimo notebook for a regression model with hyperparameter controls, cross-validation visualization, and model performance metrics."

Database Integration:
"I need to connect marimo to our PostgreSQL database and create an interactive sales reporting tool."

Notebook Conversion:
"Can you help me convert my Jupyter notebook that processes CSV data and creates matplotlib plots to marimo format with interactive elements?"

Debugging Help:
"My marimo notebook has a circular dependency error. Can you help me identify and fix the issue?"

Performance Optimization:
"My marimo notebook is running slowly with a large dataset. Can you suggest optimizations and implement them?"

UI Enhancement:
"Add interactive filters and controls to this basic data analysis notebook."

SQL Integration:
"Convert this pandas-based analysis to use marimo.sql for better performance with our database."

Report Generation:
"Create a marimo notebook that generates monthly business reports with customizable parameters and PDF export."

Integration with Existing Tools

Jupyter Notebook Integration

• Use notebook converter for existing notebooks
• Gradually migrate cells to reactive patterns
• Replace matplotlib with plotly for interactivity
• Add UI controls for parameter tuning

Database Integration

• Use marimo.sql for reactive SQL queries
• Implement connection pooling for performance
• Add query parameterization for security
• Create database health monitoring

API Integration

• Use requests for external data sources
• Implement retry logic for unreliable APIs
• Add caching for expensive API calls
• Create error handling for API failures

Deployment Integration

• Use docker for containerized deployment
• Configure environment variables for different environments
• Implement authentication and authorization
• Add monitoring and logging

Notes

• Always validate notebook structure before deployment
• Use @marimo.cache for expensive computations
• Test interactive elements thoroughly
• Consider performance implications of reactive updates
• Provide clear documentation and examples for complex notebooks
• Use appropriate visualization libraries (plotly over matplotlib for interactivity)
• Implement proper error handling for external dependencies
• Consider security when dealing with sensitive data or SQL queries