Show HN: Statewright – Visual state machines that make AI agents reliable

Thanks for digging deeper and I'm happy to clarify all three aspects:

Re: Reproducing the results: the engine, agent crate and demo TUI are all in the repo. If you have ollama running with a 13B+ model, task run:bugfix reproduces the simple bugfix result end to end. What isn't published yet is the SWE-bench experiment harness (task selection, patch scoring, control runs). I need to get that out, I prioritized the end-to-end simple Claude Code plugin for the launch. The demo crate (crates/demo) contains a demo TUI which calls ollama and runs the bugfix state machine interactively with code.

Re: Engine: The core engine (crates/engine/) is the pure Rust state machine evaluator. It's what Statewright is running on the backend. JSON in => transition decisions out. Agent (crates/agent/) builds on top of it to make it useful for LLMs. That all is Apache 2.0 with no restrictions.

Re: the Patent: The patent covers the method of using state machines to constrain LLM agent tool access at the protocol layer. It's defensive, it helps protect the managed service and the idea from "being scooped" from a larger company with more personnel and resources. It's not targeted against solo developers, self-hosters or researchers.

You'll find that the portions that I've released FSL 1.1 have explicit grants which do not restrict solo developers or single team self-hosting. The code released this way becomes Apache 2 in exactly 3 years. This is not unlike what Sentry and MariaDB did. I am planning on releasing more portions as FSL 1.1, I just hadn't crossed that bridge and honestly this thing seems to have gotten popular at the moment so I thought I'd set the record straight a bit

