Meet Maid

Diagram Perfection Service

Maid ensures your Mermaid diagrams always work. Lightweight and browser-free (unlike mermaid-cli), she provides intelligent linting, automatic fixing, and contextual error messages to help both humans and AI create flawless diagrams.

Get Started → View on GitHub

What Makes Maid Special

She's not just a linter — she's your diagram companion

🎯

Smart Linting

Catches every syntax error before it breaks. From missing arrows to unbalanced brackets, Maid spots issues instantly and shows you exactly where they are.

✨

Auto-Fixing Magic

Why just report errors when she can fix them? Maid automatically corrects common mistakes, adds missing syntax, and formats your diagrams beautifully.

💬

Contextual Help

Every error comes with helpful context and suggestions. Perfect for learning Mermaid syntax or helping AI tools generate correct diagrams on the first try.

🤖

AI-Friendly

Designed to work seamlessly with AI code generators. Clear error messages help LLMs understand and fix diagram syntax issues automatically.

⚡

Lightning Fast

Validates complex diagrams in milliseconds. Real-time feedback as you type, whether in VSCode, your terminal, or CI/CD pipeline.

🪶

Featherweight

No browser, no puppeteer, no heavy dependencies. Unlike mermaid-cli, Maid runs in pure JavaScript. Tiny install size, instant startup, minimal memory usage.

Why Maid, Not Mermaid-CLI?

❌ Mermaid-CLI

• Requires Puppeteer & Chromium (~170MB)
• Slow startup (browser launch)
• Memory hungry
• Complex installation
• Just renders, no validation

✨ Maid

• Pure JavaScript (~5MB)
• Instant startup
• Minimal memory footprint
• Simple npm install
• Validates, fixes, and educates

Getting Started with Maid

Installation and usage examples

📦 Installation

npm

# Install globally
npm install -g @probelabs/maid

# Or use directly with npx (no installation needed)
npx @probelabs/maid check diagram.mmd

# Install as dev dependency for your project
npm install --save-dev @probelabs/maid

💻 CLI Usage

terminal

# Check a single diagram
maid check flowchart.mmd

# Check and auto-fix issues
maid fix flowchart.mmd

# Check all diagrams in a directory
maid check ./diagrams/*.mmd

# Use with npx (no installation required)
npx @probelabs/maid check diagram.mmd

# Output JSON for CI/CD integration
maid check diagram.mmd --format json

# Watch mode for development
maid watch ./diagrams --auto-fix

🤖 SDK for Agentic Flows

javascript

import { MaidLinter } from '@probelabs/maid';

// Initialize the linter
const maid = new MaidLinter();

// Validate a diagram string
const diagram = `
flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Process]
    B -->|No| D[End]
`;

const result = await maid.validate(diagram);

if (!result.isValid) {
    console.log('Found issues:', result.errors);
    
    // Auto-fix the issues
    const fixed = await maid.autoFix(diagram);
    console.log('Fixed diagram:', fixed.content);
}

// Use in AI agent workflows
async function generateValidDiagram(prompt) {
    let diagram = await llm.generate(prompt);
    
    // Ensure the diagram is valid
    const validation = await maid.validate(diagram);
    
    if (!validation.isValid) {
        // Get contextual hints for the AI
        const hints = validation.errors.map(e => e.suggestion);
        
        // Regenerate with error context
        diagram = await llm.generate(prompt, { 
            context: hints,
            previousAttempt: diagram 
        });
    }
    
    return diagram;
}

⚙️ Configuration

json

// .maidrc.json
{
  "rules": {
    "arrow-style": "error",
    "node-naming": "warning",
    "max-depth": ["error", 5]
  },
  "autoFix": {
    "enabled": true,
    "rules": ["arrow-style", "missing-brackets"]
  },
  "ignore": ["**/draft-*.mmd"]
}

🔧 CI/CD Integration

yaml

# GitHub Actions
name: Validate Mermaid Diagrams
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run Maid Linter
        run: npx @probelabs/maid check "**/*.mmd"

See Maid in Action

Fixing your diagrams with style

❯ maid check diagram.mmd

✨ Checking your diagram, master...

💔 Found 2 issues that need attention:

Line 4: Missing arrow between nodes
  Before: A[Start] B[Process]
  Fixed:  A[Start] --> B[Process]

Line 8: Unclosed bracket in node definition
  Before: C[Final Step
  Fixed:  C[Final Step]

✨ All fixed! Your diagram is now perfect~
💡 Run with --auto-fix to apply these changes automatically

❯ maid fix diagram.mmd
✅ Fixed 2 issues and saved diagram.mmd

Probe Ecosystem

Maid is part of the Probe ecosystem—tools dedicated to improving human and AI collaboration in development.

While Probe helps AI understand your codebase context, Maid ensures your Mermaid diagrams are always syntactically perfect. Together, they create a seamless environment where AI agents can work alongside developers without friction.

Every tool in our ecosystem shares the same philosophy: be lightweight, be fast, and make the development experience delightful for both humans and AI.

Explore the Ecosystem →