Writ plugin
Writ turns workflow rules into checks at tool-call time: Claude Code writes no code until you approve the plan and tests
- 317 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The `bootstrap-plugin.sh` script creates the environment, starts Neo4j in Docker and edits `~/.claude/settings.json`, `~/.claude/CLAUDE.md` and slash commands
- Hooks see every tool call, and the `audit.jsonl` log lives in `~/.local/state/writ/logs`
- The daemon listens on localhost without authentication and serves the hooks and the CLI
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add plugins/writDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The `bootstrap-plugin.sh` script creates the environment, starts Neo4j in Docker and edits `~/.claude/settings.json`, `~/.claude/CLAUDE.md` and slash commands
- Hooks see every tool call, and the `audit.jsonl` log lives in `~/.local/state/writ/logs`
- The daemon listens on localhost without authentication and serves the hooks and the CLI
This is third-party code. Review the repository files before installing.
What it does
Writ is a Claude Code plugin that moves workflow rules out of prompts and into code. It consists of hooks on Claude Code events, a local daemon and a Neo4j database in Docker that holds rules and decision records. A source write before an approved plan is blocked at the hook level. In `work` mode two gates stand between a request and the first source write: an approved plan in `plan.md` and approved test skeletons. A gate opens only on your `approved` reply to the agent's request, and the agent cannot approve itself. If `plan.md` changes after approval, writes are blocked again until a fresh `approved`. Credential paths such as `.env`, `*.key` and `~/.ssh/` stay closed at all times. For every prompt Writ adds matching rules, methodology and past decisions, and at commit time it links file changes to the plan. The `writ recall` command shows recorded decisions, and `writ audit-session` prints a timeline of refusals and approvals. Five agents ship with it: explorer, planner, implementer, test writer and reviewer.
Who it is for. Developers on Claude Code who need a verifiable agent workflow: plan, tests, then code. Teams get a log of why files changed.
Good fit when
- The agent starts on code right away with no plan, and you want to read the plan before the first edit
- A rule from `CLAUDE.md` fades in a long session, and a check that fires on every write is required
- A team records why a file changed, and `writ recall` should find the decision behind an edit
- Debugging should start from the cause: `debug` mode blocks code edits until a root cause is written in `debug.md`
- Agents are forbidden to touch `.env`, keys and paths outside the project, and the ban must hold without their consent
Not a fit when
- The machine runs Windows or has no Docker: the plugin needs Linux or macOS, Python 3.11 and Docker with a running daemon
- You need a quick draft or a one-off script: in `work` mode every write waits for an approved plan and tests
- The agent runs without a person, for example in CI: nobody can approve the plan and tests, because the gates read your reply through a prompt-submit hook
Example request
Add a `slugify()` function with tests to `src/textutil.py`. Show the plan first and wait for my approvedLimitations
- Writ constrains a cooperative agent and does not replace a sandbox. Shell inspection is pattern-based and misses paths built from variables, `eval` and `sh -c` bodies.
- The gates check that a plan and tests exist in the right shape. A person judges the quality of the plan and of the test assertions.
- The daemon listens on localhost without authentication. Some checks only report findings and block nothing.
- The author has not shown by experiment that delivering rules to the agent improves code quality.
How to disable. Disable or remove the plugin through the `/plugin` menu and restart Claude Code. The install script edited `~/.claude/settings.json` and `~/.claude/CLAUDE.md`, so check those files and stop the Neo4j container.
FAQ
How do I install Writ in Claude Code?
Run `claude plugin marketplace add infinri/Writ` and `claude plugin install writ@writ`. Open Claude Code in a project and Writ prints `bash <plugin root>/scripts/bootstrap-plugin.sh`, which you run in a terminal. After the `Writ plugin is ready` message restart Claude Code and check `writ status`.
Why did Writ block a file write?
In `work` mode, until a plan and test skeletons are approved, any code write is blocked. Read the plan, reply `approved` as a whole message after the agent asks, then approve the tests the same way. The section "Why was I blocked?" in `docs/install.md` explains each refusal.
Can the agent approve its own plan?
No. A prompt-submit hook reads your reply and mints a single-use token bound to the current gate and the fingerprint of `plan.md`. Token and session-state files are write-protected for the agent, and an attempt without a token is refused and logged.
How does Writ differ from rules in `CLAUDE.md`?
An agent has to find, keep and apply a rule from `CLAUDE.md` on its own. Writ checks the action with code at tool-call time and blocks the write. Writ rules also reach the context, but only hooks block writes, and the rule text stays a hint.
Which modes does Writ have?
Five: `conversation`, `review`, `investigate`, `debug` and `work`. The plan and test gates apply only in `work`, and `debug` blocks code edits until a root cause is written. The mode is picked automatically from the prompt or with `writ mode set <mode> <session_id>`.
Discussion
No questions or reviews yet.
Related
PluginsA 13-skill delivery workflow for coding agents: from idea to plan, review, security audit, tests and a shipped pull request
A Claude Code working configuration: a planner with per-milestone review, sub-agents and skills for analysis, refactoring and docs sync
planr keeps agent-driven development tasks in Git Markdown files and shows what is ready, blocked and waiting on you
A plugin for Claude Code and Codex with xdo, xdel and xflow modes: a main agent plans, a coder builds, an evaluator checks.
A Claude Code plugin for development with separated roles: spec, review, TDD, QA and verification by different agents
The /improve skill: a strong model audits a repository and writes self-contained fix plans, and you hand the execution to a cheaper model
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| Writ (this card) | no | 317 | |
| HOL Guard | yes | 1,094 | checks risky commands, secret reads and package installs, and does not impose a plan-tests-code order |
| TDD Guard | no | 2,375 | blocks code without a failing test and does not require an approved plan |
| Superpowers | no | 316,679 | a skill set with a development process that rests on prompts and has no hook blocks |
README in short
The README opens with an 81-second demo and a table of gates with all refusal codes such as `[ENF-GATE-PLAN]`. A session example from request to commit follows, then the modes and three layers: context, enforcement, continuity. The limits section gives rule-retrieval measurements on 193 queries and notes that a gain in code quality is not shown by experiment.