Skip to content
Back to search

sloppy

Static analysis for the debt AI agents leave in PHP: 26 rules, Claude Code hooks, git-diff review, a Rector and Pint fix pass, Pest expectations, CI annotations and an MCP server. Deterministic, local, no LLM.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Heyosseus/sloppy with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Heyosseus/sloppy'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/heyosseus--sloppy/badge.svg)](/listings/heyosseus--sloppy)

HTML

<a href="/listings/heyosseus--sloppy"><img src="/api/listings/heyosseus--sloppy/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

composer require --dev heyosseus/sloppy

vendor/bin/sloppy                   # scan the project (php artisan sloppy in Laravel)
vendor/bin/sloppy agents install    # make Claude Code check its own work

That's it: no configuration file, no account. Sloppy finds your source roots from `composer.json`. It runs on any PHP 8.3+ project, and adds ten Eloquent-aware rules when it finds Laravel 12 or 13.

A first scan of a codebase with history does not hand you hundreds of findings to work through. It lists the defects worth fixing first, sums up the rest per file, and offers to baseline what is already there.

Trying it before adding a dependency? Run `composer global require heyosseus/sloppy`, or [download the phar](https://github.com/heyosseus/sloppy/releases/latest/download/sloppy.phar). See [Getting started](docs/getting-started.md).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 241 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset=".github/assets/logo-dark.svg">
  4. <img alt="Sloppy" src=".github/assets/logo-light.svg" width="348">
  5. </picture>
  6. </p>
  7. <p align="center">
  8. <b>Your AI agent writes the PHP. Sloppy makes it clean up after itself.</b><br>
  9. It catches the code people regret — god methods, swallowed exceptions, N+1 queries —
  10. inside Claude Code, your CI and your Pest suite.<br>
  11. Deterministic and local: no model, no API key, no network.
  12. </p>
  13. <p align="center">
  14. <a href="https://github.com/heyosseus/sloppy/actions/workflows/tests.yml"><img alt="tests" src="https://github.com/heyosseus/sloppy/actions/workflows/tests.yml/badge.svg"></a>
  15. <a href="https://packagist.org/packages/heyosseus/sloppy"><img alt="packagist" src="https://img.shields.io/packagist/v/heyosseus/sloppy.svg"></a>
  16. <a href="https://packagist.org/packages/heyosseus/sloppy"><img alt="downloads" src="https://img.shields.io/packagist/dt/heyosseus/sloppy.svg"></a>
  17. <img alt="php" src="https://img.shields.io/packagist/dependency-v/heyosseus/sloppy/php.svg">
  18. <a href="LICENSE.md"><img alt="license" src="https://img.shields.io/packagist/l/heyosseus/sloppy.svg"></a>
  19. <a href="https://ko-fi.com/ratirukhadze"><img alt="ko-fi" src="https://img.shields.io/badge/Ko--fi-support-FF5E5B?logo=ko-fi&logoColor=white"></a>
  20. <a href="https://m8ven.ai/mcp/heyosseus/sloppy?s=readme"><img alt="M8ven Score" src="https://m8ven.ai/badge/mcp/heyosseus/sloppy"></a>
  21. </p>
  22. <p align="center">
  23. <img alt="What Claude Code runs after the agent edits a PHP file" src=".github/assets/agent.svg" width="780">
  24. </p>
  25. <p align="center"><sub>Real output. Claude Code runs this after every edit and hands it to the model, which fixes the catch block before you ever see it.</sub></p>
  26. ## Quick start
  27. ```bash
  28. composer require --dev heyosseus/sloppy
  29. vendor/bin/sloppy # scan the project (php artisan sloppy in Laravel)
  30. vendor/bin/sloppy agents install # make Claude Code check its own work (--host=gemini, --host=codex)
  31. ```
  32. That's it: no configuration file, no account. Sloppy finds your source roots
  33. from `composer.json`. It runs on any PHP 8.3+ project, and adds ten
  34. Eloquent-aware rules when it finds Laravel 12 or 13.
  35. A first scan of a codebase with history does not hand you hundreds of findings
  36. to work through. It lists the defects worth fixing first, sums up the rest per
  37. file, and offers to baseline what is already there.
  38. Trying it before adding a dependency? Run `composer global require heyosseus/sloppy`,
  39. or [download the phar](https://github.com/heyosseus/sloppy/releases/latest/download/sloppy.phar).
  40. See [Getting started](docs/getting-started.md).
  41. ## How the agent loop works
  42. Agents produce code fast, and they produce the same mistakes fast: the
  43. `catch (Throwable)` that hides a failure, the 200-line controller action, the
  44. query inside a loop. Code review catches them late. Sloppy catches them while
  45. the agent still has the code in hand.
  46. 1. **The rules go in first.** `CLAUDE.md` (or `AGENTS.md`, `.cursorrules`,
  47. Copilot, Windsurf, Gemini CLI, Laravel Boost) gets this project's rules, each written as
  48. an instruction the agent can follow.
  49. 2. **Every edit is checked.** After each change to a PHP file, Claude Code (or
  50. Gemini CLI, or Codex) runs Sloppy and hands the model anything *that edit* introduced, then the model
  51. fixes it.
  52. 3. **It can't finish dirty.** When the agent tries to call the task done, new
  53. findings at or above your threshold send it back to fix them.
  54. It's built never to get in the way. Findings a file already had are never
  55. reported, so the agent doesn't wander off "fixing" code nobody asked it to
  56. touch. The finish check blocks once, so a false positive costs one round trip,
  57. not the session. And if Sloppy can't run (no git, a broken config), the agent
  58. carries on. `sloppy agents uninstall` takes it all back out, leaving every
  59. other setting byte for byte as it was.
  60. There's also an [MCP server](docs/agents.md#mcp-server) for agents that should
  61. scan on demand. See [Coding agents](docs/agents.md).
  62. ## What it catches
  63. 34 rules, plus three checks that compare your change with its base, and five
  64. more that enforce an architecture you describe. Each one is tested to fire on
  65. the pattern *and* to stay silent on ordinary Laravel code.
  66. | | Rules |
  67. | --- | --- |
  68. | **Complexity** | `SL101` God Method · `SL102` God Class · `SL103` Excessive Nesting · `SL113` Long Parameter List |
  69. | **Duplication** | `SL104` Duplicate Logic · `SL111` Copy-Paste Drift, a near-copy whose one difference looks like an unfinished edit |
  70. | **Dead code & dependencies** | `SL105` Dead Private Method · `SL106` Unused Constructor Dependency · `SL112` Placeholder Implementation, the `// ... existing code ...` or "not implemented" left where a body should be |
  71. | **Error handling** | `SL107` Swallowed Exception |
  72. | **Readability** | `SL108` Redundant Condition · `SL109` Narrative Comment · `SL110` Defensive Programming Noise · `SL114` Nested Ternary |
  73. | **Laravel** | `SL201` Business Logic In Controller · `SL202` Inline Validation · `SL208` Direct External API Call · `SL209` Model Doing Too Much |
  74. | **Routes & migrations** | `SL211` Missing Route Action, a route to a controller method nobody wrote · `SL212` Logic In Route Closure · `SL213` Destructive GET Route · `SL214` Edited Migration, a migration changed after it already ran · `SL215` Irreversible Migration · `SL216` Model In Migration · `SL217` Unconstrained Foreign Key |
  75. | **Performance** | `SL203` Possible N+1 · `SL204` Query Inside Loop · `SL205` Collection Instead Of Query · `SL210` Suspicious `Model::all()` |
  76. | **Dependencies** | `SL206` Excessive Controller Dependencies · `SL207` Excessive Service Dependencies |
  77. | **Architecture** (advisory) | `SL301` Abstraction Inflation · `SL302` Empty Wrapper Class · `SL303` Single-Use Abstraction |
  78. | **Your architecture** (opt-in) | `SL304` Layer Violation · `SL305` Forbidden Capability, a query in a controller or `env()` in the domain · `SL306` Boundary Violation, one module reaching into another's internals · `SL307` Misplaced Class, a new class with no place in the architecture · `SL308` Role Shape, an action with a second public method |
  79. | **Suppression** | `SL501` Unexplained Suppression · `SL502` Baseline Growth, new entries in your PHPStan or Psalm baseline · `SL503` Weakened Test, a test skipped, stripped of assertions or given `assertTrue(true)` to make it pass |
  80. Every finding says **where** it is, **what** was measured, **how sure** the
  81. analyser is, **why** the pattern costs you, and **what to do** instead. See
  82. [Rules](docs/rules.md), or [write your own](docs/custom-rules.md).
  83. ## Beyond the agent
  84. The same analyser, wherever else you want the answer.
  85. **Start with what matters.** A first scan of a medium-sized application finds
  86. hundreds of things, and nobody reads hundreds of things. So `sloppy` lists the
  87. defects first (swallowed exceptions, queries in loops, unfinished bodies),
  88. highest risk first. It sums up the long methods and narrating comments per
  89. file, putting the files that keep changing at the top. Then it tells you which
  90. commands shorten the list without reading it: `sloppy fix` for the mechanical
  91. findings, `sloppy baseline` for the debt that is already there. `--all` lists
  92. everything.
  93. **Review a change.** `sloppy diff main` reports only what your branch
  94. *introduced*, never what it inherited; add `--merge-base` to compare with
  95. where your branch forked, as `sloppy ci` does. `sloppy review main` ranks the same
  96. findings by risk, so you know which file to read first and where to stop.
  97. ![php artisan sloppy:diff main](.github/assets/diff.svg)
  98. **Adopt it on a codebase with history.** `sloppy baseline` accepts today's
  99. debt, so only new findings fail the build. Entries are keyed on class and
  100. member, not line numbers, so the baseline survives ordinary editing.
  101. **Gate it in CI.** `sloppy ci` reads the pipeline it runs in: it annotates the
  102. diff on a GitHub pull request and fills the Code Quality widget on GitLab. The
  103. GitHub Action is three lines:
  104. ```yaml
  105. - uses: heyosseus/sloppy-action@v1
  106. with:
  107. diff-branch: main
  108. ```
  109. **Already on PHPStan?** Get the same findings inside the run you already have:
  110. ```bash
  111. composer require --dev heyosseus/phpstan-sloppy
  112. ```
  113. Each one is a PHPStan error with its own identifier (`sloppy.SL107`), so
  114. `@phpstan-ignore`, `ignoreErrors` and PHPStan baselines work on it. It reports
  115. exactly what `sloppy ci` would fail on. See
  116. [heyosseus/phpstan-sloppy](https://github.com/heyosseus/phpstan-sloppy).
  117. **Fail your tests on new debt.** A Pest plugin ships with the package:
  118. ```php
  119. it('has no new slop on this branch', function (): void {
  120. expectCleanSloppyDiff('main');
  121. });
  122. ```
  123. **Fix what a machine can fix.** `sloppy fix` hands the mechanical findings to
  124. Rector, scoped to the files that have them, deletes the comments that only
  125. restate their code, then formats with Pint. It tells you which findings still
  126. need a person, and why no tool should touch them.
  127. **Keep score while you work.** `sloppy watch` keeps the score and what to read
  128. first on screen, redrawing on every save. It's made to sit beside an agent that
  129. is writing code.
  130. **See it where you already look.** Use SARIF for GitHub code scanning and your
  131. IDE, `--format=github` for inline annotations, and Markdown for a PR comment.
  132. There's also a Filament widget, a NativePHP menu-bar label, and
  133. [JSON output](docs/json-output.md) with a published schema.
  134. See [Everyday workflow](docs/workflow.md) and [CI and code scanning](docs/ci.md).
  135. ## Why trust the numbers
  136. **It is not an AI detector.** Nobody can reliably tell from source code who or
  137. what wrote it, and Sloppy never tries. It detects patterns that turn into
  138. maintenance cost, whoever wrote them. A 200-line controller action that swallows
  139. a `Throwable` is a problem whether a person or an agent wrote it at 3am.
  140. | Sloppy says | It means | It does **not** mean |
  141. | --- | --- | --- |
  142. | `Confidence: 88%` | How sure the analyser is that the pattern is really there | Any probability that the code was AI-generated |
  143. | `Score: 67/100` | A code-quality risk measure for the analysed paths | "67% of this code is AI-generated" |
  144. **Every number shows its working.** Add `--explain-risk` and each score and risk
  145. prints the arithmetic that produced it. The same code always produces the same
  146. report, which is what makes Sloppy usable as a gate. See
  147. [Score, severity and risk](docs/scoring.md).
  148. **It is tuned for silence.** Rules need several signals, not one; they
  149. understand framework conventions; and they back off wherever code could be
  150. reached indirectly. Sloppy runs over its own source in CI, and a test asserts
  151. that ordinary Laravel code produces zero findings. The rules and the score are
  152. checked against eight open-source Laravel applications, 782,578 lines, where
  153. the four healthiest score 87 to 90.
  154. **It complements your tools rather than replacing them:**
  155. | Tool | Answers |
  156. | --- | --- |
  157. | PHPStan / Psalm | Is this type-correct? |
  158. | Pint / PHP_CodeSniffer | Is this formatted consistently? |
  159. | Pest / PHPUnit | Does this behave correctly? |
  160. | Rector | Can this be transformed mechanically? |
  161. | **Sloppy** | Is this shaped like code somebody will regret? |
  162. If PHPStan can prove it, Sloppy stays out of it.
  163. ## Documentation
  164. | | |
  165. | --- | --- |
  166. | [Getting started](docs/getting-started.md) | Install options, every command, your first scan and how a long one is triaged, adopting on an existing codebase |
  167. | [Coding agents](docs/agents.md) | Claude Code, Gemini CLI and Codex hooks, rulesets for every agent, Laravel Boost, the MCP server |
  168. | [Rules](docs/rules.md) | Every rule in detail, and how false positives are kept down |
  169. | [Everyday workflow](docs/workflow.md) | Diff and review, `sloppy fix` over Rector, Pint and narrating comments, Pest expectations, `watch`, Filament and NativePHP |
  170. | [CI and code scanning](docs/ci.md) | `sloppy ci`, the GitHub Action, GitLab, SARIF, annotations, exit codes |
  171. | [Score, severity and risk](docs/scoring.md) | How every number is calculated, and what coverage, git history and PHPStan baselines feed |
  172. | [Configuration](docs/configuration.md) | `config/sloppy.php`, where the binary looks for it, `sloppy-architecture.php`, and taming a noisy first run |
  173. | [JSON output](docs/json-output.md) | The machine-readable report and its contract |
  174. | [Custom rules](docs/custom-rules.md) | Writing your own rule, and where it shows up |
  175. ## Roadmap
  176. Still ahead: inline pull-request review comments, `sloppy explain` for a
  177. longer write-up of one finding, HTML reports, and more rules for the shortcuts
  178. agents take, such as configuration keys and routes that do not exist. Anything AI-assisted
  179. will be opt-in and separate: the analyser will always work with no API key, no
  180. network and no model.
  181. ## Contributing
  182. Found a false positive? That's a bug worth reporting, not a threshold to work
  183. around. [Open an issue](https://github.com/heyosseus/sloppy/issues). To work on
  184. Sloppy itself, see [CONTRIBUTING.md](CONTRIBUTING.md). `composer test` runs
  185. Rector, Pint, PHPStan at level 8, 100% type coverage and the suite.
  186. Security issues: see [SECURITY.md](SECURITY.md).
  187. ## License
  188. MIT. See [LICENSE.md](LICENSE.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.