Stately

See what your software actually does.

Stately is a visual state machine editor and software modeling tool. Map your code into statecharts that humans can see and coding agents can reason about.

Open the editorBook a demo (opens in a new tab)
$ npx statelyai scan

Hosted setup for Claude Code, Codex, Cursor, and VS Code below

Statechart of an example checkout flowExample checkout statechart, simulated on a loop: an order is added, checked out, submitted, declined, cancelled, and then paid. States: idle (initial), cart, address, payment, declined, confirmed (final), refund (unreachable). Transitions: idle on ADD_ITEM to cart; cart on CHECKOUT to address; cart on EMPTY to idle; address on SUBMIT to payment; payment on PAID to confirmed; payment on FAIL to declined; declined on RETRY to payment; declined on CANCEL to cart.ADD_ITEMEMPTYCHECKOUTSUBMITPAIDFAILRETRYCANCELidlecartaddresspaymentdeclinedconfirmedrefund
7 states · 8 transitions · 1 unreachable · example: checkout · state: idle

Connect once. Your agent maps the rest.

The hosted MCP server covers graphs, projects, proposals, comments, and editor work. These graph tools map source, compare behavior, and list paths.

stately mcpstable

terminal

$ claude mcp add --transport http stately https://mcp.stately.ai/mcp

In Claude Code, run /mcp and complete Stately sign-in.

Add the skills with npx skills add statelyai/skills.

MCP URL
https://mcp.stately.ai/mcp
Docs
MCP server · llms.txt

Validate and convert

stable

Find missing targets, unreachable states, and invalid config, then translate between XState, SCXML, Mermaid, and D2.

  • validate_machine
  • convert_machine

Diff and patch

stable

List the states and transitions that changed between two machines, and apply structured edits.

  • diff_machines
  • apply_machine_patches

Paths and simulation

stable

Enumerate paths between states, step a machine through events, and render it as a diagram.

  • generate_graph_paths
  • simulate_machine
  • visualize_machinebeta

Extract and review

beta

Extract machines from source and compare a model with implementation evidence.

  • extract_machines_from_code
  • review_machine_implementation

Agents write code faster than anyone can review it.

A diff shows which lines moved. It doesn't show that refund can no longer be reached, or that RETRY now loops back into payment.

PR #4821 · checkout retrysrc/checkout.ts+4 −4

Fig 1: Excerpt of src/checkout.ts. 8 lines changed.

same change, as behaviorrefund unreachable
The same PR as a statechartThe checkout statechart after the PR. States: idle (initial), cart, address, payment, declined, confirmed (final), refund (unreachable: no transition leads to it). Transitions: idle on ADD_ITEM to cart; cart on CHECKOUT to address; cart on EMPTY to idle; address on SUBMIT to payment; payment on PAID to confirmed; payment on FAIL to declined; declined on RETRY to payment (added in this PR); declined on CANCEL to cart. Removed in this PR: declined on REFUND to refund.ADD_ITEMEMPTYCHECKOUTSUBMITPAIDFAILRETRYCANCELREFUNDidlecartaddresspaymentdeclinedconfirmedrefund

Fig 2: The same PR as a graph. refund can no longer be reached.

How an agent's change gets reviewed.

Map behavior, review a proposed change, and compare the implementation with the model.

review

Mapped

A model of the code, with source citations for observed behavior.

statechart + source hash

Proposed

A proposed edit to the graph, made in the editor or over MCP.

proposed change

Approved

A reviewer examines the proposed change and approves it.

review + approval

Implemented

The approved edit, written into the source.

commit

Verified

The implementation is compared with the approved model.

review findings

CI gate

The diff command can fail a build when machine semantics change.

$ statelyai diff <base> <head> --fail-on-changes
no changeschanges

What we test

We run Claude Code and Codex through map, edit, and apply. Changes can include citations to their source. MCP docs

Runs over MCP, with the CLI for scan, push, pull, and diff. The editor is optional, and so is XState in your code.

Try it live.

The editor in viewing mode, on the checkout machine. Run a simulation, step through events, open the command palette, and find the unreachable state.

Loads editor.stately.ai in a frame

Try it on your own code.

Open the editorBook a demo (opens in a new tab)

Understand the whole system.

system

Storefront

Next.js

Checkout

Node service

Orders

Postgres

Payments

Node service

Email

Queue

Architecture view. Components: Storefront (Next.js), Checkout (Node service), Orders (Postgres), Payments (Node service), Email (queue). Relationships: Storefront sends ORDER to Checkout; Checkout writes Orders; Checkout sends CHARGE to Payments; Payments sends RECEIPT to Email.

Architecture

Map how services, actors, and machines connect. Import C4, Structurizr, D2, or Mermaid, or let the agent draw the project from source.

The editor

The editor inspecting a running checkout actor. The payment state is active with a double outline; the CHECKOUT transition it just took is highlighted. The inspection panel shows state payment, context orderId order-42, items 3, total 4200, the CHECKOUT event, and the actions reserveInventory and startPayment.

Inspection

Attach to a running app and watch states, events, and actors as they happen. Sequence diagrams show who sent what to whom.

Inspector