The not-quite-Apache-2 "Fair Source License, Version 1.1, ALv2 Future License" (https://github.com/getsentry/fsl.software/blob/main/FSL-1.1-...) includes the Apache 2 patent grant. That grants you conditional permission to use the software in ways that would, without the grant, infringe upon their patent. One of the conditions is that you may not make a claim against any party that the software infringes upon any patent, or else your patent grant is terminated.

Unfortunately, the license actually in the repo is not even a not-quite-Apache-2 license. It doesn't appear to be FSL-1.1-ALv2 at all: https://github.com/statewright/statewright/blob/main/plugins.... This notably does not include the patent grant, which makes it unclear whether use of the software would infringe upon the patent.

[flagged]

I feel you on how sluggish Claude Code can be, you just never know what those pulsing prompts are doing in the background...

Given Statewright plugs into Claude Code, there is a little added overhead while managing the state machine logic, but for complicated workflows if it saves you a few debug loops, mass edit reversions or death spirals I think the case can be pretty solid for including it

Great question... and there are two answers depending on what you were originally referring to:

re: Claude Code... we actually don't filter or modify the tool list so all tools stay visible -- disallowed calls get blocked at execution time with an error message. No cache busts on transitions, the model sees the full tool sets. The cost there is prompt caching dollars not latency I suppose

re: The research (Rust agent + Ollama) the model only receives tool schemas for the current states' allowed tools. Ollama does have a KV cache reuse facility so changing the tool list busts that cache. Depending on your workflow this can happen as many times as you expect your states to transition until completion. For simple workflows this is 3-5x. Within each state the tool list is stable and cache operates normally. Presenting fewer tools instead of dozens on every agent processing step reduces input tokens and decision complexity, which is where the measurable gains come from.

Both enforce the same constraints depending on the execution interface. The schema level filtering in the research is the S-tier approach. Adding tools/list filtering to the MCP gateway would be beneficial if possible (it looks like we could only filter MCP tools not core ones, which could provide tangible benefit. I've added this evaluation to the roadmap.

bingo! and that's where this journey began, it's been fun proving it out ^_^

[dead]

you're hitting the nail on the head... rules in prompts are suggestions the model can rationalize away.

"the task is so simple that maybe I don't need worktrees" is the model overriding your intent with its own judgement and that's a pattern I'm seeing more and more as these models mature. statewright provides the guardrails... strong suggestions up front on what it can do in X state via injection and if it still wants to try and outsmart that, it gets hit in the post hook and the model gets the message "oh, you're right I shouldn't do it that way" ... instead of you course correcting, it's the state machine

to your first question: the engine is Apache 2.0 and runs locally. the managed service adds the visual editor, run history and plugin install. the enforcement itself doesn't require the cloud, I run the exact same engine on the backend

the MCP server is just the way to get statewright in the hands of a wide array of existing use cases, claude code included. not all agentic clients are created equal and Pi is actually the experience I want to hone next (also the most extensible)

> example I have rules when using Pi to ask main agent to dispatch implementer agents in parallel using git worktrees. Some time it uses git worktrees, sometimes no

I've taken the approach that whenever this happens, it's my fault. The instructions were not clear enough, not direct enough, or more often, there's just too many of them.

I'm now at the point where my pi system prompt + agents + skills + tools starts out at just 7k context. It's all very clear and concise. I almost never have ambiguous responses like this, at least not bear the start of a session.

Combined with instructions to keep the main session as a coordinator and use subagents for all non trivial work, I can get a lot of work done before hitting 100k context and basically never go over 150k.

It's a stark contrast with Claude code where I was starting at about 35k context even after trimming my stuff down. It's hardly surprising if an agent doesn't know what to do if you dump 30k+ of context with all kinds of rules and workflows, most of them unrelated to the current tasks, before you even do anything.

I feel you on the Claude pulsing thing. Running (or trying to) run Opencode with any model I could throw at it to perform useful work like the frontier/proprietary models do (a tall order I know) is where I started. everyone makes the problem bigger (massive contexts, massive number of parameters, more transformers (MoE)) but I started with how can we make small/local LLMs perform better (do more with less)

Opencode's plan/build is decent, like it is in Claude Code... state machines are the next evolution. model agnostic, tooling agnostic (where feasible)

The workflow definition is intentionally simple... the enforcement layer handles the mechanics however the model gets more context than just "you're in <xyz> mode now"

Each state has an `instructions` field for phase specific guidance and when an agent's action (tool call) gets rejected the error message lets the model know what went wrong, and what's available to move forward

Tool 'Edit' is not available in the 'planning' phase. Allowed Tools: Read, Grep, Glob To advance, call statewright_transition with READY -> implementing

Models (even simple ones) tend to reason through these error messages, adjusting their approaches as opposed to retrying the blocked call. Additionally, on transitions the model is required to include a rationale explaining why it's transitioning (`data.rationale`) which creates an audit trail of the agent's reasoning at each phase boundary. That ends up being one of the most useful parts of the run history viewable on statewright.ai

yeah... I wanted the smaller models to behave more like their state of the art siblings and was a little shocked that it just didn't work well... so I made small models work better. Having the larger models work better was just an added benefit

the colors are based on the event name.... green for happy path events (READY, DONE, PASS), red for failure events (FAIL, ERROR) and purple for everything else

they don't indicate whether the transition is guarded or not... that is shown in the sidebar when you click a state.

the state engine is the part that can't hallucinate. even with simple steps/prompting the review model can miss things... it's still an LLM making a judgement call at the end of the day.

the state engine doesn't judge, it enforces... with code and not transformers ^_^

if a tool (or any other guardrail) isn't valid at a given state the model call gets rejected before the model sees the result. that's the gap between "a model said this is okay" vs. "the system structurally prevents this"

[flagged]

for the integration piece that ties into Claude Code and other places where AI is used most frequently? yes I think it does... we're not fighting context in Opus/Sonnet as much as we are in smaller models and we're only adding about 6 tools here which is a smaller footprint than other MCP exposures. Smaller models have a more direct/tight interface that doesn't bloat the tool space in my experimentation (using the core directly)

Yes, the engine handles the full workflow schema including guards. There are some aspects of runtime enforcement (env vars/command filtering, etc. exposed via the UI) that currently only live in the plugin layer but the engine parses and exposes everything. All you would have to do is wire up enforcement on your end in your app the same way the plugin does.

[dead]

[dead]

Stately (and XState ^_^) is pretty neat, I hadn't come across it yet... (edit:) neat to see visual XState being used for application logic as well

I see constant posts on Reddit/HN about the ways that AI is amazing and at the same time is fudging it (literally). Nobody can make reliability guarantees on something that's non-deterministic and non-idempotent. Nobody's AI workflow suite of tools can claim this. Prompting gets you closer to the mark but still non-deterministic. Breaking down the problem into chunks with valid transition criterion so that even tiny models can step through them I believe gets us closer to where we want to be semantically

Mr. Claude's Opus says that this is a very feasible thing. It has better support for hooks than Cursor and full MCP support so protocol-layer blocking (like Claude) is possible. Adding to the roadmap...

Nice project... the per-agent tool restriction is the same core insight (smaller tool space -> better reasoning)

The main difference with Statewright is that tool access changes over time within a single agent. Planning phase gets read-only tools, edit capability unlocks after the agent proves it has adequate understanding... test tools unlock after the fix. State machines handle the phase transitions, guards and retry loops.

Your multi-agent approach decomposes by role instead of by phase/state. Both are valid. Since you're already in Rust, the engine crate (crates/engine) is a pure library with no deps. It might be interesting to see if putting a state machine around your orchestration layer improves your observed performance

[flagged]