slopguard

Static checks for the specific failure modes of AI-generated code — the stuff that's correct but bad, which type checkers and default linters wave through: duplicated helpers, fields added "just in case", placeholder bodies, swallowed exceptions, comments that restate the code.

Designed to run as a hook inside AI coding agents (Claude Code and OpenAI Codex CLI), so the agent gets blocking feedback the moment it writes slop and fixes it itself — no human review pass needed. Zero dependencies, Python ≥ 3.9.

Install

pip install slopguards      # PyPI name is plural; the command is `slopguard`
slopguard install claude    # wire PostToolUse hook into ~/.claude/settings.json
slopguard install codex     # append hooks to ~/.codex/config.toml

(From a checkout: pip install . or pip install git+https://github.com/WT-MM/slopguard.)

Zero dependencies; running straight from a checkout via bin/slopguard works too (the installers prefer a pip-installed console script when one is on PATH, else they pin the checkout's launcher path).

Usage

slopguard scan <paths>            # human-readable report, exit 1 on warn+
slopguard scan --json --fail-on never
slopguard rules                   # list all rules

Rules

In test files (*.test.ts, test_*.py, __tests__/, …) the conventional patterns — as any mocks, repeated setup blocks, long functions — drop to info instead of blocking.

Test-suite rules (test files only)

These push toward minimal tests that pin observable behavior, not the implementation's wiring — the two big AI failure modes being over-mocking and over-specification:

Custom assert helpers are recognized (functions with assert/check/verify/ expect/validate in their name count as assertions), so helper-based suites aren't flagged as assertion-free. Parametrize groups of 6+ additionally suggest stating the rule once as a property-based test.

Contract-drift rules (when message schemas are in the repo)

Code that disagrees with a message schema fails at runtime; when the schema is in the repo, it's statically visible. Schema sources: Protobuf (.proto, message-scoped; .textproto instance data, file-scoped), Avro (.avsc), Thrift (.thrift), GraphQL SDL (.graphql/.graphqls/.gql), and JSON Schema / OpenAPI documents (*.json/*.yaml named like a schema — *schema*, openapi*, swagger*, asyncapi*). Discovery is automatic (scan: under the scanned paths; hook: each edited file's subtree, capped at 40 schema files and 1,000 directories to preserve edit latency), plus two .slopguard.json keys for schemas living elsewhere: "schema_roots": ["protos/"] (directories, searched recursively) and "contract_schemas": ["contracts/**/*.avsc"] (explicit globs), both resolved relative to the config file.

Matching is message-scoped: a dict literal must substantially match ONE message's fields (≥4 string keys, ≥75% of them fields of that message), so vocabulary from unrelated messages can't combine to legitimize a stray key. camelCase- and snake_case-declared schemas both work — keys are canonicalized before matching, and proto json_name aliases are honored. Checks apply to Python dict literals (proto3's JSON mapping legitimately camelCases in JS/TS):

Self-checking

tests/run_tests.py includes a scan-mode rule-coverage meta-test: every rule listed in slopguard rules must demonstrably fire on the test corpus, so an analyzer refactor can't silently kill a rule (this caught a real one: comment-masking had made @ts-ignore undetectable). Separate targeted tests cover hook target discovery and blocking behavior; the meta-test does not prove every rule is reachable through every hook protocol.

Hook behavior

Both agents speak the same protocol: hook gets a JSON event on stdin; exit code 2 with text on stderr feeds findings back to the model as blocking feedback the agent must address.

• Claude Code: PostToolUse on Edit|Write|MultiEdit|NotebookEdit — checks the file the agent just touched, immediately.
• Codex CLI: PostToolUse on apply_patch, plus a Stop hook that scans git-dirty files at end of turn (with a loop guard: the same finding set blocks a session's Stop only once).

Sibling same-extension files are loaded as context so duplicate detection sees the neighbors the agent should have reused, but findings are only reported for the files actually changed. Hooks fail open: an internal slopguard error never blocks the agent. Typical hook latency: <100 ms.

Escape hatches

• slopguard:ignore in a comment on (or directly above) the flagged line. Name rules to scope it — # slopguard:ignore swallowed-exception — expected on our own cancel() suppresses only that rule; a bare ignore suppresses everything on the line. Reasons after a dash are encouraged and never parsed as rule names.
• .slopguard.json at repo root: {"disable": ["long-function"], "max_function_lines": 120, "max_nesting": 5, "fail_on": "error", "hook_exclude": ["*/tests/fixtures/*"]}. hook_exclude uses fnmatch patterns against absolute paths and affects hook targets only; explicit scan paths are never excluded.
• SLOPGUARD_DISABLE=1 env var kills the hook entirely; SLOPGUARD_DISABLE_RULES=rule,rule disables specific rules.

Tests

python3 tests/run_tests.py

Fixtures in tests/fixtures/ deliberately contain every kind of slop; the suite asserts every rule fires there, that clean code produces zero findings, and that both hook protocols (block, pass, loop-guard, garbage stdin) behave.