Statewright

Statewright is a state machine guardrail system for AI coding agents, built around a deterministic Rust engine with no LLM in the loop. It constrains which tools an agent can access at each phase of a workflow, preventing the open-ended tool sprawl that causes agents to stall or loop. The project is hosted on GitHub under a dual Apache 2.0 / FSL-1.1-ALv2 license, with a managed cloud at statewright.ai handling workflow storage, run history, and the MCP gateway.

What It Is

Statewright sits between an AI coding agent and its tool set, enforcing a user-defined state machine that dictates which tools are visible and callable at each workflow phase. A planning state might expose only read-only tools; an implementing state unlocks edit tools with line-count caps; a testing state restricts Bash to a prefix-matched allow-list of test commands. If the agent calls a tool outside the current phase, the call is rejected with a message listing what IS available and how to transition. The core engine is written in Rust and is deterministic — no model inference is involved in enforcement.

How the Guardrail Architecture Works

The enforcement layer operates at the protocol level for supported agents, meaning tool calls are blocked before the model ever sees them ("hard" enforcement). For Cursor, enforcement is advisory — rules are injected into context but cannot be gated at the protocol layer due to Cursor's architecture. The guardrail set includes:

• Per-state tool enforcement — tools not in allowed_tools are invisible to the agent
• Bash discernment — redirects, destructive ops (rm, shred), and scripting interpreters are blocked in non-write states
• Edit guards — rejects diffs exceeding max_edit_lines, caps files edited per state
• Command allow-lists — prefix-matched allowed_commands per state
• Conditional transitions — guards with programmatic predicates (eq, gt, exists) on context data
• Approval gates — requires_approval pauses for human review before high-risk transitions
• Session isolation — per-session state via CLAUDE_SESSION_ID

Research Results and Tradeoffs

The README reports a 5-task SWE-bench subset experiment where two local models (13.8 GB and 19.9 GB) went from 2/10 to 10/10 correct with Statewright constraints active — same tasks, same hardware. The project notes this is a 5-task subset, not the full 2,294-instance benchmark. Below 13 GB, models can produce tool calls but cannot retain enough file content for accurate edits, which the project describes as a model floor rather than a Statewright limitation. Structural benefits cited include breaking read-loop death spirals and keeping the tool space small enough for the model to reason rather than flail.

Known tradeoffs documented in the README: requires MCP support or hooks in the agent; workflow definitions are hand-authored (though agents can generate them via statewright_create_workflow); Cursor enforcement is advisory only; and overly restrictive workflows can stall the agent (statewright_deactivate is the escape hatch).

Supported Agents and Integration Model

Statewright integrates with agents via MCP and/or hooks:

Installation into Claude Code is a three-command process via the plugin marketplace. The browser opens for sign-up, an API key is generated and pasted, and workflows are started via natural language or slash commands.

Deployment Model and Licensing

The engine (crates/engine) is Apache 2.0 and embeddable with no runtime dependencies. The broader codebase uses FSL-1.1-ALv2, which converts to Apache 2.0 on May 3, 2029. Single-developer and single-team self-hosting of the full stack is permitted under the FSL license. The project also includes a patent pledge covering independent implementations for solo developers, researchers, open-source projects, and single-team self-hosted deployments. The managed cloud handles workflow storage, run history, and the MCP gateway for users who do not self-host.

Update: Initial Public Release (May 2026)

The repository was created on May 3, 2026, and last pushed on May 14, 2026, indicating this is a very recent initial release. The project has 273 stars and 4 forks as of the last update. Docs are live at docs.statewright.ai covering install, workflow authoring, schema reference, MCP tool reference, and agent-generated workflows.