Maid - Your Mermaid Assistant
Your syntax
needs attention~ 💕
Let me fix that
for you, darling ✨
I'll make your
diagrams perfect~
No error escapes
my service! 💖
Leave the validation
to me, dear~
I found all your
mistakes... ♥

Meet Maid

Your Diagram Perfection Service ✨

Lightning-fast Mermaid linter with intelligent auto-fix. No browser, no Puppeteer—just pure JavaScript validation that works everywhere: CLI, CI/CD, and AI agents. Catches errors with precision and fixes them instantly. When Maid says it's valid, it will render—guaranteed.

Try Interactive Demo → View on GitHub

See Maid in Action

Watch errors get caught and fixed with style

❯ npx -y @probelabs/maid diagram.mmd

✨ Validating your diagram...

💔 Found 2 issues that need my attention:

error[FL-ARROW-INVALID]: Invalid arrow syntax: -> (use --> instead)
at diagram.mmd:2:7
  1 | flowchart TD
  2 |     A -> B
            ^^
  3 |     B --> C
hint: Replace -> with -->, or use -- text --> for inline labels.

error[FL-NODE-UNCLOSED-BRACKET]: Unclosed '['. Add a matching ']'.
at diagram.mmd:4:13
  3 |     B --> C
  4 |     C[Start --> D
                  ^
  5 |     D --> E
hint: Example: A[Label] --> B

✗ 2 errors found

❯ npx -y @probelabs/maid --fix diagram.mmd

✨ Let me fix those for you, darling~

✓ Fixed: A -> B  →  A --> B
✓ Fixed: C[Start  →  C[Start ]

💖 All done! Fixed 2 issues in diagram.mmd
Your diagrams are perfect now~

Why Choose Maid?

Fast, precise, and always at your service

✅

Render Guarantee

When Maid says your diagram is valid, it will render. No more "looks correct but fails in production." Our validation matches actual Mermaid rendering behavior.

🤖

Built for AI Agents

Designed from the ground up for LLMs and AI agents. Clear, semantic error messages that AI can understand and learn from—not cryptic token lists.

🪶

5MB vs. 1.7GB

Pure JavaScript validation without Puppeteer or Chrome. Maid is ~300x smaller than mermaid-cli, installs in seconds, and runs instantly.

🔬

Modern Architecture

Built with Chevrotain, not 1990s Bison/Jison. Decoupled validation from rendering means we can validate at scale without launching browsers.

✨

Intelligent Auto-Fix

Automatically fixes common AI-generated mistakes. Two levels: safe mechanical fixes and smart heuristics that understand intent.

💬

Human-Friendly Errors

No more "Expecting 'SEMI', got 'MINUS'". Get clear messages with line numbers, visual carets, and actionable hints for fixing issues.

Maid vs Mermaid-CLI

A modern solution for a modern problem

❌ Mermaid-CLI

  • • Requires Puppeteer & Chromium (1.7GB)
  • • Must render to validate
  • • Jison parser (1990s technology)
  • • Tightly coupled architecture
  • • Cryptic errors: "Expecting 'SEMI', got 'MINUS'"
  • • No auto-fix capability
  • • Not designed for AI agents

✨ Maid

  • • Pure JavaScript (~5MB)
  • • Validates without rendering
  • • Chevrotain parser (modern, fast)
  • • Decoupled validation logic
  • • Semantic errors: "Invalid arrow: -> (use -->)"
  • • Intelligent auto-fix (2 levels)
  • • Built for AI & humans
  • • Active development
  • • Render guarantee when valid

Get Started with Maid

Ready to serve • No setup required • Full documentation available

Validate a single file npx -y @probelabs/maid diagram.mmd
Recursively validate directory npx -y @probelabs/maid docs/
Auto-fix safe issues npx -y @probelabs/maid --fix diagram.mmd
Auto-fix with heuristics npx -y @probelabs/maid --fix=all docs/
Preview fixes without writing npx -y @probelabs/maid --fix --dry-run diagram.mmd
JSON output for CI/CD npx -y @probelabs/maid --format json docs/
Include/exclude patterns npx -y @probelabs/maid docs/ -I "**/*.md" -E "legacy/**"
Read from stdin cat diagram.mmd | npx -y @probelabs/maid -
Install as dev dependency npm install -D @probelabs/maid

AI Agent Integration

Build intelligent agents with Maid's validation capabilities

🤖

SDK Integration

Create custom tools for AI agents to validate Mermaid diagrams

import { z } from 'zod';
import { tool } from 'ai';
import { validateMermaid } from '@probelabs/maid';

const mermaidValidator = tool({
  description: 'Validate Mermaid diagram syntax',
  parameters: z.object({
    diagram: z.string().describe('Mermaid diagram code'),
    autoFix: z.boolean().optional().describe('Auto-fix issues'),
  }),
  execute: async ({ diagram, autoFix }) => {
    const result = await validateMermaid(diagram, {
      fix: autoFix
    });
    return {
      valid: result.errors.length === 0,
      errors: result.errors,
      fixed: result.fixed,
      output: result.output
    };
  },
});
🔧

MCP Server for Claude

Add Maid as an MCP server for Claude Desktop or API

Quick Setup via CLI:

claude mcp add -- npx -y @probelabs/maid mcp

Manual Configuration:

Add to ~/.claude.json:

{
  "mcpServers": {
    "maid": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@probelabs/maid", "mcp"]
    }
  }
}
📚

SDK Documentation

For detailed JavaScript SDK documentation, API reference, and examples:

View SDK Documentation →

Let Maid Guard Your Pipeline

Seamless CI/CD integration • Complete setup guide available

🚀

GitHub Actions

Validate all your docs on every push or PR—never sleeps!

name: Lint Mermaid Diagrams
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22.x'
      - name: Lint docs/
        run: npx -y @probelabs/maid docs/
🪝

Pre-commit Hook

Catches mistakes before they make it to the repository

#!/bin/sh
# .git/hooks/pre-commit
set -e

STAGED=$(git diff --cached --name-only --diff-filter=ACMR)
[ -z "$STAGED" ] && exit 0

# Lint staged Mermaid/Markdown files
for f in $STAGED; do
  case "$f" in
    *.mmd|*.mermaid|*.md|*.markdown)
      echo "maid: $f"
      npx -y @probelabs/maid "$f" || exit 1
      ;;
  esac
