Mermaid Collab

A Claude Code plugin that provides a real-time collaboration UI, 150+ MCP tools, and structured workflows for designing and building software with Claude.

What is Mermaid Collab?

Mermaid Collab gives Claude Code a persistent collaboration layer — a browser UI where diagrams, documents, designs, code snippets, and spreadsheets appear in real time as Claude works. It also includes a full browser automation suite (Chrome via CDP) and a pseudocode documentation system.

Key capabilities:

Collab UI — React interface with live preview of all artifacts
Visual Design Editor — Figma-like canvas with layers, properties, and component system
Browser Automation — Drive real Chrome on Windows via CDP tunnel (27 tools)
Pseudocode System — File-level documentation with call graphs and coverage
30 Skills — Orchestrated workflow patterns for vibe sessions, planning, debugging, and review
VSCode Extension — Status bar integration with one-click Chrome CDP toggle

Quick Start

1. Install the Plugin

/plugin install ben-mad-jlp/claude-mermaid-collab

2. Start the Server

bun run bin/mermaid-collab.ts start

The API server runs on http://localhost:9002 and the UI at http://localhost:9102.

3. Start a Session

/collab

Server Ports

Service	Port	Description
API + WebSocket + MCP	9002	REST API, WebSocket, MCP HTTP transport
UI	9102	React frontend (dev mode via Vite)
CDP	9333	Chrome DevTools Protocol (Windows Chrome via SSH tunnel)

Collab UI

Access at http://localhost:9102 after starting the server.

Split-pane editors with live preview for diagrams, documents, snippets, and spreadsheets
Visual design editor with layers panel, properties panel, and component library
Terminal integration (tmux sessions)
Session browser with project grouping
Real-time WebSocket updates across all open tabs

Visual Design Editor

A canvas-based design tool for creating UI mockups and design systems.

Features:

Freeform canvas with zoom and pan (middle-drag, Alt+drag, Shift+scroll)
Layers panel for node hierarchy
Properties panel for size, position, color, text, and style
Component system with instances and detach
Design tokens
Page-based layouts
Export to SVG and PNG
Version history with revert

Tools available: 40+ MCP tools for programmatic design creation and editing.

Browser Automation (CDP)

Claude can drive a real Chrome browser on your Windows machine via SSH tunnel. The VSCode extension manages Chrome launch and tunnel setup with one button.

Setup:

Install the VSCode extension (mermaid-collab-vscode)
Click the CDP button in the status bar — Chrome launches with remote debugging on port 9333, tunneled to the Linux dev server

27 browser tools:

Category	Tools
Navigation	`browser_open`, `browser_navigate`, `browser_list_pages`, `browser_select_page`, `browser_close`
Interaction	`browser_click`, `browser_fill`, `browser_fill_form`, `browser_type_text`, `browser_drag`, `browser_hover`, `browser_press_key`, `browser_select`, `browser_upload_file`, `browser_handle_dialog`
Inspection	`browser_screenshot`, `browser_take_snapshot`, `browser_evaluate`, `browser_get_url`, `browser_wait_for`
Diagnostics	`browser_console`, `browser_network`, `browser_take_memory_snapshot`, `browser_emulate`, `browser_resize_page`, `browser_lighthouse_audit`, `browser_performance_analyze_insight`

Pseudocode System

A file-level documentation layer stored in a SQLite database (.collab/pseudo/). Claude scans source files, writes prose descriptions of functions and modules, and maintains call graphs and coverage metrics.

Key tools: pseudo_hot_files, pseudo_search, pseudo_find_function_v6, pseudo_call_chain_v6, pseudo_coverage_report, pseudo_upsert_prose_v6, pseudo_import_graph, pseudo_impact_analysis

MCP Tools Reference

All tools are available to Claude Code via HTTP MCP at http://localhost:9002/mcp.

Session & Project

check_server_health, list_sessions, list_projects, register_project, unregister_project, generate_session_name, register_claude_session, archive_session, clear_session_artifacts, generate_session_summary, validate_session_links

Diagrams

create_diagram, update_diagram, patch_diagram, get_diagram, list_diagrams, delete_diagram (via deprecate), validate_diagram, preview_diagram, export_diagram_svg, export_diagram_png, transpile_diagram, diagram_from_code, get_diagram_history, revert_diagram

Documents

create_document, update_document, patch_document, get_document, list_documents, delete_document, preview_document, get_document_history, revert_document

Designs (40+ tools)

create_design, update_design, get_design, list_designs, delete_design, add_design_node, update_design_node, get_design_node, remove_design_node, list_design_nodes, batch_design_operations, group_design_nodes, ungroup_design_nodes, duplicate_design_nodes, align_design_nodes, transform_design_nodes, reorder_design_nodes, create_design_from_tree, add_design_image, set_node_image, export_design_svg, export_design_png, export_design_code, describe_design, describe_design_changes, lint_design, annotate_node, get_annotations, remove_annotation, create_component, create_instance, detach_instance, list_components, save_component, load_component, list_library_components, create_design_tokens, apply_design_tokens, create_from_template, design_to_diagram, get_design_history, revert_design, get_design_item, patch_design_item