Payment statechart in the editorPayment statechart. States: payment (initial), declined, confirmed (final). Transitions: payment on PAID to confirmed; payment on FAIL to declined; declined on RETRY to payment.PAIDFAILRETRYpaymentconfirmeddeclined
states: {
  declined: {
    on: { RETRY: 'payment' },
  },

Edit in either direction

Change the diagram and the source changes. Change the source and the diagram follows. In the editor, in VS Code, or through your agent.

VS Code extension

Connect behavior across your stack.

Stately imports supported machine, store, workflow, and diagram formats into one graph model. Conversion and write-back depend on the format; the graph can also drive test paths and inspection.

The graph model can represent behavior from these sources and outputs:

  • Libraries: XState, XState Store, Redux, Zustand
  • Workflow and agent runtimes: LangGraph, Inngest, Restate
  • Diagram and model formats: Mermaid, SCXML, D2
  • Outputs: Test paths, Running app, TypeScript

With Inngest, Restate, and LangGraph, Stately reads the workflows you already run and models the behavior around them. It sits above those runtimes and does not replace them.

See it on a running app.

Open the editorBook a demo (opens in a new tab)

Built on XState.

The open-source state machine library under every Stately diagram. It runs the machine you reviewed, in the browser or on Node, MIT licensed.

npm downloads a week
3.2M+
GitHub stars
30K+
repositories depend on it
338K+
years in production
10
installstable
$ npm install xstate

For multi-step flows, async orchestration, retries and timeouts, and any behavior that must be reviewed.

ReactVueSvelteSolid
inspector

Inspect a running XState app.

Attach the inspector to a running app and watch states, events, and actors as they happen.

Open the inspector docs

xstate 5 · xstate/graph · @xstate/store · xstate 6 beta

XState naturally separates the logic and makes it simple to mock out API calls, so it's easier to test the code and organize it!
Presley PizzoCoder

XState is used by engineers at

We use XState to implement business workflows as statecharts. The visualizer helps us collaborate more closely with customers, the ability to externalize workflows as JSON configuration makes complex workflow changes surprisingly simple to roll out, and test case generation makes it easier than ever to move forward with confidence. XState makes it all possible!
James TharpeT-Mobile

Start free.

Community is the editor, simulation, and code export. Pro adds private projects, codebase sync, and test paths. Team shares all of it with up to 10 people. Enterprise runs where you need it to.

PlanFeaturesPrice
Community
  • Public projects and machines
  • Editor, simulation, and code export
  • 200 AI credits a month
$0
Pro
  • Unlimited private and unlisted projects
  • Codebase sync via GitHub, CLI, SDK, or MCP
  • Test path generation and locked machines
  • Version history and live simulation
  • 1,000 AI credits a month
$39 / mo$33 / mo billed yearly
Team
  • Everything in Pro for up to 10 people
  • Shared team projects
  • 4,000 shared AI credits a month
  • Admins, editors, and unlimited viewers
$199 / mo$167 / mo billed yearly
Enterprise
  • Cloud or self-hosted, custom server locations
  • SSO and audit logs
  • Custom export formats and effect collections
  • Embed Stately in your own apps
  • Dedicated priority support
Book a demo (opens in a new tab)
Start freeSee pricing

Enterprise-ready.

Self-host it, sign in through your identity provider, and keep the model inside your boundary.

  • Self-host the editor on your own network. No database required.
  • Sign in through your identity provider: an SSO proxy or your OAuth issuer.
  • Turn AI off with one flag. No traffic leaves your network.
  • The same REST API and MCP endpoint on your host.
  • Commercial license, with MIT-licensed SDK and CLI.
self-hosted
AI_ENABLED=false
# hosted comments off
# no traffic leaves your network

What an audit gets

  • Versioned behavior records
  • Immutable proposals with review trail
  • Verify verdicts
  • SCXML export
Book a demo (opens in a new tab)Self-hosting guide

Questions.

Start with what a state machine is, then explore state machines and statecharts, state chart examples, and the actor model.

What is a state machine?

A state machine models behavior as states and transitions between them. Events can trigger transitions, changing the current state. Statecharts extend state machines with nested states and parallel regions for concurrent behavior.

Does Stately replace my workflow runtime?

No. Temporal, Inngest, Restate, and LangGraph keep running your workflows. Stately models and analyzes the behavior they run.

Do I need XState?

No. Stately maps existing code from many libraries and formats, and can capture behavior from a running app. Use XState when you want to execute the model directly.

Does my code leave my network?

With the hosted service, the code you send is processed under the Stately privacy policy. With self-hosted Stately, and AI features and hosted comments turned off, no traffic leaves your network.

What does my agent actually do with Stately?

It can map code into a statechart with cited evidence, propose graph changes, and compare a model with implementation evidence. People can review the resulting changes.

Where are the machine-readable docs?

Start with /llms.txt and /llms-full.txt. Docs pages are available as markdown by adding .mdx to the URL. The MCP server is at https://mcp.stately.ai/mcp, and npx skills add statelyai/skills installs the agent skills.

machine-readable
  • /llms.txtSite summary for agents
  • /llms-full.txtFull docs as plain text
  • https://mcp.stately.ai/mcpHosted MCP server
  • claude mcp add --transport http stately https://mcp.stately.ai/mcpAdd the MCP server to Claude Code
  • codex mcp add stately --url https://mcp.stately.ai/mcpAdd the MCP server to Codex
  • {"mcpServers":{"stately":{"url":"https://mcp.stately.ai/mcp"}}}Cursor: .cursor/mcp.json
  • code --add-mcp '{"name":"stately","type":"http","url":"https://mcp.stately.ai/mcp"}'Add the MCP server to VS Code
  • npx statelyai scanFind the machines in a repo
  • npx skills add statelyai/skillsAgent skills
  • /docs/packages/mcp.mdxMCP docs as markdown
  • https://github.com/statelyai (opens in a new tab)Source

Map your first repo.

$ npx statelyai scan
Open the editorBook a demo (opens in a new tab)