state-gate

state_gate

An orchestrator that governs, visualizes, and makes auditable the development and exploration work of AI agents (such as Claude Code) through external state machines.

Overview

state_gate treats agents not as "smart entities that remember processes," but as executors that generate and submit actions and artifacts required by the state machine. This enables:

• Explicit processes and auditability
• Consistency across multiple agents/teams
• Process diversity absorbed through state/transition/guard definitions rather than proliferating skills

Key Features

• State-Driven: Agent behavior is determined by the state machine
• Evidence Submission Model: Agents submit evidence, not transition commands
• Guard Conditions: Control transitions through artifact requirements, machine verification, approvals, etc.
• Audit Logs: Record all events and decision results
• Optimistic Locking: Ensure consistency in concurrent execution through revision numbers

Use Cases

• Iterative processes including exploration, implementation, evaluation, and review
• Particularly designed for instant prototyping (short loops in exploration phase)

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Integration Layer                         │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────────────┐  │
│  │ MCP Server  │  │ Hook Adapter │  │ HTTP API / CLI     │  │
│  │ (Dialog)    │  │ (Execution)  │  │ (Integration)      │  │
│  └──────┬──────┘  └──────┬───────┘  └─────────┬──────────┘  │
└─────────┼────────────────┼───────────────────┼──────────────┘
          │                │                   │
          ▼                ▼                   ▼
┌─────────────────────────────────────────────────────────────┐
│                      State Engine                            │
│  ┌──────────────────────────────────────────────────────┐   │
│  │ Process Definition → Event → Guard Eval → Transition │   │
│  └──────────────────────────────────────────────────────┘   │
└──────────────────────────┬──────────────────────────────────┘
                           │
          ┌────────────────┼────────────────┐
          ▼                ▼                ▼
┌────────────────┐ ┌──────────────┐ ┌──────────────────┐
│ Artifact Store │ │ Audit/Event  │ │ Context/Run      │
│ (Source)       │ │ Log          │ │ Management       │
└────────────────┘ └──────────────┘ └──────────────────┘

Documentation

• Architecture
• Core Concepts
• Process DSL Specification
• MCP Interface
• Hook Adapter
• Security
• MVP Requirements
• Examples

Design Principles

1. Truth lives in state_gate - Don't rely on agent memory
2. state_gate decides transitions - Agents focus on evidence submission
3. Process differences are contained in DSL - Don't absorb them through skills proliferation
4. Handle conflicts and retries in specification - revision / idempotency / audit

Quick Start

Local Development

npm install
npm run build
npm link

mkdir -p .state_gate/processes
cp examples/exploration/exploration-process.yaml .state_gate/processes/exploration-process.yaml

state-gate create-run --process-id exploration-process
state-gate get-state --run-id <run_id>
state-gate list-events --run-id <run_id> --include-blocked true

All CLI output is JSON format. Define tool execution permissions in tool_permissions for each state (within process definition). emit-event accumulates artifact_paths and saves them in the latest row.

See examples/exploration/README.md for detailed instructions.

MCP Server

state-gate serve --process=./path/to/process.yaml

Hook Adapter (PreToolUse)

state-gate-hook pre-tool-use --tool-name Edit --tool-input '{"path":"README.md"}'

stdin input example:

echo '{"tool_name":"Edit","tool_input":{"path":"README.md"}}' | state-gate-hook pre-tool-use

Error behavior follows fail-open/fail-close settings in docs/hook-adapter.md.

Use as Claude Code Plugin

state_gate is distributed as a Claude Code Plugin and can be installed easily.

Installation

Method 1: From Marketplace (Recommended)

# Add marketplace
/plugin marketplace add https://github.com/CAPHTECH/state_gate

# Install plugin
/plugin install state-gate

Method 2: Direct from GitHub

/plugin install https://github.com/CAPHTECH/state_gate/tree/main/plugin

What Gets Installed

When you install the plugin, the following become automatically available: