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:
#:schema https://kpozin.github.io/sprawl-guard/schemas/v1/sprawl-guard.ratchet.schema.jsonschema_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.
Record an improvement
Section titled “Record an improvement”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:
pnpm exec sprawl-guard tightenpnpm exec sprawl-guard tighten --writenpm exec -- @kpozin/sprawl-guard tightennpm exec -- @kpozin/sprawl-guard tighten --writeuv run sprawl-guard tightenuv run sprawl-guard tighten --writesprawl-guard tightensprawl-guard tighten --writesprawl-guard tightensprawl-guard tighten --writetighten 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.
Approve a new violation
Section titled “Approve a new violation”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:
pnpm exec sprawl-guard update src/parser.rspnpm exec sprawl-guard update src/parser.rs --writenpm exec -- @kpozin/sprawl-guard update src/parser.rsnpm exec -- @kpozin/sprawl-guard update src/parser.rs --writeuv run sprawl-guard update src/parser.rsuv run sprawl-guard update src/parser.rs --writesprawl-guard update src/parser.rssprawl-guard update src/parser.rs --writesprawl-guard update src/parser.rssprawl-guard update src/parser.rs --writeupdate 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.
Guide coding agents
Section titled “Guide coding agents”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.