done

Error Messages Matter

Especially when AI agents need to understand and fix their mistakes

When an AI agent generates an invalid diagram, cryptic error messages create a broken feedback loop. The AI can't learn from Expecting 'SEMI', got 'MINUS'. But it can understand and fix Invalid arrow: -> (use -->).

📄 Source Code

flowchart TD
    A -> B
    B --> C
❌ Mermaid-CLI Cryptic Parser Error 
Error: Parse error on line 2:
flowchart TD    A -> B    B --> C
------------------^
Expecting 'SEMI', 'NEWLINE', 'EOF', 'AMP',
'START_LINK', 'LINK', 'LINK_ID', got 'MINUS'
Parser3.parseError (node_modules/mermaid/...
    at #evaluate (node_modules/puppeteer-core/...
    at async ExecutionContext.evaluate (node...
✨ Maid Clear & Actionable 
error[FL-ARROW-INVALID]: Invalid arrow syntax: -> (use --> instead)
at diagram.mmd:2:7
  1 | flowchart TD
  2 |     A -> B
    |       ^^
  3 |     B --> C
hint: Replace -> with -->, or use -- text --> for inline labels.

✨ Auto-Fixed with --fix

flowchart TD
    A --> B
    B --> C

📄 Source Code

flowchart TD
    A[Start] --> B{"Is \"Driver\" configured?"}
❌ Mermaid-CLI Stack Trace Hell 
Error: Parse error on line 2:
...--> B{"Is \"Driver\" configured?"}
-----------------------^
Expecting 'SQE', 'DOUBLECIRCLEEND', 'PE', '-)',
'STADIUMEND', 'SUBROUTINEEND', 'PIPE', 'CYLINDEREND',
'DIAMOND_STOP', 'TAGEND', 'TRAPEND', 'INVTRAPEND',
'UNICODE_TEXT', 'TEXT', 'TAGSTART', got 'STR'
Parser3.parseError (node_modules/mermaid/dist/...
✨ Maid Precise Location & Fix 
error[FL-LABEL-ESCAPED-QUOTE]: Escaped quotes (\") in node
labels are not supported by Mermaid. Use " instead.
at diagram.mmd:2:28
  1 | flowchart TD
  2 |     A[Start] --> B{"Is \"Driver\" configured?"}
    |                            ^^
hint: Example: D{"Is "Driver" configured?"}

✨ Auto-Fixed with --fix

flowchart TD
    A[Start] --> B{"Is "Driver" configured?"}

📄 Source Code

flowchart LR
    A[Start --> B
    B --> C
❌ Mermaid-CLI Confusing Token List 
Error: Parse error on line 4:
...t --> B    B --> C
---------------------^
Expecting 'SQE', 'DOUBLECIRCLEEND', 'PE', '-)',
'STADIUMEND', 'SUBROUTINEEND', 'PIPE', 'CYLINDEREND',
'DIAMOND_STOP', 'TAGEND', 'TRAPEND', 'INVTRAPEND',
'UNICODE_TEXT', 'TEXT', 'TAGSTART', got '1'
Parser3.parseError (node_modules/mermaid/dist/...
✨ Maid Exact Issue & Solution 
error[FL-NODE-UNCLOSED-BRACKET]: Unclosed '['. Add a
matching ']' before the arrow or newline.
at diagram.mmd:2:13
  1 | flowchart LR
  2 |     A[Start --> B
    |             ^
  3 |     B --> C
hint: Example: A[Label] --> B

✨ Auto-Fixed with --fix

flowchart LR
    A[Start ]--> B
    B --> C

📄 Source Code

flowchart TD
    A B
❌ Mermaid-CLI Token Soup 
Error: Parse error on line 2:
flowchart TD    A B
------------------^
Expecting 'SEMI', 'NEWLINE', 'EOF', 'AMP',
'START_LINK', 'LINK', 'LINK_ID', got 'NODE_STRING'
Parser3.parseError (node_modules/mermaid/dist/...
✨ Maid Human-Friendly 
error[FL-LINK-MISSING]: Two nodes on one line must be
connected with an arrow before 'B'.
at diagram.mmd:2:7
  1 | flowchart TD
  2 |     A B
    |       ^
hint: Insert --> between nodes, e.g., A --> B.

✨ Auto-Fixed with --fix=all

flowchart TD
    A  --> B
More Examples →

Why Maid Was Created

Making Mermaid more accessible for the AI age

Mermaid Has Become Essential

Mermaid diagrams are everywhere—in documentation, README files, and AI-generated content. Every major LLM knows the syntax. It's become the universal language for text-based diagrams.

But there's been a gap: lightweight validation. The current approach requires a full browser environment (1.7GB with Puppeteer) just to check syntax. We built Maid to fill this gap with a modern, lightweight validator that guarantees your diagrams will render.

🤖

Built for AI

Clear, semantic error messages that AI agents can understand and learn from. Auto-fixes common patterns that AI frequently generates incorrectly.

⚡

Modern Architecture

Built with Chevrotain for fast, flexible parsing. Validation is decoupled from rendering, enabling instant checks without launching browsers.

✅

Render Guarantee

When Maid validates your diagram, it will render. No more "looks correct but fails in production." Our test suite ensures compatibility with actual Mermaid rendering.

Probe Ecosystem

Probe Labs Explore 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.

Questions or feedback? Reach out at hello@probelabs.com