StateSmith: generating state machine code so the diagram stays the source of truth

The problem is a diagram that rots away from the code

The author starts from a specific frustration rather than from a feature list. Before StateSmith, keeping a hand written state machine synchronized with a drawing was always a pain. Urgent client requests come in and the code is updated, but nobody remembers to update the drawing, and the rot begins. Documentation trust issues arise, and as designs get larger, keeping the diagram accurate becomes punishing.

StateSmith's answer is to make the diagram the input. You draw the state machine, the tool generates the code, and the two cannot silently diverge because there is only one of them. The author describes generating fully working code from the documentation, and calls it especially helpful for teams and for talking with clients.

That framing matters for who should adopt it. This is a code generator for a specific artefact, the state machine, and the audience is anyone whose application logic has a stateful shape. The project description says it is suitable for bare metal, embedded and more, and the documentation site for interactive examples, the fundamentals-1 page, lets you explore most of the features in a browser without installing anything. There is also a separate StateSmith-examples repository with a growing list of application uses, and a note that other companies are using it in production, in consumer electronics and autonomous vehicles among other fields.

A cross platform generator written in C# with an antlr grammar

StateSmith is a cross platform, free and open source tool for generating state machines in multiple programming languages, and the implementation is C#. The repository layout is small at the top level: a src directory for the tool, an antlr directory, a docs directory, an examples directory and the usual project files, with a CHANGELOG.md and a CONTRIBUTING.md.

The antlr directory is worth noting for anyone planning to extend the tool. ANTLR is a parser generator, and having one in the tree tells you the diagram syntax is handled by a generated grammar rather than by ad hoc string matching. That matters because the two front ends the project documents, PlantUML and draw.io, do not share a file format, so the tool needs a way to get from each of them to a common internal model. The repository lists a Multiple-Language-Support plan as the author's current plan, and the author notes it is tricky and invites contributors to help add a new language.

The output side is what the plan refers to. The generated code is described as human readable, with zero dependencies, and it avoids dynamic memory allocations for the safety or performance inclined. Those two properties are the reason the project targets tiny bare metal microcontrollers, and they are also the properties that distinguish it from generators that emit a runtime library you must link and carry.

The spec integration tests compile and run the generated code

The strongest claim in the project is about testing, and it is specific enough to be checked. StateSmith has a suite of tests with 730 or more cases and behavior specification coverage. The specification integration tests read a diagram file, generate executable state machine code, then compile and execute that code in another process and ensure that the state machine behavior is exactly what was expected.

The same suite of integration tests runs for each supported programming language. That is the sentence that carries the weight, because it means the guarantee of matching behaviour is not per language but shared across all of them. It also gives the author a stated reason for confidence, and permission to refactor and optimize the generator without fear of accidentally breaking specified behavior.

For a user of the tool, this shapes what you should expect from a release. A bug fixed in one language's output path is a bug fixed for every language, because the check is the same check. A behaviour that has no specification test is a behaviour that can change between versions, which is worth knowing when you are pinning a version for an embedded product where a recompile is expensive.

PlantUML and draw.io as the two diagram front ends

StateSmith does not impose a diagram editor of its own. The quick start points at two tutorial repositories that use different diagram tools and mirror each other fairly closely otherwise. Tutorial-3 is built around PlantUML with the CLI and text lessons, and Tutorial-4 uses draw.io with the CLI plus text lessons and a video series. Older lessons are collected in the wiki under Learning-Resources.

The two tutorials are listed in the project's quick start, each naming its diagram tool, the CLI and the kind of lessons it carries:

- [Tutorial-3](https://github.com/StateSmith/tutorial-3) - `PlantUML` `CLI` `text lessons`

Both routes run through the command line, which is the important detail. The tutorials are described as using new StateSmith features that are more user friendly, and the CLI is the common interface between the diagram tool and the generator. A diagram tool you already use can stay in place, and the diagram file itself becomes the input the generator reads.

This also explains the testing design. The specification integration tests read a diagram file, generate code, then compile and run it. The diagram file is the stable, reviewable artefact in that pipeline: a change to behaviour shows up as a diff in a diagram, not as a diff in generated code, and a diff in a diagram is something a human can actually assess.

The cost of this design is a dependency on your diagram tool's file format. A PlantUML state diagram is text, so it diffs and merges well. A draw.io file is a graph of XML. Neither is a problem in practice for a single maintainer, but it is a factor in a team where several people edit the same model, and the project does not document a merge strategy for concurrent diagram edits.

Where StateSmith is the wrong tool

There is a version problem, and it is the first thing to look at. The recent release history shows v0.22.2, then v0.22.1-alpha-1 and v0.22.0-alpha-1 a month earlier. A 0.x version line with alpha builds still appearing in the history is a signal that the generated API and the tool's own configuration surface are still moving, and the author is candid that the multi-language support is a plan in progress rather than a finished matrix.

So StateSmith is the wrong tool if you need a stable public API to depend on, if you are generating code for a fleet of devices where a change in the generated output requires a coordinated firmware update, or if you need a language that is not yet on the list. It is also the wrong tool for a state machine so small that a switch statement and a comment would do, since the setup cost of a diagram, a generator run and a build pipeline is real.

The scope limit is explicit in the source. The project is described as suitable for bare metal, embedded and more, and the generated code avoids dynamic memory allocations, which is a feature for embedded and a constraint for a large application that expects a general purpose allocator. Anyone moving to a mainstream managed environment is trading one property away for another and should decide which matters.

Finally, the author states the reason for the project plainly: they could not find a quality state machine code generator that met their needs, had an attractive license and was enjoyable to use. That is a strong signal about the code, and a weak one about the surrounding ecosystem, since it means the alternative tools each failed on some part of that combination.

The licence is the reason it works for closed source products

The licence field on the repository says Apache-2.0, and that choice is doing real work in the project's story. A state machine generator emits source code that gets compiled into a product, often a product sold with closed source firmware, and permissive terms matter for that. The author's own reason for building StateSmith lists having an attractive license as one of the three criteria, alongside quality and being enjoyable to use.

For a commercial embedded product, Apache-2.0 means the generated code can be shipped in a closed binary without a source disclosure obligation, though the licence file itself carries the standard set of conditions that whoever handles licensing in your organisation should read rather than rely on a summary.

On maintenance, the last push to the repository was on 2026-05-11, and the release published the same day is v0.22.2. The repository is not archived, and there is a public Discord invite, a GitHub issue tracker and a discussions space for questions, along with a YouTube channel. The wiki holds most of the documentation. Between the active channel, the 730 plus test suite and the fact that the project is used in production, the risk of the tool disappearing is low, while the risk of the generated API shifting within the 0.x line is high.

Editorial conclusion

StateSmith fits teams whose state machine logic is currently hand written in a switch statement and whose diagram is already drifting from the code, particularly on embedded targets where a dependency free generated file is a requirement. It does not fit a project that needs a stable public API today, because the version line is still 0.x with alpha builds in the recent history. Verify first which version of StateSmith your diagram parses under, since v0.22.1-alpha-1 and v0.22.0-alpha-1 sit alongside the stable v0.22.2, and confirm the target language appears in the project's list of supported outputs before designing around the generated code shape.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. StateSmith/StateSmith on GitHub