statewright/statewright

statewright – Guardrails for AI‑agent tool use

What it is – An open‑source framework that lets you wrap an LLM‑based agent (Claude Code, Codex, Cursor, OpenCode, Pi, etc.) in a deterministic state‑machine. Each state defines which tools (read, edit, bash, test, …) the agent may call, which model to use, budget limits, and transition conditions. The engine enforces these rules at runtime, rejecting disallowed tool calls and prompting the user to move to the appropriate phase.

Why it matters – Modern code‑writing agents are prone to “brittle” behaviour: they keep re‑reading files, invoke destructive commands, or deploy before tests pass. Statewright shrinks the problem space by constraining the agent’s actions, turning a free‑form prompt into a guided workflow that improves reliability without needing larger models.

Core components

• Engine (Rust) – Pure‑Rust state‑machine evaluator, no LLM dependency, deterministic.
• Agent binary (sw‑agent) – Executes the LLM (via Ollama or the host’s API) inside the current state, streams JSONL events, and respects per‑state tool policies.
• Executor / MCP gateway – Bridges the agent to host platforms (Claude Code, Codex, Cursor, etc.), handling authentication, session isolation, and telemetry.
• TUI (statewright) – Terminal UI built with ratatui that visualises the workflow and lets you start/transition workflows with slash commands.

Key features

• Per‑state tool enforcement – Only the tools listed in allowed_tools are callable.
• Bash safety – Blocks destructive redirections, rm -rf, and script interpreters unless the state explicitly permits write‑level actions.
• Edit guards – Limits on number of edited lines/files per state.
• Command allow‑lists – Whitelists test commands (e.g., pytest).
• Conditional transitions & approval gates – Transitions can depend on runtime data (test results) or require human approval.
• Model routing – Different states can target different models (e.g., cheap Haiku for diagnosis, expensive Opus for fixing).
• Self‑hosting – Docker‑Compose stack (PocketBase + gateway) with BYO Ollama; Apache‑2.0 licensed engine.

Quick start (choose your host)

# Codex
npx statewright-codex@latest init
# Claude Code
/plugin marketplace add statewright/statewright && /plugin install statewright
# OpenCode, Cursor, etc.
npx statewright-<host>@latest init

Then sign up at statewright.ai, obtain an API key, and run a workflow:

❯ start the bugfix workflow — fix the failing tests in calc.py
…
[statewright] testing => completed
Workflow complete. 46 s.

You can also invoke via the slash command /statewright start bugfix.

Research snapshot – On a 5‑task subset of SWE‑bench, local models below 13 GB failed to edit files correctly, while models ≥13 GB achieved 10/10 passes when run under Statewright constraints, demonstrating the guardrails’ impact.

Licensing – Engine and agent are Apache 2.0; the overall project includes an FSL‑1.1‑ALv2 component that will convert to Apache 2.0 in 2029. A patent pledge covers independent implementations.

Where to learn more – Full docs, workflow schema, and visual editor are at https://docs.statewright.ai. The repository also contains example workflows, the Rust source (crates/*), and plugin adapters for each supported host.