Skip to content

Work with the ratchet

The ratchet file, sprawl-guard.ratchet.toml, records each violation you accepted. The size it had when you recorded it is its ceiling. sprawl-guard check fails when a recorded violation grows past its ceiling, and also when it shrinks below it, so that the file always matches the repository. Commit ratchet changes together with the source changes that caused them.

This ratchet file records a 640-line parser and a directory with 14 source files, both over the default limits, and a 2 MB image over a configured byte limit:

sprawl-guard.ratchet.toml
#:schema https://kpozin.github.io/sprawl-guard/schemas/v1/sprawl-guard.ratchet.schema.json
schema_version = 1
[[files]]
path = "src/parser.rs"
role = "production"
max_lines = 640
[[directories]]
path = "src/handlers"
role = "production"
group = "source"
max_direct_files = 14
[file_sizes]
"assets/hero.png" = 2000000
"models/weights.bin" = { max_bytes = 50000000, storage = "lfs" }

Each entry’s role says whether the production or the test limit applies. A directory entry’s group names the language group whose files it counts. Languages outside custom groups use source, except literate languages such as Markdown, which use documentation. Each file_sizes entry maps a path to the size in bytes of any file, source or not, under the limit from max_bytes_per_file. A file in Git LFS has a table with storage = "lfs" instead, under the limit from max_bytes_per_lfs_object. It records the content size, so the entry doesn’t change when Git LFS downloads the file. When a file moves into or out of Git LFS, its old entry becomes stale. Sprawl Guard versions without byte limits reject a ratchet file that has file_sizes entries. The commands below write the file. Edit it by hand only to resolve a merge conflict.

After you shorten a file or move files out of a crowded directory, the check reports the ratchet entry as stale. Preview the change, then write it:

Terminal window
pnpm exec sprawl-guard tighten
pnpm exec sprawl-guard tighten --write

tighten lowers each ceiling to the new size, or removes the entry when the file or directory is back within its limit. It never raises a ceiling or adds an entry.

When a file or directory has to exceed its limit for now, preview and write an entry for it. Pass the file or directory that is over its limit:

Terminal window
pnpm exec sprawl-guard update src/parser.rs
pnpm exec sprawl-guard update src/parser.rs --write

update adds entries for new violations but leaves existing ceilings alone. To let a recorded violation grow, add --allow-increases to both commands. The preview marks each raised ceiling with ! raise.

For a permanent exception, such as a vendored file, set a higher limit with an override instead. An override states its reason in the configuration.

Resolve a merge conflict in the ratchet file

Section titled “Resolve a merge conflict in the ratchet file”

Keep the entries from both sides, and where they disagree, keep the higher ceiling. Then run sprawl-guard tighten --write to lower each ceiling to the size of the merged code, and run sprawl-guard check. If both branches grew the same file or directory, approve the combined size with sprawl-guard update PATH --allow-increases --write.

Coding agents tend to satisfy a size limit by moving code into catch-all files or by raising the limit. Sprawl Guard comes with an agent skill that tells an agent how to run the check and how to fix each kind of failure. The npm package includes it at node_modules/@kpozin/sprawl-guard/skills/sprawl-guard/, and the GitHub repository has it too. Copy the sprawl-guard directory to where your agent loads skills, such as .claude/skills/ for Claude Code.

If your agent does not support skills, copy the directory to skills/sprawl-guard/ in the repository instead, and add a line like this to the repository’s agent instructions file:

Before declaring work complete, follow skills/sprawl-guard/SKILL.md.
© 2026 Konstantin Pozin