writty

Writ

A Claude Code harness that gives every coding session two helpers: a fast librarian that picks the rules that fit the current task, and a process keeper that blocks risky writes until you have approved a plan and tests.

At the live 276-rule production corpus (post Phase 1-5 public-rulebook expansion), the librarian returns ranked results in 0.590 ms at the 95th percentile. At the 10,000-rule synthetic scale, it still holds at 0.557 ms while reducing context tokens by 726 times versus loading the whole rulebook every turn.

See CHANGELOG.md for the v1.5.0 release notes (workflow content migrated into RAG-surfaced Methodology nodes, writ import-markdown unified as the single ingestion entry point) and the full release history back to v1.0.0. OVERVIEW.md explains the most recent work: in-flight hook envelope rewriting, blocking stop gates, and the retrieval relevance floor.

Browse the architecture in your browser

Four self-contained HTML pages render the whole system. No clone or install required: open any link below and walk the diagrams. A sticky top nav inside each page cross-links to the other three, so you can flip between layers without coming back to the README.

• Complete overview: seven diagrams (system block, session flowchart, query sequence, pipeline funnel, mode/phase state machine, knowledge graph excerpt, rule-evolution lifecycle) covering the full system end to end. Start here.
• Architecture layers: eight tabbed layer cards (pipeline, weighting, mandatory-vs-retrieved split, knowledge graph, mode system, phase gates, enforcement layer, evolution model) with plain-English summaries and technical drill-in.
• Workflow flowchart: long-ways START-to-END SVG process flowchart of one Writ-enforced coding session, with rectangles for steps, diamonds for decisions, and dashed loop-back arrows for the iterate-until-it-passes gates. The description and step detail stay anchored in a sticky left rail.
• Commands reference: every CLI command, every writ-session.py subcommand, and every HTTP endpoint, tabbed by group with live filter.

These four pages live at the repo root (writ-complete-overview.html, writ-architecture-flowchart.html, writ-workflow-flowchart.html, writ-commands.html) and are served by GitHub Pages from main. Clone and open locally for offline browsing, or follow the links above straight from a browser tab.

Install as a Claude Code plugin

Writ is published as a single-plugin marketplace in this repo.

Prerequisites

• Python 3.11 or newer
• Docker (Neo4j runs in a container)
• jq, curl, envsubst

Install

claude plugin marketplace add infinri/Writ
claude plugin install writ@writ

One-time bootstrap. Creates the venv at ${CLAUDE_PLUGIN_DATA:-$HOME/.cache/writ}/.venv, brings up Neo4j, ingests the rule bible, and starts the FastAPI daemon:

bash $(claude plugin path writ)/scripts/bootstrap-plugin.sh

Restart Claude Code. Verify with:

curl http://localhost:8765/health
# {"status":"healthy"}

Patch global config (plugin mode only). Plugin installs do not write to ~/.claude/settings.json or ~/.claude/CLAUDE.md. The Writ-specific Bash allowlist that suppresses permission prompts for read-only and onboarding commands is missing, and the mandatory-workflow instructions that Writ relies on are not installed either. Run this once after bootstrap to bring ~/.claude/ up to the state a standalone install would produce:

bash $(claude plugin path writ)/scripts/patch-global-config.sh
# Use --dry-run first to preview the diff.

The script does two things: merges the cross-mode allow and deny entries into ~/.claude/settings.json (existing ordering preserved), and renders templates/CLAUDE.md into ~/.claude/CLAUDE.md. Both steps are idempotent (no-op when already in sync) and back up any pre-existing file before writing. Standalone-install users do not need to run it; scripts/install-harness-config.sh already produces the same output.

The plugin's hooks degrade gracefully until bootstrap completes. The SessionStart hook prints clear setup instructions on every fresh session where any prerequisite is missing, but the session itself is never blocked.

The standalone install path at ~/.claude/skills/writ/ remains supported; see "Quick start" below if you prefer that mode.

The problem

Three things break when you give a coding agent a large rulebook the obvious way (paste it all into the prompt):