Ratchet

Ratchet is an open-source CLI tool built by 0xwilliamortiz that closes the feedback loop between the rules you give a coding agent and whether the agent actually followed them. It hooks into Claude Code's PostToolUse event, reads every file edit the agent makes, measures it against configurable budgets, and reports findings back into the same session while the agent is still working. The project is MIT-licensed, written in JavaScript, and requires Node 20 or newer.

What It Is

Ratchet is a complexity-enforcement harness for AI coding agents. The core insight is that prompt-only minimalism rulesets are open loops: the model reads "prefer the standard library, do not add dependencies, keep the diff small," and then nothing verifies compliance. Ratchet adds the verification half. It installs as a Claude Code plugin, registers PreToolUse and PostToolUse hooks, and runs a suite of static detectors on every Edit, MultiEdit, and Write the agent produces.

How the Detection Pipeline Works

Every agent edit passes through a set of tagged detectors:

• dep — catches new entries in package.json, requirements.txt, pyproject.toml, go.mod, Cargo.toml, Gemfile, or composer.json
• exists — finds a new symbol whose normalized name already lives elsewhere in the repository (e.g., formatDuration matches format_duration)
• stdlib — identifies hand-rolled versions of things the standard library already ships
• native — flags a dependency or code doing what the platform already does natively
• wrapper — detects a function whose body only forwards to another function with the same arguments
• yagni — surfaces interfaces, abstract classes, or protocols with a single implementation
• validation — catches bespoke email regexes
• budget — tracks running totals for new files, new dependencies, and net added lines

Findings are graded certain (parsed from a manifest), likely (structural analysis), or heuristic (shape matching). Only certain findings trigger a block in strict mode, which keeps false positives from becoming noise.

The Three Operating Modes

Ratchet ships with four modes that control how aggressively it enforces budgets:

The default is guard. Modes can be switched mid-session with /ratchet strict or persisted with /ratchet default advise, and the RATCHET_MODE environment variable also works.

The Mark, Ledger, and Baseline System

Ratchet's name comes from its core mechanic: existing complexity is grandfathered in via a baseline, and only new complexity is flagged. Running ratchet baseline fingerprints current findings by tag, path, and shape (not line number), so the baseline survives reformatting and code moving within a file. The .ratchet/mark.json file records an accepted codebase size — source lines, source files, a date, and a written reason. Raising the mark requires a deliberate command with a sentence of justification. The .ratchet/ledger.jsonl file appends one row per finished session, and ratchet report renders the trend as a small ASCII chart showing added lines, removed lines, new dependencies, flagged findings, and repo size over time.

Setup Path

Installation is a two-step process: clone the repository, run npm install -g ., then run ratchet once inside any project you want watched. That single command registers the hooks, sets a baseline, and on Windows opens ratchetui.exe — a bundled GUI that shows the live session state and ledger. Restarting the agent picks up the hooks. ratchet doctor validates the full loop by building a scratch repository, planting known problems, driving the hooks as real subprocesses, and printing exactly what the agent would have received.

Update: Recent Activity

The repository was created on 2026-07-31 and last updated on 2026-08-03, with 424 stars and 85 forks accumulated in its first few days. The project ships 115 tests covering both unit and integration scenarios, including a dedicated tests/windows.test.js that covers Windows path serialization bugs from any platform. The README documents two real bugs found by ratchet doctor and ratchet log on their first runs, signaling an actively debugged early release rather than a prototype.