Statutor

Keep project rules, handoffs, and decisions intact across coding-agent sessions.

Quickstart · Agents · The ledger · Documentation

Statutor gives a repository a small set of files for its rules, current work, and decision history. Hooks check supported tool calls before they write. The Git check validates the staged result against the committed policy.

Append a new decision         → allowed
Rewrite an earlier decision  → blocked
Edit an ordinary source file → allowed

Quickstart

Install and initialize

Requires Python 3.10 or later. Run these commands in your project directory:

pipx install statutor
statutor init .

Existing files stay unchanged. init creates the ledger and detects a small project profile. Use statutor init . --type none for governed files only. Profiles and policy.

Choose your agent

Connect an adapter to check supported tool calls during a session. Installing the CLI and initializing a ledger do not register agent hooks.

Claude Code

Run these slash commands inside Claude Code:

/plugin marketplace add https://github.com/hoohugokim/statutor
/plugin install statutor@hoo-plugins --scope project

The repository is the plugin. It includes /statutor-init, /handoff, /decide, and /statutor-doctor.

Enable the Git backstop

Hooks cover different tools on each agent. Use the staged-index check in addition to your agent adapter. With pre-commit installed, add this entry to your project's .pre-commit-config.yaml:

repos:
  - repo: https://github.com/hoohugokim/statutor
    rev: v0.7.5
    hooks: [{id: statutor}]

Then install the Git hook and check the ledger:

pre-commit install
statutor-doctor .

Run statutor staged . to check the current index directly. A native Rust binary provides the same staged checks without Python. Git setup and limits.

How the ledger works

Each file has a designated writer and a mutation policy. Four planes separate rules, current state, decisions, and plans:

The default handoff is limited to 40 lines. Task checkboxes, descriptions, and ordering can change; existing IDs remain. CLAUDE.md bridges to AGENTS.md. See policy and trust for writer roles, budgets, shell checks, and intentional policy changes.

Optional capabilities

• Global instructions and skills: preview and manage shared instructions and skills across supported hosts. This is a separate opt-in operation from project initialization.
• Worker provenance: record sessions and attributed handoffs. Automatic hooks prove attempts, never successful mutation, and record nothing by themselves.

Coverage and limits

Automatic adapters stay silent outside a repository explicitly marked by .statutor.yaml. Hook failures allow the session to continue. The staged floor fails closed on invalid policy or Git errors. It inspects the local index; Git hooks can be bypassed with --no-verify.

MCP tools and some partial-patch checks remain outside in-loop coverage. Use the Git backstop to check their staged results. Agent-specific guides above describe each adapter's scope and verified behavior.

Documentation

Policy and trust · Architecture and API · Global layer · Workers · Releasing · Release notes

For local development, run pip install -e ., pytest -q, and statutor-doctor .. The kernel has no third-party dependencies; PyYAML is optional. Architecture covers the source layout, validation modes, design references, and contribution checks.