Sloppatrol is a team of agents that patrols your repo and makes the code cleaner, one small pull request at a time. It never changes what the code does, and each pull request carries the proof.
- A surveyor agent reads the code and records opportunities: shallow modules, mixed concerns, hidden dependencies, tests that mock your own code.
- A refactorer agent makes one opportunity real, in its own git worktree.
- The gate is code, not a model. It keeps a refactor only when your checks pass and a planted bug turns a test red.
- Three blind assessor agents score the code before and after, on seven quality metrics. The target metrics must go up.
- A reviewer agent reads the change against your repo's rules. It can only reject.
It is the code-quality sibling of Bugpatrol and Speedpatrol.
npx sloppatrolnpx sloppatrol runs the patrol: survey, refactor, gate, prove, review, and publish, again and again. Verified refactors wait for sloppatrol publish until you turn on GitHub.
The patrol is light by default, so it can stay on next to your own work. It runs at low CPU and I/O priority, and only its assessors run side by side, since they wait on the model. It skips a cycle while the machine is busy, waits longer after each cycle that finds nothing, and runs at most 6 cycles a day. npx sloppatrol --once runs one cycle and exits, for a scheduled CI job. Configuration shows how to change each limit.
flowchart TB
start(["npx sloppatrol"]) --> pull["Pull main, run your checks, score more files"]
pull -->|green| survey["1 · Survey<br/>LLM · Surveyor records opportunities"]
survey --> refactor["2 · Refactor<br/>LLM · Refactorer edits a worktree"]
refactor --> gate["3 · Gate<br/>Code · guards, your checks, a planted bug"]
gate --> assess["4 · Prove the gain<br/>LLM · 3 blind assessors score before and after"]
assess --> review["5 · Review<br/>LLM · Reviewer, veto only"]
review --> publish["6 · Publish<br/>Code · a PR with its proof"]
publish --> wait["Wait for the next cycle<br/>longer while nothing is found, at most 6 a day"]
wait -->|"machine not busy"| pull
subgraph legend ["Legend"]
direction LR
l1["LLM agent"] ~~~ l3["Code, no model"] ~~~ l4["Off by default"]
end
wait ~~~ legend
classDef llm fill:#312e81,stroke:#a5b4fc,color:#ffffff
classDef code fill:#1e293b,stroke:#64748b,color:#e2e8f0
classDef opt fill:#1e293b,stroke:#64748b,color:#e2e8f0,stroke-width:2px,stroke-dasharray:6 4
class survey,refactor,assess,review,l1 llm
class start,pull,gate,wait,l3 code
class publish,l4 opt
style legend fill:transparent,stroke:#64748b
How it works shows each step of the gate, and the proof on each pull request.
Sloppatrol can score your code without the patrol. It changes no code and runs none of your checks, so it works on any repo.
-
Log in to Claude Code, Codex or opencode. Sloppatrol uses the agent that you have.
-
Go to the root of your repo, and create the config:
npx sloppatrol init
-
Optional: add your generated code to
ignorein.sloppatrol/sloppatrol.yml. A tool writes that code, so it must not change your score.ignore: [src/generated/**]
-
Score each file:
npx sloppatrol score
An assessor agent scores each file on the seven metrics, from 0 (worst) to 100 (best). Then Sloppatrol opens the scorecard in your browser. Click Download PNG or Copy image, and post it.
Sloppatrol scores the last commit on origin/main, not your local changes. The first run can take some minutes on a large repo. Sloppatrol keeps each score, so the next run scores only the files that changed. --files <n> scores at most n files in one run.
npx sloppatrol review 42 # a pull request number or URL
npx sloppatrol review feat/my-branchSloppatrol scores only the files that the pull request or branch changes. It scores each file at the head and at the merge base, and prints the change per file, worst first. A pull request compares with its base branch. A branch compares with patrol.pull (origin/main by default). --base <ref> sets another base. The command exits 1 when a file loses 10 points or more.
npx sloppatrol dashboard, or npx sloppatrol --dashboard with the patrol, serves a live dashboard on http://127.0.0.1:4322. The Overview tells you at a glance if the patrol is healthy: the checks on main, what waits for your decision, the code quality and its change, and the last cycle. Then it lists what needs attention, with the command to run next.
The other pages show each refactor as a pipeline with its proof, the scorecard of each file, every check run, the backlog in the order the refactorer picks it, and every agent session. The dashboard tells more.
-
Install the Sloppatrol skill in your repo:
npx skills add agent-labs-dev/sloppatrol
The skills CLI installs the skill for Claude Code, Codex, Cursor, and many other agents. It also writes
skills-lock.jsonat the repo root. Commit both, so your team gets the skill too. -
Give this prompt to your agent:
Set up Sloppatrol for this repo.
The skill tells the agent what Sloppatrol does, how to configure the checks of your repo, how to run it, and how to read the results.
If your agent cannot install skills, give it the skill URL:
Read https://raw.githubusercontent.com/agent-labs-dev/sloppatrol/main/skills/sloppatrol/SKILL.md and set up Sloppatrol for this repo.
To set it up by hand, read Getting started.
| Area | Supported |
|---|---|
| Languages | Any language with checks that you can run from a shell. The playbook has pages for TypeScript, React and React Native, Node backends, Python, Go, Swift, Kotlin and Rust. |
| Agents | Claude Code, Codex or opencode, with your existing login (agent: auto picks the installed one). Or an API key for Anthropic, OpenAI, OpenRouter, or a custom endpoint. |
| Repo rules | AGENTS.md, CLAUDE.md and their @ imports, CONTRIBUTING.md, GLOSSARY.md, and your decision records |
| GitHub | Pull requests through the gh CLI |
| Output | A local dashboard, GitHub pull requests, and JSON files under .sloppatrol/runs/ |
| Page | What it covers |
|---|---|
| Getting started | Add Sloppatrol to your repo, step by step |
| How it works | The cycle, the gate, the proof, your repo's rules, and the playbook |
| The metrics | The seven metrics, the rubric, and how the scorecard grows |
| Commands | All the CLI commands |
| Configuration | All the settings in .sloppatrol/sloppatrol.yml |
| Agents and models | The agent of each role, and the model providers |
| The dashboard | What each page shows |
| Playbook | The engineering practice that the agents follow |
| Glossary | The words Sloppatrol uses, with one meaning each |
| Decisions | Why Sloppatrol works this way |
| Contributing | Build Sloppatrol from source, the shape of the code, and releases |
Made with ❤️ by the Nebula team.