Skip to content
wrt

writ start

Use writ start to add a writ to the agent workflow that is already running. The command does not launch an agent or change its harness. Your existing workflow must still give the task to the agent. Writ records the mandate, but the native hook does not add it to the agent prompt.

Terminal window
writ sessions --agent <agent>
writ start <file> --agent <agent> --session <session-id>

The agent must already have a healthy Writ connection. The agent can be claude, codex, cursor, or opencode.

Set WRIT_HOME to a directory outside the project. The command stops before it creates an activation when the Writ home is the project root or is inside it.

An attached writ is default deny across the complete agent tool surface. The selected hook must provide complete pre-tool coverage. Claude currently provides this coverage. Codex, Cursor, and OpenCode remain available for normal connections, but they cannot run an attached writ with the current hook contracts.

Select the session

Section titled “Select the session”

Make one complete tool call in the intended session. Then list the sessions that the current connection observed during the last 24 hours:

Terminal window
writ sessions --agent claude

Copy the intended session ID. Writ does not guess the session. The selected session must have no allowed tool call that is waiting for a result.

Check and start the writ

Section titled “Check and start the writ”

Check the target before you start:

Terminal window
writ plan task.yaml --agent claude
writ sessions --agent claude
writ start task.yaml --agent claude --session <session-id>

Writ performs these checks before it creates an activation:

  1. It validates and binds the writ file.
  2. It checks the complete grants allowlist.
  3. It compares every authored clause with the selected hook.
  4. It stops when an event or evidence source is missing.
  5. It checks the installed connection.
  6. It checks the selected session and its pending calls.

An unsupported plan names the exact writ path and missing capability. Writ does not ignore the clause.

After activation, continue in the selected agent session. The writ applies only to that session. Other sessions keep their normal connection policy. One agent can have one active writ in a project.

Writ creates one fail-closed marker for the selected provider session. Its filename contains the agent and a SHA-256 digest of the raw session ID. This keeps marker lookup correlated with the exact session. Read writ finish for recovery rules.

End the attached writ

Section titled “End the attached writ”
Terminal window
writ finish --agent claude

Run this command only when you accept that the work satisfies the writ. It writes a human satisfaction attestation after the selected session uses a tool. Use --cancel to stop without an attestation:

Terminal window
writ finish --agent claude --cancel

If the selected session did not use a tool, finish cancels the waiting activation and does not attest satisfaction.

Use --set name=value to bind a placeholder before planning. Repeat the flag for more values. Do not put a secret in the writ or a --set value. Activation state stores the bound document.

Use writ plan <file> --agent <agent> to inspect coverage without creating an activation. The /grants row and every authored clause must be enforced. Use writ issue when you want Writ to own the model loop and managed tools.