Writ

• Explainer
• Design Paper
• Docs

Writ is a language and runtime for bounded agent authority.

A writ file states what an agent can do and how much it can spend. It also states what the agent must not change. The registrar checks each action against these terms. It writes each action, check, and result to a record.

Writ file

A writ can contain these terms:

Term	Purpose
mandate	States the goal.
grants	Give permission for actions and resources.
bounds	Limit iterations, cost, time, and changes.
invariants	State conditions that must remain true.
obligations	State checks that must pass before satisfaction.
satisfaction	States the proof that the work is complete.
remedies	State the response to a breach.

Example:

writ: bug-fixer
mandate: "The failing tests pass without changes to the tests."

grants:
  - read:  { paths: ["**/*"] }
  - shell: { commands: ["pytest *"] }
  - edit:  { paths: ["src/**"] }

bounds:
  iterations: 40
  cost: $2.50
  wall_clock: 20m
  edits:
    max_changed_lines: 200

invariants:
  - layer: letter
    untouched: "tests/**"

satisfaction:
  all:
    - layer: letter
      run: "pytest -x -q"
      exit: 0

remedies:
  on_bound_breach: { do: halt, inform: issuer }

Check layers

Each clause names the party that makes its check.

Layer	Check
letter	The registrar makes a deterministic check.
judgment	A separate judge model evaluates the clause.
assent	A person makes the decision.

The record keeps the layer with each check. A judgment is not shown as a deterministic result.

Run modes

Writ supports three run modes.

Mode	Command	Coverage
Embedded	writ issue <file>	Model turns, tool actions, effects, bounds, invariants, satisfaction, and remedies.
Model gateway	writ gate <file>	Model iterations, model cost, and tool names that cross the model API.
MCP sidecar	writ proxy <file> -- <server command>	Tool names and arguments that cross the MCP boundary.

The model gateway does not run tools. It cannot verify tool effects.

The MCP sidecar cannot see model iterations or model cost. It cannot verify effects outside the MCP calls.

Install

Install Writ with Homebrew:

brew install sirrobot01/tap/writ

You can also download a binary from the releases page.

Check the installation:

writ --version

Start a run

1. Create the engagement configuration.

   writ configure

2. Create a writ file.

   writ init bug-fixer

3. Add the required terms to bug-fixer.yaml.

4. Check the file.

   writ check bug-fixer.yaml --explain

5. Issue the writ.

   writ issue bug-fixer.yaml

6. Read the record.

   writ record bug-fixer

Commands

Command	Purpose
writ init	Create a writ file.
writ check	Validate and explain a writ file.
writ configure	Configure holders, judges, the sandbox, and assent.
writ issue	Run an agent under a writ.
writ gate	Govern an external agent at the model API boundary.
writ proxy	Govern an MCP server at the tool boundary.
writ record	Show the record of a run.
writ amend	Change the terms of a writ.

Development

Run all Go checks:

task check

Build the command:

task build

Read CONTRIBUTING.md before you send a change.

License

Writ uses the Apache License 2.0.

Brand files are in blog/brand/.