# Statewright

> State machine guardrails that control which tools your AI agent can use in each phase, enforcing structured workflows across Claude Code, Codex, Cursor, opencode, and Pi.

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:

| Agent | Integration | Enforcement |
|---|---|---|
| Claude Code | Hooks + MCP | Hard |
| Codex | Hooks | Hard (alpha) |
| opencode | TypeScript plugin | Hard (alpha) |
| Pi | Skills extension | Hard (alpha) |
| Cursor | MCP + rules | Advisory (alpha) |

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.

## Features
- State machine workflow enforcement for AI agents
- Per-state tool allow/block lists
- Bash discernment (blocks destructive ops and redirects in non-write states)
- Edit guards (max_edit_lines, max_files_per_state)
- Command allow-lists with prefix matching
- Conditional transitions with programmatic guards
- Approval gates for human review before high-risk transitions
- Environment scoping (blocked_env, env_overrides per state)
- Session isolation via CLAUDE_SESSION_ID
- Visual workflow editor
- Agent-generated workflow creation via statewright_create_workflow
- Deterministic Rust engine (no LLM in enforcement loop)
- Self-hostable engine under Apache 2.0
- MCP gateway via managed cloud
- Run history and workflow storage in managed cloud

## Integrations
Claude Code, Codex, Cursor, opencode, Pi, MCP (Model Context Protocol)

## Platforms
CLI, API, WEB, DEVELOPER_SDK

## Pricing
Freemium — Free tier available with paid upgrades

## Links
- Website: https://statewright.ai
- Documentation: https://docs.statewright.ai
- Repository: https://github.com/statewright/statewright
- EveryDev.ai: https://www.everydev.ai/tools/statewright