VSCXML Simulator

The VSCXML Simulator is an interactive terminal-based REPL for testing and debugging state machines. Available for Windows, macOS, and Linux, it lets you step through state transitions, send events, inspect variables, and record execution traces.

Installation#

Download the installer for your platform:

After installation, the simulator appears in your system's application menu as VSCXML Simulator.

Quick Start#

1. Launch the VSCXML Simulator
2. Load an SCXML file: scxml-simulator myfile.scxml
3. Start the state machine: type start
4. Send events: type send myevent
5. Observe state changes in the Active States panel

User Interface#

The simulator displays a three-panel terminal interface:

┌─────────────────────────────────────────────────────────────────────┐
│ VSCXML Simulator v0.1.0                                             │
├────────────────────────────────────┬────────────────────────────────┤
│ * Active States                    │ # Variables                    │
│ ─────────────────                  │ ─────────────────              │
│   main                             │ counter: 5                     │
│     └─ running                     │ status: "active"               │
│         └─ processing              │ items: [1, 2, 3]               │
├────────────────────────────────────┴────────────────────────────────┤
│ ! Event Log                                                         │
│ ────────────────────────────────────────────────────────────────────│
│ [10:23:45.123]  session_start: datamodel=ecmascript                 │
│ [10:23:45.125]  state_enter: main                                   │
│ [10:23:45.126]  state_enter: main.idle                              │
│ [10:23:47.456]  event_received: start                               │
│ [10:23:47.458]  transition: main.idle → main.running                │
├─────────────────────────────────────────────────────────────────────┤
│ > _                                                        RUNNING  │
└─────────────────────────────────────────────────────────────────────┘

Panels#

Commands#

Session Control#

Execution Control#

Sending Events#

Examples:

> send button_pressed
> send login {"username": "admin", "password": "secret"}
> send timeout

Inspection#

Variable Manipulation#

Values are auto-parsed:

• set counter 5 → integer
• set flag true → boolean
• set name "Alice" → string
• set items [1,2,3] → array

Watch Settings#

Control what information is displayed in real-time:

Trace Recording#

Record execution traces to JSONL files for later analysis:

WebSocket Server#

Start a WebSocket server for external tool integration:

Help#

Execution Modes#

Command-Line Usage#

# Load and start interactive REPL
scxml-simulator traffic.scxml

# Start with trace recording
scxml-simulator traffic.scxml --trace execution.jsonl

# Start with WebSocket server
scxml-simulator traffic.scxml --serve 8888

Command-Line Options#

Event Log Format#

The Event Log displays timestamped entries:

Trace File Format#

Traces are recorded in JSONL format (one JSON object per line):

{"timestamp":1704567890123456,"type":"session_start","datamodel":"ecmascript"}
{"timestamp":1704567890123500,"type":"state_enter","state_id":"main"}
{"timestamp":1704567890124000,"type":"event_received","event":"start","data":{}}
{"timestamp":1704567890124100,"type":"transition","source":"idle","target":"running","event":"start"}
{"timestamp":1704567890124200,"type":"variable_changed","var":"counter","old":0,"new":1}

Trace Fields#

WebSocket Integration#

The WebSocket server enables integration with external tools like the Visual Editor.

Starting the Server#

> serve 8888
WebSocket server started on port 8888
Connect at: ws://localhost:8888

Message Protocol#

Client → Server:

{"type": "send_event", "event": "button", "data": {}}
{"type": "pause"}
{"type": "resume"}
{"type": "step"}

Server → Client (broadcasts):

{"type": "state_update", "active": ["main", "main.running"]}
{"type": "transition_fired", "source": "idle", "target": "running"}
{"type": "variable_changed", "var": "counter", "value": 5}

Example Session#

$ scxml-simulator traffic-light.scxml

VSCXML Simulator v0.1.0
Type 'help' for commands, 'start' to begin

> start
[10:00:00.001]  session_start: datamodel=ecmascript
[10:00:00.002]  state_enter: red

> state
Active states: [red]

> send timer
[10:00:05.100]  event_received: timer
[10:00:05.101]  transition: red → green
[10:00:05.102]  state_exit: red
[10:00:05.103]  state_enter: green

> vars
counter: 1
cycle_count: 0

> set counter 10
counter = 10

> send timer
[10:00:10.200]  event_received: timer
[10:00:10.201]  transition: green → yellow

> history
1. session_start
2. state_enter: red
3. event: timer → transition: red → green
4. event: timer → transition: green → yellow

> quit
Goodbye!

Datamodel Support#

The simulator supports multiple datamodels:

Workflow Integration#

The Simulator bridges design and code generation:

┌─────────────────┐          ┌─────────────────┐
│  SCXML Editor   │────────▶│    Simulator    │
│  (Design)       │  .scxml  │  (Test & Debug) │
└─────────────────┘          └────────┬────────┘
                                      │
                             All tests pass?
                                      │
                                      ▼
                             ┌─────────────────┐
                             │    Generator    │
                             │  (Build Code)   │
                             └─────────────────┘

1. Design in the Editor
2. Test thoroughly in the Simulator
3. Generate code with the Generator only after validation

Tips & Best Practices#

1. Use watch commands to focus on relevant information during debugging
2. Record traces for complex debugging sessions or regression testing
3. Use step mode to carefully examine transition behavior
4. Check scheduled to see pending delayed events
5. Use set to test edge cases by modifying variables directly

AI Integration (MCP)#

The Simulator is also accessible via the VSCXML MCP Server, enabling AI assistants to run simulations, send events, record traces, and inspect state — all programmatically.

Key MCP tools for simulation:

• scxml_sim_start — Load and start a simulation session
• scxml_sim_send — Send an event and get the trace
• scxml_sim_scenario — Run a batch of events (most useful for testing)
• scxml_sim_timed_scenario — Run events with delays (for <send delay="..."/> machines)
• scxml_trace_embed — Save execution traces into the SCXML document

Install the MCP server for Claude Code:

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

Next Steps#

• Editor Guide — Design state machines visually
• Generator Guide — Generate production code
• MCP Setup Guide — AI integration with Claude Code
• Traffic Light Tutorial — Interactive step-by-step example