The fastest way to make a coding agent less reckless is not another paragraph in its system prompt. It is taking tools away until the agent reaches the phase where it is allowed to use them.

That is the pitch behind Statewright, an open source Rust engine and managed MCP layer for state machine guardrails. A planning state can expose only Read, Grep, and Glob. An implementation state can unlock Edit and Write. A testing state can expose Bash, but only for commands such as pytest. If the model tries to skip ahead, the gateway rejects the call instead of politely hoping the model changes its mind.

Statewright reported constrained-agent result

The distinction matters because most agent failures are sequencing failures. The model edits before it understands the bug, runs a broad shell command when a narrow test would do, or keeps retrying after the task has plainly gone sideways. A prompt can describe the desired order. Statewright turns the order into a machine that has to approve each transition.

The useful question is not whether Statewright is interesting. It is whether you should put it in front of your next coding agent, and which version you should run.

The safe local install

Start with the managed path unless your actual requirement is keeping the workflow service off the internet. The official install guide lists jq as a prerequisite, then adds the Claude Code plugin with two commands:

claude /plugin marketplace add statewright/statewright
claude /plugin install statewright

Create an API key at Statewright, save it as ~/.statewright/api_key with mode 600, and start Claude Code. The documented verification step is /statewright list. A new account should show a default bugfix workflow. The official site currently advertises 200 transitions per month on its free tier, so a small team can test the control model before making a billing decision.

The first run is deliberately constrained. /statewright start bugfix begins in a planning state with Read, Grep, and Glob. Edit is unavailable. The quick start shows the gateway returning a concrete error when the agent tries it, including the allowed tool list and the transition it needs to request. That is a better failure mode than a hidden policy violation because the operator can see exactly which phase the agent is in.

When the agent calls the READY transition, Edit and Write become available. The example workflow caps each edit operation at 20 lines and limits the implementation state to 3 files. DONE moves the run into testing. Bash appears there, but the workflow can narrow it with allowed_commands, for example pytest, npm test, or cargo test. A passing test can unlock completion. A failing test sends the machine back to implementation.

That loop is the part worth stealing even if you never use the hosted service. Planning, implementation, testing, and approval are separate permissions. The model does not get a single all-purpose tool belt and a paragraph telling it to behave.

If you need the fully local route, the project also documents a self-hosted stack built around Docker Compose, a local MCP gateway, the workflow editor, and the open source engine. The repository's own local executor can talk to Ollama, and its follow-up discussion says the end-to-end bugfix path works with an Ollama model at 13B or larger. I would treat that as a starting point, not a hardware guarantee. Model quantization, context length, repository size, and tool-call behavior still decide whether the run is usable.

The safe rollout is simple: install the managed plugin, run the supplied bugfix workflow on a disposable repository, inspect the transition history, then move the same workflow to a local stack only if the data boundary justifies the added operations work. Do not start by pointing an experimental state machine at production credentials.

What the published result actually says

The Statewright repository reports a striking result. In its own evaluation table, the constrained run recorded 10 passing attempts out of 10, while the comparison run recorded 2 passing attempts out of 10. The models listed around that result include a 13.8GB gpt-oss variant and a 19.9GB Gemma variant. The README also reports 5 out of 5 on a five-task SWE-bench subset for those entries.

That is useful evidence for a narrow claim: reducing the tool and solution space can make a small local model complete a constrained bugfix more reliably. It is not evidence that Statewright raises every model's general coding ability, and it is not a full SWE-bench result. The repository calls out the five-task subset, and the author has said the full experiment harness was not yet published when the discussion took place.

There is a second boundary. The same README says models below roughly 13GB can produce tool calls but struggle to retain enough file content for accurate edits. That is a workload observation, not a universal minimum. A tiny repository with a short test may work on less memory. A large monorepo can overwhelm a much larger model. The practical test is whether the model can keep the relevant files, test output, and state instructions in working context at the same time.

This is where the chart above can mislead if you treat it as a benchmark rather than a deployment clue. The 2/10 to 10/10 change is a reported before-and-after comparison under the project's setup. It does not tell you how many tokens were used, how the control prompt was tuned, whether the tasks were representative, or whether the result survives a larger sample. Use it to justify a local probe, not to skip one.

Where the guardrails stop

Statewright can prevent an agent from calling Edit in planning. It cannot make a bad plan good. It cannot tell whether the requested change is safe for your business, whether the tests cover the dangerous path, or whether a human approved the right thing. A state machine is a permission boundary, not a substitute for code review.

It can also be too restrictive. If a workflow forgets to expose a needed read tool, the agent gets stuck. If allowed_commands is too broad, the testing state may still have more shell power than you intended. The schema documentation warns that instructions guide while command allow-lists enforce. That difference should shape every state you write. Trust the command prefix that produces proof, not a prompt that asks for the proof.

The schema gives you enough pieces to build a serious workflow without a large framework: per-state tool lists, iteration limits, edit-line and file caps, blocked environment variables, environment overrides, context byte budgets, conditional guards, approval gates, and fork/join branches. Start with less. Add one permission when the task proves it needs one. The reverse process is how agents end up with a giant tool surface again.

There is also a licensing and product boundary to check before standardizing on it. The repository says the engine and agent crates are Apache 2.0, while parts of the gateway and plugins use FSL-1.1-ALv2 and convert later. The project states that single-developer and single-team self-hosting is permitted, but a company should still read the current license and patent pledge instead of treating an HN comment as legal advice.

My decision rule is blunt. Use the managed plugin when you want to test phase-level enforcement in minutes and can accept an external gateway. Use the self-hosted stack when the workflow data or model traffic cannot leave your environment and you are willing to own Docker, Ollama, updates, and failure recovery. Skip Statewright for a one-shot script where a normal sandbox and a test command already give you a clear boundary. Use it when the work has phases that matter and the cost of a skipped phase is higher than the cost of maintaining a workflow.

The interesting shift is small but concrete: reliable agents may need fewer permissions before they need more parameters. Statewright has not proved that thesis at benchmark scale. It has made the thesis executable, which is enough reason to run the disposable-repository test and see where your own agent fails.

Sources