Sloppy

Static analysis for the code-quality patterns AI coding agents leave behind. Runs on any PHP project — 25 rules, plus a Laravel set that knows Eloquent, controllers and queues. Hands the mechanical fixes to Rector and Pint, fails your Pest suite on new debt, annotates the pull request, and teaches the agent through CLAUDE.md and MCP. Deterministic and local — no model, no API key, no network.

Sloppy reads your PHP with a real parser and reports the shapes that turn into maintenance cost: god methods, swallowed exceptions, likely N+1 queries, business logic in controllers, abstractions that never earned their keep.

It ships 25 rules, a git-diff review mode and a baseline for existing projects; a CI command that reads your pipeline instead of asking you to describe it, with an official GitHub Action and a GitLab template; an automated fix pass that hands the mechanical findings to Rector and the formatting to Pint; a Pest plugin, so new debt fails in the same red-green loop as everything else; and, for the agents writing the code, a generated ruleset for CLAUDE.md and its equivalents plus an MCP server they can check their own work against.

Every screenshot on this page is real output from the command in its caption.

It is not an AI detector

Nobody can reliably prove authorship from source code, and a tool that claimed to would be selling you a coin flip with a progress bar. Sloppy never guesses who or what wrote a line. It detects slop — patterns that correlate with fast, unreviewed output and with technical debt generally. A 200-line controller action that writes to four tables, calls a payment API and swallows a Throwable is a problem whether a person, an agent or a pair of them wrote it at 3am.

So every number is about the code, never about its author:

| Sloppy says | It means | It does not mean | | --- | --- | --- | | Confidence: 88% | How sure the analyser is that the pattern it describes is really present | Any probability that the code was AI-generated | | Score: 67/100 | A code-quality risk measure for the analysed paths | "67% of this code is AI-generated" | | SL107 Swallowed Exception | This catch block does nothing observable with the failure | An accusation about who wrote it |

Sloppy is deterministic and local. Your source never leaves the machine, and the same code always produces the same report — which is what makes it usable as a gate.

Install

composer require --dev heyosseus/sloppy

php artisan sloppy          # Laravel
vendor/bin/sloppy           # any PHP project

The service provider is discovered automatically. Publish the config when you want to tune it:

php artisan vendor:publish --tag=sloppy-config

Or without adding a dependency

Deciding whether a tool is worth a composer.json entry is easier once you have seen what it says about your code. Two ways to run it against a project that has never heard of it:

# Once per machine, for every project on it
composer global require heyosseus/sloppy
sloppy                                    # run it from anywhere inside a project

# Or a single file, no Composer resolution at all
curl -L -o sloppy.phar https://github.com/heyosseus/sloppy/releases/latest/download/sloppy.phar
chmod +x sloppy.phar
./sloppy.phar

Both work with no configuration file. Sloppy finds the project by walking up to the nearest composer.json, and analyses the PSR-4 source roots declared there when there is no config/sloppy.php to say otherwise — so src/ on a framework-free project and app/ on a Laravel one are both found on their own. Pass --project when the directory it picked is not the one you meant.

Everything works this way except the php artisan sloppy:* commands themselves, which need the package installed in the project. sloppy fix still drives Rector and Pint, because it resolves them from the analysed project's vendor/bin rather than its own.

Each release attaches sloppy.phar.sha256 alongside the binary, if you want to check it:

curl -L -o sloppy.phar.sha256 https://github.com/heyosseus/sloppy/releases/latest/download/sloppy.phar.sha256
sha256sum -c sloppy.phar.sha256

Requirements: PHP 8.3+. Laravel 12 or 13 for the Artisan commands and the SL2xx rules; everything else runs anywhere.

Which command do I want?

php artisan sloppy:help      # or: vendor/bin/sloppy guide

Eleven commands, and the moment each one belongs to. Both names run the same code, so use whichever your project has.

| Every day | | | |---|---|---| | sloppy | sloppy scan | Analyse the project and rank what is worth reading first | | sloppy:diff | sloppy diff | Report what a change introduced, against a git revision | | sloppy:review | sloppy review | The same change, ordered by risk rather than by file | | sloppy:baseline | sloppy baseline | Accept what is already there, so only new findings fail | | sloppy:watch | sloppy watch | Keep the score on screen, redrawing as files change | | sloppy:help | sloppy guide | This list | | In a pipeline | | | | sloppy:ci | sloppy ci | Analyse a change the way the surrounding CI system reports it | | sloppy:fix | sloppy fix | Hand the fixable findings to Rector, then format with Pint | | sloppy:health | sloppy health | The score and what is dragging it down, from a cached snapshot | | For agents | | | | sloppy:rules | sloppy rules | Write this project's rules into CLAUDE.md, AGENTS.md and friends | | sloppy:mcp | sloppy mcp | Serve scan, diff, rules and health over MCP |

