Statewright
title: Statewright type: tool created: 2026-05-19 last_updated: 2026-05-19 related: ["Playradar", "radar/tools/TDDGuard", "radar/platforms/ModelContextProtocol"] sources: ["https://github.com/statewright/statewright"] radar_quadrant: Tools radar_ring: Assess radar_position: inner
A tool that constrains AI agent behaviour through JSON-defined state machines, controlling which tools an agent can access at each phase of a workflow. The project motto: "Agents are suggestions, states are laws."
AI agents with large tool sets (40+ tools) exhibit predictable failure modes: re-reading files repeatedly during implementation, attempting edits during review phases, or running deploys before tests pass. Increasing model size or prompt length provides inconsistent improvements. Statewright addresses this by shrinking the problem rather than scaling the solution — restricting tool availability per state so an agent working in a planning phase sees 5 tools instead of 30.
Workflows are defined as JSON state machines with named states, transitions, and guards. Each state specifies:
- Tool allowlist — which tools the agent may call
-
Bash command allowlist — prefix-matched commands only (blocks
rm -rfand similar even when Bash is permitted) - Edit restrictions — maximum lines per edit, files per state
- Conditional transitions — based on context data
- Approval gates — human review checkpoints between states
When an agent attempts to call a tool not available in the current state, it receives a rejection message specifying what is currently permitted and how to transition to a state where the tool is available.
| Agent | Enforcement mode |
|---|---|
| Claude Code | Hard (hooks-based) |
| Codex / Oh My Codex | Hard |
| Pi / opencode | Hard |
| Cursor | Advisory (MCP + rules) |
All integrations use the Model Context Protocol (MCP) or Claude Code hook-based enforcement.
Testing on a 5-task SWE-bench subset:
- Local models at 13.8 GB and above achieved 100% pass rates with state constraints applied
- Below 13 GB, models could identify bugs but struggled with surgical edits regardless of constraints
- Primary gain: elimination of read-loop failures and maintenance of focused tool spaces
Workflows can be written manually in JSON or generated by the agent itself via the statewright_create_workflow tool. A visual editor is available at statewright.ai.
Engine code is Apache 2.0. The managed platform uses FSL-1.1-ALv2, converting to Apache 2.0 in 2029. Solo developers, researchers, open-source projects, and single-team self-hosted deployments are covered by a patent pledge.
Free tier: 3 workflows, 200 transitions/month. Pro: $29/month.
Statewright sits in the Assess ring of the Tools quadrant, at inner position. First studied via the GitHub repository on 2026-05-19; no personal use. The tool addresses a directly observable problem in Claude Code-driven workflows — agent tool overload leading to inefficient loops — using the same hook/MCP integration layer as TDD Guard. Inner position reflects low installation friction, a free tier suitable for trial, and strong applicability to any Claude Code project with a defined multi-phase workflow (plan → implement → test → review). The remaining gate before Trial is a first workflow definition and deployment on an active project.
