# Ratchet

> A PostToolUse hook for Claude Code that measures every edit an AI agent makes and reports whether it followed your minimalism rules, blocking or flagging new dependencies, files, and complexity in real time.

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:

| Mode | New files | New deps | Net added lines | On overrun |
|------|-----------|----------|-----------------|------------|
| `advise` | 8 | 3 | 400 | findings only |
| `guard` | 3 | 1 | 150 | findings and budget warnings |
| `strict` | 1 | 0 | 60 | the edit is blocked |
| `off` | — | — | — | nothing runs |

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.

## Features
- PostToolUse hook integration with Claude Code
- Real-time complexity measurement on every agent edit
- Dependency detection across package.json, requirements.txt, pyproject.toml, go.mod, Cargo.toml, Gemfile, composer.json
- Duplicate symbol detection with normalized name matching
- Standard library and native platform alternative detection
- Wrapper function and YAGNI pattern detection
- Three enforcement modes: advise, guard, strict
- Graded findings: certain, likely, heuristic
- Baseline system to grandfather existing complexity
- Mark and ledger for tracking complexity trend over sessions
- Per-line ratchet-ignore suppression with required reason
- ratchet doctor end-to-end validation command
- ratchet report ASCII trend chart
- Windows GUI (ratchetui.exe) for live session monitoring
- In-agent slash commands: /ratchet, /ratchet-review, /ratchet-audit, /ratchet-ledger
- Per-project and per-user configuration files
- RATCHET_MODE and RATCHET_LOG environment variable support
- Cached symbol index (warm cost ~4ms)
- Git-backed diff measurement against committed version
- Global hooks mode for all projects on a machine

## Integrations
Claude Code, Git, Node.js, npm, package.json, requirements.txt, pyproject.toml, go.mod, Cargo.toml, Gemfile, composer.json, PowerShell (Windows launcher)

## Platforms
WINDOWS, MACOS, LINUX, API, CLI

## Pricing
Open Source

## Links
- Website: https://github.com/0xwilliamortiz/ratchet
- Documentation: https://github.com/0xwilliamortiz/ratchet/blob/main/CONTRIBUTING.md
- Repository: https://github.com/0xwilliamortiz/ratchet
- EveryDev.ai: https://www.everydev.ai/tools/ratchet-agent-complexity-guard