statewright - Moses Yebei

The Problem

AI agents given unrestricted tool access fail in predictable ways: they re-read files, edit during review, deploy before tests pass. Bigger models and longer prompts help only marginally. Statewright's approach is to constrain the problem space itself—state machines that limit which tools an agent can use in each phase, rejecting out-of-phase calls with guidance on what's available and how to transition.

What This Does

Statewright is a collection of five self-contained projects, not a single codebase. The core is a pure Rust state machine engine (crates/engine) with no LLM in the loop—states, transitions, guards, and tool restrictions are deterministic. Around it sits an agent binary (crates/cli, binary sw-agent) that runs an Ollama-backed loop, enforcing tool access and streaming structured output.

The repo also includes an MCP gateway (crates/mcp-gateway) for integration with Claude Code, Codex, Cursor, opencode, and Pi, plus plugins (plugins/), a self-hosted deployment (self-hosted/), and experiments. The README claims two local models went from 2/10 to 10/10 passing on a 5-task SWE-bench subset under these constraints.

How It Is Wired

Execution starts at main in crates/cli/src/main.rs:1337, which reaches 205 functions. The shortest path out of the process is main -> chat via self.http.post(&url).json(&request).send—a network call to an Ollama endpoint. The CLI also runs external commands via execute_tool, called 22 times from main and 8 times from run_tdd_chain.

The call graph shows clear hubs: classify (called from 40 places), handle_message (39), and resolve_transition (32) in crates/engine/src/transition.rs. Changing these breaks the most. The engine's types.rs defines the core state machine types (target, guard_names, requires_approval). The MCP gateway (gateway.rs, session.rs, interceptors.rs) handles remote sessions, with pre_call_check (18 callers) enforcing tool restrictions before execution.

The module graph is shallow—37 internal modules, 7 import edges, no circular dependencies. The heaviest file is crates/cli/src/main.rs (57 functions, 9 types), followed by tools.rs (84 functions) and plugins/pi/src/index.ts (2872 lines). The wiring is not deeply layered; most logic sits in these few large files.

How To Use It

Setup: This is a Rust workspace. Build with cargo build --release from the root (Cargo.toml present). Docker is available via docker-compose.yml for self-hosted deployment.

Configuration: The agent connects to Ollama directly. Endpoint and model configuration live in crates/cli/src/main.rs and crates/agent/src/ollama_client.rs. For MCP-based clients, authentication uses an API key—see self-hosted/pocketbase/pb_migrations/002_bootstrap_api_key.js.

Running it: The README documents plugin installation for Claude Code:

/plugin marketplace add statewright/statewright
/plugin install statewright

Then start a workflow with /statewright start bugfix or a natural-language command. The CLI binary is sw-agent.

Real-World Use

A bugfix workflow: agent starts in planning phase with read-only tools. It reads files, then transitions to implementing where edit tools unlock with limited shell access. Write-via-redirect and destructive ops stay blocked even when Bash is allowed. Transition to testing permits only designated test commands. A rejected tool call returns what's available and how to transition.

Code Health & Issues

Static analysis found 55 findings (13 high, 42 medium). The dominant issues:

High - Deep nesting (24 occurrences) - crates/agent/src/executor.rs, ollama_client.rs, orchestrator.rs; max indentation depth 9. Fix with early returns.
High - Duplicated code (699 repeated 6-line blocks across 37 files) - extract shared helpers.
High - Oversized files (13) - plugins/pi/src/index.ts at 2872 lines, crates/cli/src/main.rs, tools.rs. Split by responsibility.
Medium - Empty catch blocks (4) - self-hosted/pocketbase/pb_migrations/*.js silently discard errors.
Medium - High branching density (13) - plugins/pi/src/index.ts has 1208 branch points over 2872 lines.

SDLC concerns: no LICENSE file (all rights reserved by default), unpinned GitHub Actions (dtolnay/rust-toolchain@stable), no dependency vulnerability scan, no non-root USER in the Dockerfile, and CI workflows discard exit codes in release.yml. Tests and CI exist; no committed secrets found.

The Bottom Line

The core idea is sound—constraining agent tool access via state machines is a practical alternative to prompt engineering. The Rust engine is clean and deterministic. The weaknesses are structural: oversized files, duplicated logic, and missing license/security hygiene. Worth using if you run Ollama-based agents and need guardrails; expect to refactor before extending.

What the analyser found

Deployment readiness

7/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

288 files

Markdown54
JSON39
Rust38
Shell33
Python31
JavaScript20

ReactVueExpressTailwindDocker

Module dependencies

The 10 most depended-upon modules of 37, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_rn_june_2026_src_backend_etl["etl"] n1_june_2026_src_backend_server["server"] n2_plugins_omx_src_hook["hook"] n3_plugins_opencode_src_index["index"] n4_plugins_pi_src_index["index"] n5_f_hosted_ui_src_router_index["index"] n6_ne_2026_src_backend_etl_test["etl.test"] n7_2026_src_backend_server_test["server.test"] n8_plugins_omx_src_hook_spec["hook.spec"] n9_gins_opencode_src_index_spec["index.spec"] n6_ne_2026_src_backend_etl_test --> n0_rn_june_2026_src_backend_etl n1_june_2026_src_backend_server --> n0_rn_june_2026_src_backend_etl n7_2026_src_backend_server_test --> n1_june_2026_src_backend_server n8_plugins_omx_src_hook_spec --> n2_plugins_omx_src_hook n9_gins_opencode_src_index_spec --> n3_plugins_opencode_src_index

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high3

medium6

low2

Pin third-party GitHub Actions to a commit SHAhigh3 occurrences

.github/workflows

dtolnay/rust-toolchain@stable, Swatinem/rust-cache@v2, softprops/action-gh-release@v2

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Add a LICENSE; redistribution rights are undefinedhigh

no licence file at the repository root

Fix: Add MIT or Apache-2.0 at the repository root.

Stop discarding the exit code of steps whose failure mattershigh5 occurrences

.github/workflows/release.yml

lines 31, 33, 35, 36, 38 discard failure

The job reports green while the artifact it was supposed to produce was never produced, so a crash becomes a successful run built on stale data.

Fix: Let the step fail, or test the specific expected condition instead of discarding all exit codes.

Declare least-privilege permissions for GITHUB_TOKENmedium

.github/workflows/ci.yml

1 workflow(s) declare no permissions

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

11 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium2 occurrences

self-hosted/gateway/Dockerfile

rust:1.87-bookworm, debian:bookworm-slim

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/ci.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Add a non-root USER to the imagemedium

self-hosted/gateway/Dockerfile

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Set timeout-minutes on the workflow jobslow3 occurrences

.github/workflows/ci.yml

3 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Add the repository convention files this project lackslow3 occurrences

missing .editorconfig, .gitattributes, a formatter config

Without them one contributor's editor writes tabs into a Python file, a shell script commits with CRLF and fails in the container, and a notebook diff is unreviewable.

Fix: Add .editorconfig, .gitattributes with text=auto eol=lf, and a formatter config.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.