SCXML Editor

The SCXML Editor is a professional visual state machine designer available for Windows, macOS, and Linux. Design complex hierarchical statecharts with an intuitive drag-and-drop interface.

Installation#

Download the installer for your platform:

After installation, the editor appears in your system's application menu.

Quick Start#

1. Launch the SCXML Editor from your applications menu
2. Create states by selecting a state type from the toolbar and clicking on the canvas
3. Connect states with transitions by dragging from one state to another
4. Configure states and transitions in the properties panel on the right
5. Export your design as .scxml to use with the Generator

Features#

Visual Design Canvas#

• Drag & Drop - Create and arrange states visually
• Pan & Zoom - Navigate large diagrams with mouse wheel and middle-click
• Grid Snap - Align states precisely with optional grid snapping
• Auto-Layout - Automatically arrange states with hierarchical layout algorithms
• Minimap - Bird's-eye navigation for complex diagrams

State Types#

Transitions#

• Event-based - Triggered by named events
• Eventless - Execute automatically (spontaneous transitions)
• Conditional - Guard expressions that must evaluate to true
• Internal - Execute actions without exiting/entering the state
• Multi-target - Transition to multiple states simultaneously

Executable Content#

Add actions to state entry, exit, and transitions:

Invoke Support#

Launch child state machines from within a state:

<invoke type="scxml" src="child-machine.scxml" id="child1">
    <param name="input" expr="parentValue"/>
    <finalize>
        <assign location="result" expr="_event.data.output"/>
    </finalize>
</invoke>

Keyboard Shortcuts#

File Operations#

Editing#

View#

Quick Insert (in insert mode)#

Workflow Integration#

The SCXML Editor works seamlessly with the other vscxml tools:

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  SCXML Editor   │────▶│    Simulator    │────▶│    Generator    │
│  (Design)       │     │  (Test & Debug) │     │  (Build Code)   │
└─────────────────┘     └─────────────────┘     └─────────────────┘
        │                                               │
        │            Export .scxml file                 │
        └───────────────────────────────────────────────┘

1. Design your state machine visually in the Editor
2. Test the logic with the Simulator before generating code
3. Generate production code with the Generator

Import & Export#

Exporting Your Design#

• SCXML - W3C-compliant XML format (use with Generator and Simulator)
• SVG - Vector graphics for documentation
• PNG - Raster image for presentations

The Editor preserves layout metadata in the SCXML file, so re-importing restores exact positions.

Importing Existing SCXML#

Open any valid SCXML file. If no layout metadata is present, the auto-layout algorithm arranges states automatically.

Validation#

Click the validation button (Ctrl/Cmd + K) to check your diagram for:

• Errors - Critical issues that would prevent the state machine from running
• Warnings - Best practice violations (unreachable states, undefined events)
• Info - Helpful statistics and suggestions

Results appear in the notification panel at the bottom of the window.

Tips & Best Practices#

1. Name states descriptively - Use meaningful IDs like waitingForPayment instead of state1
2. Use compound states for hierarchy - Group related states to reduce complexity
3. Validate early and often - Catch issues before generating code
4. Export regularly - Save your work in SCXML format for backup
5. Use auto-layout - Let the algorithm organize your diagram, then fine-tune manually

AI Integration (MCP)#

The Editor integrates with AI assistants via the VSCXML MCP Server. When the editor is running, Claude Code and other MCP-compatible tools can:

• Push and pull SCXML documents to/from the editor canvas
• Highlight states with semantic colors (error, warning, success, info)
• Add annotations with conditional visibility
• Add/remove states and transitions programmatically
• Navigate the canvas (center, fit, zoom)
• Export SVG, PNG, or interactive HTML
• Connect to the simulator for live state highlighting during simulation
• Take screenshots of the current diagram

The MCP editor API starts automatically on port 48623 when the editor launches. No additional configuration is needed.

Install the MCP server for Claude Code:

claude mcp add vscxml -- npx -y @vscxml/mcp

Next Steps#

• Simulator Guide — Test your state machine interactively
• Generator Guide — Generate production code
• MCP Setup Guide — AI integration with Claude Code
• Traffic Light Tutorial — Interactive step-by-step example