anti-slop-py

A standalone, zero-dependency Python linter that rejects low-evidence, low-signal patterns — the ones coding agents leave behind when they reach for an escape hatch instead of naming a contract: Any and object parameters, cast cascades, unexplained # type: ignore, string-target module mocking, ad-hoc isinstance narrowing. A type checker permits all of these by construction, because they are legal holes in its own type system; anti-slop bans exactly those holes. Every diagnostic is written to be executed by an agent: it says what to write instead — parse at the I/O boundary, name the domain type, inject a real seam — not merely that something is forbidden. Vendoring is the primary installation model: the copy is meant to be read and adjusted to the team's standards, not depended upon, and in vendored mode nothing is installed at all. A standard pre-commit package hook is also supported (see "Use with pre-commit").

Requires Python 3.12+. Zero runtime dependencies.

Ruff finds Python problems. Type checkers find type problems. anti-slop catches the moment an agent silences the checker without adding evidence.

Analysis is purely syntactic — stdlib ast and tokenize, no type checker in the loop, no external dependency. Semantics beyond raw syntax come from a local scope table (lexical name and import resolution, alias chains) built once per file, the same "AST plus scopes, nothing heavier" discipline the original Oxlint plugin follows.

Port of dmmulroy/anti-slop (an Oxlint plugin for TypeScript) to Python semantics.

Status

All 15 core rules are implemented, with the full valid/invalid test matrix and self-lint clean on this repository's own source, plus the first opt-in contrib group (fastapi, 4 rules, off unless configured). Adoption tooling is in place: presets, a findings baseline, diff-scoped runs, and the review subcommand that composes them into a report on one change. no-adhoc-isinstance is turned off in this repository's own pyproject.toml for the reason recorded there — an AST analyzer's domain objects are themselves ast nodes, so isinstance over node classes here already is the recipe the rule prescribes, not the pattern it bans.

The ten-second version

An agent hits a type error and "fixes" it:

from typing import Any, cast


def promote(user: User) -> None:
    raw: Any = user
    admin = cast(User, raw)
    grant(admin)

The type checker is satisfied. anti-slop is not:

service.py:6:13 no-widen-then-cast `raw` is `user` widened to `Any` a few lines up, and this `cast` claims a narrow type back from it. … Delete the widening step and use `user` directly, with the type it already carries.
service.py:6:13 require-safety-comment `cast` to `User` asserts a claim the type checker cannot verify: from here on the value is `User` on your word alone, with nothing checked at runtime. …

Real output, trimmed at the ellipses. Both diagnostics end in a recipe, not a prohibition — written to be executed by the same agent that just wrote the slop.

Install into a repository (agent skill)

anti-slop-py is vendored, not depended upon. skills/install-anti-slop-py/ is the procedure for a coding agent: inspect the target repository, copy the linter in, merge [tool.anti-slop], wire up pre-commit and CI, hand Ruff its duplicate rules (ANN401, B009, B010, PGH003) over to anti-slop, run the linter, report the diff.

Add the skill to your agent with skills:

npx skills add TinyFrontier/anti-slop-py --skill install-anti-slop-py

then ask the agent to install anti-slop in the current repository. Alternatively, point the agent at skills/install-anti-slop-py/SKILL.md directly, or copy the files by hand:

cd /path/to/target-repo
python /path/to/anti-slop-py/skills/install-anti-slop-py/scripts/install.py
python tools/anti_slop --list-rules

install.py copies the package to tools/anti_slop/anti_slop/ and writes a tools/anti_slop/__main__.py launcher. Running the directory puts it on sys.path, so python tools/anti_slop lints the repository on its own interpreter (3.12+) — no install, no virtualenv, no PYTHONPATH. The script refuses to overwrite an existing destination without --force.

The skill's assets are a byte-identical copy of src/anti_slop:

python scripts/sync_skill_assets.py           # refresh after changing src/
python scripts/sync_skill_assets.py --check   # CI guard, fails on drift

Usage

python -m anti_slop src/            # check paths, or [tool.anti-slop].include
python -m anti_slop --list-rules
python -m anti_slop --explain no-widen-then-cast
python -m anti_slop --rule no-object-parameters src/
python -m anti_slop --generate-baseline           # accept today's findings
python -m anti_slop --diff origin/main            # only what this change touched
python -m anti_slop review --base origin/main     # that diff, read back as a review

Exit codes: 0 clean, 1 violations found, 2 configuration or usage error.

Configure in pyproject.toml:

[tool.anti-slop]
include = ["src", "tests"]
exclude = [".venv/**", "tools/anti_slop/**"]
# preset = "recommended"  # starting levels for the core rules; see "Presets"
# groups = ["fastapi"]    # opt-in rule groups; off unless listed here
# baseline = ".anti-slop-baseline.json"  # findings to hide; see "Baseline"

[tool.anti-slop.rules]
no-object-parameters = { level = "error", allow-object = false }
no-adhoc-isinstance = "warn"   # levels: "error" | "warn" | "off"

A warn-level rule reports its diagnostics (marked warning:) but does not fail the run: warn-only findings exit 0. Use it to stage contested rules during adoption — rule by rule here, or a whole tier at a time with a preset (see "Presets" below and "Opinionated by design"). To keep every rule at error while the findings that already exist stay out of the way, record them in a baseline instead (see "Baseline").

Suppress deliberately, and always by rule id:

def save(value: object) -> None:  # anti-slop: ignore[no-object-parameters]
    ...

# anti-slop: skip-file (in the first 5 lines) skips a whole file. A suppression without a rule id is a configuration error, not a silent blanket opt-out.

Presets

preset sets the starting level of every core rule at once, from the rule's own tier and confidence:

[tool.anti-slop]
preset = "recommended"

The two agent presets exist for the review subcommand (see "Reviewing an agent's diff"), and are equally usable as a project's own preset. A preset reads a rule's tier first and may then let its confidence relax the result: that is how minimal drops everything below high confidence, and how agent keeps a policy finding at warn no matter which tier files it. A confidence can only soften what the tier decided, never sharpen it.

[tool.anti-slop.rules] is applied on top and always wins, per rule — a preset is where a project starts, not a ceiling on what it can say afterwards. Setting only an option (no-object-parameters = { allow-object = true }) leaves the preset's level alone; naming a level replaces it. Omitting preset is not a preset: every rule starts at error, exactly as before presets existed. Rules of an opt-in group are never touched by a preset — they arrive with groups and are configured by name.

Explaining a rule

--explain <rule-id> prints why a rule exists, in five sections — what it catches, why it matters, what to write instead, when to turn it off, and its known false positives:

python -m anti_slop --explain no-widen-then-cast
python -m anti_slop --explain fastapi/no-state-attribute-access   # group not needed
python -m anti_slop --explain no-widen-then-cast --format json

It describes a rule rather than a repository, so it needs no configuration and works for the rules of an opt-in group without enabling the group. An unknown id exits 2 and suggests the closest names.

--list-rules shows each active rule's tier and confidence next to its summary, and --list-rules --format json emits the same catalogue as a stable machine-readable document — one object per rule with id, summary, tier, confidence, default_level (the level it runs at under the configuration that was loaded), fix (always "none"), tags, and options:

python -m anti_slop --list-rules --format json

One element of that array:

{
  "id": "no-unsafe-dict-values",