For one command's options, sloppy help or php artisan sloppy: --help.

Contents

• [Which command do I want?](#which-command-do-i-want) · [Scan a project](#scan-a-project) · [Anatomy of a finding](#anatomy-of-a-finding)
• [Review a change](#review-a-change) · [Adopt on an existing codebase](#adopt-on-an-existing-codebase)
• [Does it just complain about everything?](#does-it-just-complain-about-everything)
• [Slop score](#slop-score) · [Severity and confidence](#severity-and-confidence)
• [Rules](#rules) · [Configuration](#configuration) · [Custom rules](#custom-rules)
• [What to read first](#what-to-read-first) · [Risk](#risk)
• [JSON output](#json-output) · [Editors and code scanning](#editors-and-code-scanning)
• [Exit codes](#exit-codes) · [CI](#ci) · [GitHub Action](#github-action) · [GitLab CI](#gitlab-ci)
• [Fix what can be fixed](#fix-what-can-be-fixed) · [What it can fix](#what-it-can-fix-and-what-it-will-not-pretend-to) · [In your test suite](#in-your-test-suite)
• [Watch while you work](#watch-while-you-work) · [Filament and NativePHP](#filament-and-nativephp) · [Rules for coding agents](#rules-for-coding-agents) · [Custom rules for agents](#your-custom-rules-teach-the-agents-too) · [MCP server](#mcp-server)
• [What Sloppy is not](#what-sloppy-is-not) · [False positives](#false-positives)

Scan a project

php artisan sloppy                  # the configured paths
php artisan sloppy --path=app/Services
php artisan sloppy --rule=SL101 --rule=SL107
php artisan sloppy --min-confidence=80
php artisan sloppy --explain        # include each rule's "why this matters"

The screenshot at the top of this page is that command run against a small application written badly on purpose. It ships as tests/Fixtures/Sloppy, so you can reproduce it.

Anatomy of a finding

One file, seven findings, the whole report:

Every finding carries the same five things: where it is, what was measured, how sure the analyser is, why the pattern is often a problem, and what to do about it. The last one is the point — a finding you cannot act on is noise with a line number.

Review a change

The most useful command if you work with coding agents:

php artisan sloppy:diff             # working tree vs HEAD
php artisan sloppy:diff HEAD~1      # vs the previous commit
php artisan sloppy:diff main        # everything this branch changed

It separates what your change introduced from what it merely inherited, and only new findings can fail the build.

Three things worth knowing about how it works:

• It reviews the working tree, not just commits. Uncommitted and untracked

files are included, so an agent's new class is reviewed before it is committed rather than after.

• Findings are matched by fingerprint, not by line number. Adding an import

at the top of a file does not turn every existing finding in it into a new one.

• Cross-file rules still see the whole project. Rules only run on changed

files, but the project index is built from everything, so SL303 can still tell that an interface has exactly one implementation in a file the diff never touched.

Adopt on an existing codebase

Turning Sloppy on for the first time should not mean fixing everything first. Record what is there today, commit the file, and gate on what comes next:

php artisan sloppy:baseline

Baseline entries are keyed on rule, file and a rule-supplied fingerprint — usually a class and member name — and deliberately not on line numbers, so a baseline survives ordinary editing. If a finding occurs more often than the baseline recorded, the extra occurrences are new.

--force replaces an existing baseline; --rule= baselines only some rules.

Does it just complain about everything?

That is the failure mode of every analyser, so Sloppy runs its whole rule set over its own source in CI:

One finding, and it is a real one: NodeHelper is a large class. Splitting it into five so that rules import three of them to ask three questions would be exactly the ceremony this package exists to discourage, so the decision is recorded in tests/Feature/SelfCheckTest.php with its reasoning — and that test fails on any new finding about Sloppy's own code. Four others it found were genuine, and they were fixed.

The other half of the answer is tests/Fixtures/Good: deliberately ordinary Laravel code, with a test asserting that all 25 rules report zero findings on it at a score of 100.

What to read first

sloppy:diff answers did this change make it worse? sloppy:review answers the question you have immediately afterwards: of everything this change touched, what deserves reading?

vendor/bin/sloppy review origin/main
php artisan sloppy:review origin/main

  Sloppy review

  161 file(s) changed, 12,198 lines  ·  score 5 → 12 (+7)

  Read in this order
    1. app/Actions/Product/CloneProductToTenantAction.php   risk 70.5
         new SL111 Copy-Paste Drift  (76%, risk 9.9, in hunk)
         new SL102 God Class  (73%, risk 9.5, in hunk)
         new SL111 Copy-Paste Drift  (68%, risk 8.8, in hunk)
         new SL204 Query Inside Loop  (84%, risk 4.4, in hunk)
         and 9 more in this file, 2 x SL104, 7 x SL204
    2. app/Filament/Imports/B2bCatalogImporter.php   risk 48.0
         new SL102 God Class  (91%, risk 11.8, in hunk)
         new SL101 God Method  (76%, risk 9.9, in hunk)

  Skim
    4 file(s), risk under 5
      app/Support/TenantFrontend.php  risk 3.4

  No attention needed
    132 file(s) changed with no findings

  Resolved by this change
    3 finding(s) no longer reported
      2 x SL101 God Method
      1 x SL204 Query Inside Loop

Three tiers, so you know where to stop. Same analysis, same score and the same exit code as sloppy:diff — only the presentation differs, so adopting the reading order changes no build outcome.

in hunk is the part no other tool can do. A god method your change created and a god method it merely stood next to are not the same finding. Telling them apart needs the diff's hunks at rule time, and nothing else in this space has them.

Risk

Risk and the slop score answer different questions, and conflating them leads a team to chase the wrong one.

| | Slop score | Risk | | --- | --- | --- | | Question | How is this codebase? | What should I read next? | | Normalised | Yes, by size | No, absolute | | Aware of your change | No | Yes | | Moves a baseline | Yes | Never |

risk = severity_weight × (confidence / 100) × novelty × proximity × reach × exposure

reach     = 1 + log10(1 + blast_radius) × reach_weight
novelty   = new 1.0 | inherited 0.25
proximity = inside a changed hunk 1.0 | elsewhere in a touched file 0.3
exposure  = 1 + (1 − coverage) × exposure_weight | 1.0 when no coverage report

Every factor defaults to 1.0 when it cannot be measured, which is what makes the model safe to extend: a project with no coverage report ranks exactly as it did before exposure existed.

Reach is logarithmic on purpose. A class with two hundred callers is not two hundred times more urgent than one with a single caller; the tenth caller costs less new attention than the first. One usage yields 1.30, ten yields 2.04, a hundred yields 3.00 — a 2.3× spread across two orders of magnitude, which is roughly the spread a reviewer actually feels.

A file's risk is the raw sum of its findings, not their density. A file with twelve findings should be read before a file with one, even if it is longer. Density is the right measure for quality and the score already provides it; total is the right measure for attention.

Every weight lives under sloppy.risk and every one is documented in config/sloppy.php. Set reach_weight to 0.0 to rank on severity and confidence alone.

Show me the arithmetic

Add --explain-risk to any command and every derived number prints its own working:

vendor/bin/sloppy scan --explain-risk

    108  HIGH     SL102  God Class  (91% confidence)
         NodeHelper spans 1021 lines with 59 methods…
         → Group the members that change together…
         risk  10.0 (high) × 0.91 (confidence) × 1.00 (novelty unknown) × 1.00 (whole file) × 2.45 (27 usages) = 22.27

A tool that weights findings owes you its weights. A number you can watch it derive is not a magic number.

Slop score

A single deterministic number for the analysed paths:

penalty  = Σ  weight(severity) × confidence / 100
units    = max(1, analysedLines / lines_per_unit)
density  = penalty / units
coverage = min(1, Σ affectedLines / analysedLines)
score    = 100 − min(100, density × penalty_multiplier × (1 + coverage))

• Step 1 makes a finding we are half sure about cost half as much.
• Step 2 normalises by codebase size, so a large application is not punished

merely for being large.

• Step 4 doubles the penalty when findings blanket the codebase and barely

moves it when they are localised.

Default weights are critical: 20, high: 10, medium: 4, low: 1.5, info: 0.5. Weights, the multiplier, lines_per_unit and the band thresholds are all configurable under sloppy.score. Same input, same score — always.

Because the score is a density, a small codebase full of findings bottoms out quickly: the 472-line demo application in the first screenshot scores 0. That is the arithmetic working, not a verdict on 472 lines of anything.

Severity and confidence

They answer different questions, and both appear on every finding.

Severity — how much this matters if it is real. critical, high, medium, low, info. Set by the rule, overridable per rule in config. This is what fail_on compares against.

Confidence — how sure the analyser is that the pattern it describes is actually present, 0–100. A 300-line method is a measurement, so confidence is high. A possible N+1 depends on eager loading the analyser may not be able to see, so confidence is lower. Abstraction inflation is a heuristic, so it never reports above 78.

No rule ever reports 100% confidence. These are heuristics, and a heuristic that claims certainty is lying.

Rules

25 rules ship. Every one has tests proving both that it fires on the pattern and that it stays quiet on ordinary Laravel code.

PHP

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Heyosseus
• Source: Heyosseus/sloppy
• License: MIT

Install and usage instructions live in the source repository linked above.