statewright/statewright

What is Statewright?

Statewright is an open‑source framework that lets you run agentic workflows with explicit, enforceable phases. It defines a state‑machine for each step of a task (e.g., planning, implementing, testing) and controls which LLM tools are allowed in each phase. When you plug it into a supported AI client (Claude Code, Codex, Cursor, OpenCode, Pi, OMX, or a custom MCP host) the integration intercepts tool calls, blocks disallowed actions, and can route different phases to different models.

Why it matters

Typical AI‑assisted coding agents can keep using the same tools throughout a job, which makes it easy for them to edit code before a review or deploy before tests finish. Statewright makes those boundaries explicit and, where the host supports it, enforced. This gives you:

• Safety – tools like file edits or destructive shell commands are only allowed in the states you designate.
• Granular model routing – you can run cheap models for cheap phases and switch to larger ones for the heavy‑lifting phases.
• Approval gates – workflows can pause for a human review before moving on.
• Repeatable, auditable runs – every transition, guard, and tool usage is logged.

Core components (as described in the README)

Component	Language / Role	Key responsibilities
Engine (crates/engine)	Rust	Pure state‑machine evaluator – no LLM, deterministic, provides guards, transitions, and tool‑allow lists.
Agent binary (crates/cli, sw‑agent)	Rust	Executes the LLM in a constrained loop, streams JSONL events, respects per‑state model routing, can run a single state on demand.
Executor / plugin layer (plugins/*, crates/mcp‑gateway)	Rust + host adapters	Holds workflow session, credentials, telemetry, and translates native tool hooks for each supported client (Claude, Codex, Pi, etc.).
TUI (crates/tui, statewright)	Rust (ratatui)	Terminal UI that runs sw‑agent, displays live JSONL events, and lets you interact with the workflow.

How a workflow looks

A workflow is a JSON definition that lists states, allowed tools, optional per‑state model, guards, and transitions. Example (simplified):

{
  "id": "bugfix",
  "initial": "planning",
  "meta": {"default_model": "claude-sonnet-4"},
  "states": {
    "planning": {"allowed_tools": ["Read","Grep"], "model": "claude-haiku"},
    "implementing": {"allowed_tools": ["Read","Edit","Write"]},
    "testing": {"allowed_tools": ["Read","Bash"], "allowed_commands": ["pytest"]},
    "completed": {"type": "final"}
  }
}

The engine enforces the allowed_tools list, blocks disallowed Bash commands, and can require human approval on transitions.

Supported AI hosts

Statewright ships native plugins for:

• Claude Code (0.3.4 candidate) – native OAuth, pre‑permission checks.
• Codex – managed App‑Server adapter.
• Pi, OpenCode, Cursor, OMX – each with a thin bridge that enforces the same guardrails. Custom MCP hosts can also be connected via the gateway.

Research snapshot

A small experiment on a 5‑task SWE‑bench subset showed that with Statewright constraints the larger models (13.8 GB gpt‑oss:20b and 19.9 GB gemma4:31b) solved all tasks, whereas smaller models failed. The authors note this does not prove a minimum model size; it simply illustrates that the guardrails help the agent stay on track.

Pricing & deployment

• Managed cloud at [statewright.ai] – free tier (3 workflows, 200 transitions/mo) and paid tiers ($9/mo Pro, $99/mo Team, Enterprise custom). Billing covers workflow storage, run history, and the MCP gateway.
• Self‑hosted – Docker‑Compose stack (PocketBase + gateway + editor). You bring your own Ollama for model serving. Engine and agent are Apache‑2.0; the gateway is currently FSL‑1.1‑ALv2 (will convert to Apache‑2.0 in 2029).

Trade‑offs / limitations

• Requires an MCP‑aware client or custom hooks – not all AI chat tools support it.
• Workflows are hand‑written JSON (though agents can generate them via statewright_create_workflow).
• Over‑restrictive workflows can cause the agent to get stuck; a statewright_deactivate command can bypass guards.
• Research results are limited to a tiny benchmark subset.

Who might use it?

• Developer teams that want safe, auditable AI‑assisted code changes.
• Tool builders looking to embed LLM agents with strict policy enforcement.
• Researchers exploring state‑machine‑guided prompting or per‑state model routing.

---

TL;DR: Statewright is a Rust‑based, open‑source toolkit that lets you define state‑machine‑driven AI agent workflows, enforce per‑state tool permissions, and route different phases to different models. It integrates with several modern AI coding assistants and can be self‑hosted or used via a managed cloud service.