GitHub - statewright/statewright: State machine guardrails for AI agents

Same tasks, same hardware. Below 13GB, models can produce tool calls but can't retain enough file content to produce accurate edits — that's the floor, not a statewright limitation. Frontier models with default system prompts handle the obvious catastrophic actions (database deletion, credential leaks)... most of the time. The structural win is bigger: breaking read-loop death spirals where models re-read the same file 5+ times without ever editing, and keeping the tool space small enough that the model actually reasons instead of flailing. Research brief → Quick start Install into Claude Code: /plugin marketplace add statewright/statewright /plugin install statewright

Your browser opens → sign up at statewright.ai → generate a key → paste it → done. Then start a workflow: ❯ start the bugfix workflow — fix the failing tests in calc.py

◆ statewright — statewright_start (workflow: bugfix) ◆ [statewright] Workflow activated: bugfix

◆ statewright — statewright_get_state (MCP)

◆ Current phase: planning. Let me read the code first.

Read 2 files

[statewright] planning => implementing

◆ statewright — statewright_transition (READY)

Edit calc.py: 1 line changed

[statewright] implementing => testing

◆ statewright — statewright_transition (DONE)

Bash: pytest -x — 7 passed

[statewright] testing => completed ◆ [statewright] Workflow complete. 46 seconds.

You can also use the slash command directly: /statewright start bugfix. How it works The core is a Rust engine that evaluates state machine definitions: states, transitions, guards, tool restrictions. It's deterministic. No LLM in the loop. On top of that sits a plugin layer that integrates with your coding agent via MCP. When you activate a workflow, hooks enforce tool restrictions per state automatically. The model sees 5 tools instead of 30, gets clear instructions for the current phase, and transitions when conditions are met.

Guardrails

Guardrail What it does

Per-state tool enforcement Tools invisible to agent when not in allowed_tools

Bash discernment Redirects (>>), destructive ops (rm, shred), and scripting interpreters 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, etc.) on context data

Approval gates requires_approval pauses for human review before high-risk transitions

Environment scoping blocked_env + env_overrides per state

Session isolation Per-session state via CLAUDE_SESSION_ID

Full guardrail reference in the docs. Define your own workflows { "id": "bugfix", "initial": "planning", "states": { "planning": { "allowed_tools": ["Read", "Grep", "Glob"], "max_iterations": 8, "on": { "READY": "implementing" } }, "implementing": { "allowed_tools": ["Read", "Edit", "Write"], "max_edit_lines": 20, "max_files_per_state": 3, "on": { "DONE": "testing" } }, "testing": { "allowed_tools": ["Read", "Bash"], "allowed_commands": ["pytest", "cargo test", "npm test"], "on": { "PASS": { "target": "completed", "guard": "tests_passed" }, "FAIL_TEST": "implementing" } }, "completed": { "type": "final" } }, "guards": { "tests_passed": { "field": "test_result", "op": "eq", "value": "pass" } } } State machines aren't DAGs — they loop and retry, which is what agentic work actually needs. Point your agent at the JSON schema and it generates a workflow via statewright_create_workflow. Tweak tools, commands, and environment blocks in the visual editor.