Snippets

create_snippet, update_snippet, patch_snippet, get_snippet, list_snippets, delete_snippet, export_snippet, snippet_history, revert_snippet

Spreadsheets

create_spreadsheet, update_spreadsheet, patch_spreadsheet, get_spreadsheet, list_spreadsheets, delete_spreadsheet, export_spreadsheet_csv, get_spreadsheet_history, revert_spreadsheet

Images & Embeds

create_image, get_image, list_images, delete_image, create_embed, list_embeds, delete_embed, create_storybook_embed, list_storybook_stories

Terminal

terminal_create_session, terminal_list_sessions, terminal_kill_session, terminal_rename_session, terminal_reorder_sessions

Tasks & Workflow

get_task_graph, sync_task_graph, update_task_status, update_tasks_status

Session Todos

add_session_todo, list_session_todos, update_session_todo, toggle_session_todo, remove_session_todo, clear_completed_session_todos, reorder_session_todos

AI UI

render_ui, update_ui, get_ui_response, request_user_input, dismiss_ui

Utilities

get_install_path, consult_grok, deprecate_artifact, set_artifact_metadata, add_lesson, list_lessons, generate_session_name

Skills (30)

Skills are markdown instruction files loaded on-demand by Claude Code.

Skill	Purpose
`collab`	Entry point — session management
`vibe-active`	Freeform collab session
`vibe-checkpoint`	Save vibe state before `/clear`
`vibe-read`	Read current vibe instructions
`vibe-agents`	Toggle agent dispatch mode
`vibe-go`	Launch agents in dependency waves
`vibe-review`	Bug and completeness review
`vibe-blueprint`	Generate task graph from artifacts
`collab-todo`	Pick a session to work on
`writing-plans`	Create implementation plan
`writing-skills`	Create or edit skills
`executing-plans-review`	Verify implementation against design
`executing-plans-bugreview`	Bug review before completion
`test-driven-development`	RED-GREEN-REFACTOR workflow
`requesting-code-review`	Submit work for review
`receiving-code-review`	Handle incoming review feedback
`systematic-debugging`	Root cause analysis
`pair-mode`	Toggle pair programming mode
`pair`	Before/after diagram approval workflow
`dispatching-parallel-agents`	Parallel independent task agents
`pseudocode`	Create/update pseudocode for a file
`pseudocode-seed`	Seed pseudocode across hot files
`wireframing`	Create designs with MCP tools
`mermaid-collab`	Create diagrams and designs
`consult-grok`	Second opinion from Grok (xAI)
`ui-question`	Ask user a question via browser UI
`using-superpowers`	Establish skill/tool usage patterns

Architecture

┌─────────────────────────────────────────────────────┐
│                 Collaboration Server                 │
│                     port 9002                        │
├──────────────┬──────────────┬────────────────────────┤
│  REST API    │  WebSocket   │  MCP HTTP Transport    │
├──────────────┴──────────────┴────────────────────────┤
│  DiagramManager │ DocumentManager │ DesignManager    │
│  SnippetManager │ PseudoDB        │ TerminalManager  │
└─────────────────────────────────────────────────────┘
         ↓                    ↓
  React UI (9102)      Claude Code (MCP)
                              ↓
                    chrome-devtools-mcp
                    (CDP → port 9333)
                              ↓
                  Chrome on Windows (via SSH tunnel)

Session storage:

/your/project/
└── .collab/
    ├── sessions/
    │   └── <session-name>/
    │       ├── documents/
    │       ├── diagrams/
    │       ├── designs/
    │       ├── snippets/
    │       ├── spreadsheets/
    │       ├── images/
    │       └── embeds/
    └── pseudo/          # Pseudocode SQLite DB

VSCode Extension

The mermaid-collab-vscode extension adds:

Status bar showing collab server connection state
CDP toggle button — launches Chrome with --remote-debugging-port=9333 and creates an SSH reverse tunnel so the Linux dev server can reach Windows Chrome

Install the .vsix from extensions/vscode/.

Development

# Start everything (recommended)
/srv/codebase/dev-tools/dev-start.sh

# Or manually
bun run dev          # API server + Vite UI in parallel
bun run dev:api      # API only (port 9002)
bun run dev:ui       # Vite only (port 9102)

# Server daemon
bun run server:start
bun run server:stop
bun run server:status

# Tests
npm run test:ci           # All UI tests
npm run test:ci -- path   # Specific test file
npm run test:backend      # Backend tests

Versioning — always use npm version patch|minor|major (never edit version numbers manually). The version hook syncs package.json, plugin.json, marketplace.json, and server.ts automatically.

License

MIT

Name	gather-session-goals
Description	Collect and classify work items at the start of a collab session. Invoked by collab skill after creating a new session.

gather-session-goals

SKILL.md