statewright/statewright

statewright – AIエージェントのツール使用に対するガードレール

何であるか – LLMベースのエージェント（Claude Code、Codex、Cursor、OpenCode、Piなど）を決定論的なステートマシンでラップできるオープンソースフレームワークです。各ステートは、エージェントが呼び出せるツール（読み取り、編集、bash、テストなど）、使用するモデル、予算制限、遷移条件を定義します。エンジンは実行時にこれらのルールを強制し、許可されていないツール呼び出しを拒否し、ユーザーに適切なフェーズに移動するよう促します。

なぜ重要か – 現代のコード生成エージェントは「壊れやすい」挙動を示す傾向があります：ファイルを繰り返し読み込み、破壊的なコマンドを実行し、テストが通る前にデプロイしてしまうことがあります。Statewrightはエージェントの行動を制限することで問題領域を縮小し、自由なプロンプトではなくガイド付きワークフローに変換することで、より大きなモデルを必要とせずに信頼性を向上させます。

主要コンポーネント

• エンジン（Rust） – LLMに依存しない純Rustのステートマシン評価器、決定論的。
• エージェントバイナリ（sw-agent） – OllamaまたはホストのAPIを介してLLMを実行し、現在のステート内でJSONLイベントをストリーム出力し、各ステートのツールポリシーを尊重します。
• エクセキューター / MCPゲートウェイ – エージェントをホストプラットフォーム（Claude Code、Codex、Cursorなど）に接続し、認証、セッション隔離、テレメトリを処理します。
• TUI（statewright） – ratatui で構築されたターミナルUIで、ワークフローを可視化し、スラッシュコマンドでワークフローの開始・遷移が可能です。

主な機能

• ステートごとのツール強制 – allowed_tools にリストされたツールのみが呼び出せます。
• bashの安全性 – ステートが書き込みレベルの操作を明示的に許可しない限り、破壊的なリダイレクト、rm -rf、スクリプトインタプリタをブロックします。
• 編集ガード – ステートごとの編集行数・ファイル数に制限があります。
• コマンド許可リスト – テストコマンド（例：pytest）をホワイトリスト化できます。
• 条件付き遷移と承認ゲート – 遷移は実行時データ（テスト結果）に依存可能で、人間の承認を必要とする場合もあります。
• モデルルーティング – 異なるステートで異なるモデル（例：診断には安価なHaiku、修正には高価なOpus）を指定できます。
• セルフホスティング – BYO Ollamaを備えたDocker-Composeスタック（PocketBase + ゲートウェイ）；Apache-2.0ライセンスのエンジン。

クイックスタート（ホストを選択）

# Codex
npx statewright-codex@latest init
# Claude Code
/plugin marketplace add statewright/statewright && /plugin install statewright
# OpenCode、Cursorなど
npx statewright-<host>@latest init

その後、statewright.ai でアカウント登録し、APIキーを取得してワークフローを実行します：

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

スラッシュコマンド /statewright start bugfix でも呼び出せます。

研究スナップショット – SWE-benchの5タスクサブセットにおいて、13GB未満のローカルモデルはファイルの編集を正しく行えませんでしたが、13GB以上のモデルはStatewrightの制約下で10/10の成功を達成しました。ガードレールの効果を示しています。

ライセンス – エンジンとエージェントはApache 2.0；プロジェクト全体にはFSL-1.1-ALv2のコンポーネントが含まれており、2029年にApache 2.0に移行予定です。独立実装をカバーする特許誓約があります。

さらに学ぶには – 完全なドキュメント、ワークフロー仕様、ビジュアルエディタは https://docs.statewright.ai で利用可能です。リポジトリには例のワークフロー、Rustソース（crates/*）、各サポートホスト用のプラグインアダプタも含まれています。