Claude Code

Without guardrails, agents call Edit during review, deploy before tests pass, and loop on the same file read five times. The Claude Code plugin is the most feature-complete statewright integration. Hooks block tool calls at the protocol layer; the MCP gateway provides workflow tools.

Install

/plugin marketplace add statewright/statewright
/plugin install statewright

Paste your API key when prompted (the hook auto-detects sw_live_* patterns in your input and saves the key to ~/.statewright/api_key). Get one at statewright.ai/keys.

For executor-owned isolated delivery and state model routing:

node plugins/executor/statewright-exec.mjs \
  --host claude --workflow bugfix --cwd "$PWD" -- \
  "Fix the failing tests"

The executor owns the API credential and MCP session. Claude Code uses the loopback adapter for hook policy and workflow tools. When the state changes its route, Statewright forks the saved conversation into a new CLI process and resumes it with the new model and effort. This is a boundary restart, not an in-turn model hot swap; effort is advisory when the selected Claude CLI does not expose a corresponding flag.

The 0.3.0 candidate also keeps autonomous-mode guidance and token telemetry on the managed execution path.

How it works

The plugin registers four hooks:

Hook	Purpose
`UserPromptSubmit`	Fetches workflow state from gateway, injects phase context and tools into the conversation. Tells the agent to work autonomously through states without stopping between phases.
`PreToolUse`	Blocks tools not in the current phase's `allowed_tools`. Also blocks Bash redirects, destructive ops, and scripting interpreters when Write/Edit aren't available.
`PostToolUse`	Detects statewright MCP tool calls, manages local state cache, triggers interrupts when file edits match glob patterns
`Stop`	No-op. Claude fires Stop after every agent turn (not just session exit), so deactivating here would kill workflows between turns.

The MCP gateway provides statewright_transition, statewright_get_state, statewright_load_workflow, statewright_list_workflows, statewright_get_status, statewright_deactivate, statewright_pause, statewright_force_state, and statewright_create_workflow. The plugin proxy adds statewright_search_docs client-side. Full list in the tool reference.

What enforcement looks like

Try to call Edit during a planning phase:

PreToolUse hook (blocked)
  feedback: Tool 'Edit' is not available in the 'planning' phase.
  Allowed: Read, Grep, Glob. To advance, use statewright_transition with: READY.

Try to write a file via Bash redirect when Write isn't allowed:

PreToolUse hook (blocked)
  feedback: Bash command blocked: output redirect detected but Write/Edit
  not in allowed tools for 'planning' phase.

Features

Protocol-layer tool blocking. Not a prompt suggestion. The hook returns permissionDecision: deny before the tool executes.
Bash discernment. Even when Bash is allowed, echo "fix" > src/main.rs gets blocked because it bypasses the Edit restriction via shell redirect. Same for rm -rf, sed -i, python script.py.
Interrupt detection. Edit a PocketBase hook file matching **/*.pb.js? The workflow auto-transitions to a validation state, then returns where you were.
Fork/join. Run lint, test, and type-check branches in parallel (or sequentially), rejoin when all pass.
Zero-network enforcement. PreToolUse reads from a local state cache. No round-trip to the gateway on every tool call.
Approval gates. requires_approval pauses the workflow for human review before high-risk transitions.
Auto-bootstrap. First run installs MCP config and permissions. No manual setup beyond the two install commands.

Slash commands

/statewright start bugfix    — activate a workflow
/statewright list             — show available workflows
/statewright stop             — deactivate the current workflow

Next steps

Quick Start — run your first workflow
Create Your Own — build a custom workflow

Source

plugins/claude-code/

Claude Code

On this page