A fast, deterministic quality gate for AI-assisted code.

slopfence finds the junk that AI coding assistants leave behind (hallucinated packages, tests that test nothing, placeholder stubs, duplicate helpers, swallowed errors and leftover chat text) before it gets merged.

🚧 Status: alpha (v0.2, Python only). Nine detectors work, each tuned against 20,000+ files of real-world code for false positives. Expect rough edges. Feedback is very welcome. See Contributing.

Quick start

pip install slopfence

Or run it without installing, using uv or pipx:

uvx slopfence .
pipx run slopfence .

Check a project:

slopfence .

Check only what your branch changed (ideal for pull requests):

slopfence --diff main

Options

Exit codes: 0 no issues (or none at or above --fail-on), 1 issues found, 2 error (bad options or config, or unparseable files with --strict).

Run slopfence with a Python at least as new as the syntax your code uses; otherwise newer syntax can't be parsed.

Configuration

Add a [tool.slopfence] table to the pyproject.toml at your project root:

[tool.slopfence]
select = ["SLOP001", "SLOP010", "SLOP020"]  # rules to run (default: all)
ignore = ["SLOP051"]                         # rules to skip
exclude = ["migrations", "tests/fixtures/", "*_pb2.py"]
known-packages = ["corp-auth", "corp-*"]    # private packages that aren't on PyPI
check-imports = false                        # true also looks up imports on PyPI (default: false)
detect-private-index = true                  # false if your private index only mirrors PyPI
fail-on = "high"                             # only high-severity issues fail the run
strict = true                                # unparseable files are an error

exclude works like .gitignore: a pattern without a / in the middle matches any file or folder name anywhere (migrations, *_pb2.py), and a pattern with one is relative to the project root (tests/fixtures/). Excluded files are never checked, but imports of excluded modules still count as your own code.

Command-line options (--select, --ignore, --exclude, --known-packages, --check-imports, --detect-private-index, --fail-on, --strict) replace the matching config values. Unknown keys and rule IDs are reported as errors (exit code 2).

Ignoring a finding

# In a real implementation, use the cache.  # slopfence: ignore[SLOP010]
x = legacy()  # slopfence: ignore

Put # slopfence: ignore-file anywhere in a file to skip it. In requirements.txt, add # slopfence: ignore to a line.

Private packages: if your project uses internal packages that aren't on PyPI, list them once in known-packages instead of adding ignore comments everywhere. Names are matched case-insensitively with -, _ and . treated alike (so corp_auth matches corp-auth), and * globs work. Known packages are never looked up on PyPI, and imports of them are never flagged.

SLOP010 (placeholders) also skips test code and demo or example code: files under demo/, examples/ or samples/ folders, or named like demo.py or auth_example.py.

What slopfence sends over the network

slopfence only talks to one server, https://pypi.org, and only for SLOP001. It sends a request per package name (HEAD https://pypi.org/pypi/<name>/json) and nothing else: no code, no file names, no telemetry.

Names in known-packages are never sent. Answers are cached for a day (missing) or a week (found) in ~/.cache/slopfence, so repeated runs send fewer requests. --offline sends nothing at all.

Private package indexes

If your packages may come from an index other than PyPI, a name that PyPI doesn't know could be a private package. slopfence then doesn't report it and doesn't send it to PyPI. It looks for private indexes in:

A private index in a project file stops lookups for that file's dependencies, and for imports with --check-imports. A private index in your environment (variables, pip or uv configuration) could serve any package, so SLOP001 makes no lookups at all and the report says so in a note. An index is public only if its host is pypi.org or pythonhosted.org. slopfence never prints index URLs, because they can contain credentials.

If your company index only mirrors PyPI, set detect-private-index = false (or pass --no-detect-private-index) to check packages against PyPI again, and list your own private packages in known-packages.

Imports with a different package name

With --check-imports, an import isn't looked up when a declared dependency or a locked package provides it, even if the names differ and the package isn't installed where slopfence runs. For example, import bs4 is covered by beautifulsoup4, import dateutil by python-dateutil, and from google.cloud import storage by google-cloud-storage. slopfence reads uv.lock, poetry.lock, pdm.lock, Pipfile.lock and Pipfile, so indirect dependencies count too (import idna when only requests is declared).

What the code-quality rules skip

To keep false positives low, the newer rules are deliberately conservative:

• SLOP011 stub functions needs a docstring that promises work (it starts with a verb like validate, fetch, send, calculate) or admits it isn't done (placeholder, TODO, for now). The body must then return hardcoded data while ignoring every input, or return nothing although the return type promises a value. A placeholder docstring over a body that does nothing (pass, ..., return None) is reported even without a return type. .pyi stub files are never checked. Abstract methods, @overload, properties, Protocol/ABC classes, if TYPE_CHECKING: blocks, documented hooks ("override this", "does nothing by default") and tests are skipped.
• SLOP030 duplicate functions ignores functions with fewer than 3 statements and test code. Parameter and variable names and docstrings don't matter; called functions, attributes and constants do. A full scan reports identical copies (every copy except the first). With --diff, functions you changed are also compared with the rest of the project and reported when they're ≥90% similar to an existing function, because that's when an assistant re-writes a helper that already exists. Never reported: methods with the same name in different classes (plugins, drivers), functions defined twice in one file (under if/try), near-duplicate methods, and parallel families that differ only by swapped names, operators or constants (md5_utf8/sha_utf8, polyadd/polysub).
• SLOP040 swallowed exceptions only flags except Exception, except BaseException and bare except: whose body is just pass or .... A comment in the handler (# best effort), cleanup code (__del__, __exit__, close(), atexit handlers, try: os.unlink(...), also in a loop), optional imports (try: import ujson), contextlib.suppress, tests and examples are skipped.

GitHub Action

# .github/workflows/slopfence.yml
name: slopfence
on: pull_request
permissions:
  contents: read
jobs:
  slopfence:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0
      - uses: syedmuhdahmad/slopfence@v0.2.0

On pull requests it automatically checks only the changed lines (set diff: none to check everything, or diff: <ref> for a specific ref). To show findings inline on the pull request, set sarif-file: slopfence.sarif and upload it with github/codeql-action/upload-sarif (needs security-events: write).

pre-commit

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/syedmuhdahmad/slopfence
    rev: v0.2.0
    hooks:
      - id: slopfence

The problem

AI coding tools (Claude, Copilot, Cursor, Gemini, Codex and others) are now part of everyday development. They write code fast, and that code usually looks correct. It compiles, it's well formatted, and it has comments and tests.

But it often comes with recognizable junk:

• Packages that don't exist. The AI imports flask-jwt-simple-auth because the name sounds plausible. Attackers now register these invented names to spread malware, a technique known as slopsquatting.
• Tests that test nothing. A test creates a mock, sets a value on it, then asserts that value. It passes forever and protects nothing.
• Placeholder code shipped as real code. Comments like # In a real implementation, validate the token above a function that returns True.
• Duplicate helpers. format_date(), formatDate() and date_formatter() in three different files, because the AI wrote a new helper instead of finding the existing one.
• Over-defensive code. try/except Exception: pass around code that can't fail, which hides real errors.
• Comment noise. # Increment counter by 1 above counter += 1, or leftover chat text like "Here's the updated function:".

Reviewers miss these because the code looks fine. Each one is small. Together they add up to security holes, false confidence from green test suites, and codebases that get harder to maintain every sprint.

Why existing tools aren't enough

No single tool focuses on the failure modes of AI-written code, built for reviewing pull requests. That's the gap slopfence fills.

slopfence vs. AI reviewers: complementary, not competing

Developer + AI writes code
        │
        ▼
slopfence            ← fast, free, same result every time; runs on every commit
        │
        ▼
AI / LLM review      ← deep reasoning about logic and design
        │
        ▼
Human review

AI reviewers are smart but nondeterministic and cost money on every run. slopfence catches the objective, repeatable problems in seconds with no API keys, so reviewers (human or AI) can spend their attention on what matters.

Who needs it

• Teams adopting AI coding tools that want a safety net without banning the tools.
• Open-source maintainers reviewing a growing number of AI-generated pull requests.
• Security teams worried about hallucinated or slopsquatted dependencies.
• Tech leads who want an objective quality gate instead of arguing over style in review.
• Solo developers who want to catch their AI assistant's mistakes before they commit.

Design principles

1. Detect patterns, not authorship. slopfence never tries to guess whether AI wrote the code. That's unreliable and leads to arguments. It flags low-quality patterns that AI commonly produces, no matter who wrote them.
2. Deterministic by default. Rule-based checks with no LLM required. The same input always gives the same output.
3. Diff-first. Check only what changed in a pull request. Nobody wants 4,000 warnings on an old codebase.
4. Low false positives over high recall. A noisy linter gets uninstalled. Start strict, flag only obvious cases, and make everything configurable.
5. Fits existing workflows. CLI, pre-commit hook, GitHub Action, and SARIF output for GitHub code scanning.

Detectors

Example output

$ slopfence --diff main
requirements.txt
  2:1      SLOP001  Dependency 'flask-jwt-simple-auth' does not exist on PyPI (possible hallucination)  [high]

src/auth.py
  5:5      SLOP010  Placeholder left in code: "In a real implementation, validate the token signature."  [medium]

tests/test_billing.py
  7:5      SLOP022  Test 'test_refund' catches assertion failures without re-raising, so it can never fail  [high]

tests/test_user.py
  4:1      SLOP020  Test 'test_user_name' only asserts on its own mocks and never calls real code  [high]

4 issues (3 high, 1 medium)

Architecture

┌─────────────┐   ┌──────────────┐   ┌──────────────┐   ┌───────────────┐
│   Files /   │──▶│    Parser    │──▶│  Rule engine │──▶│   Reporter    │
│   git diff  │   │ (ast / t-s)  │   │  (detectors) │   │ CLI/JSON/SARIF│
└─────────────┘   └──────────────┘   └──────┬───────┘   └───────────────┘
                                            │
                                  ┌─────────▼─────────┐
                                  │ Optional:         │
                                  │ - registry lookup │
                                  │   (cached)        │
                                  │ - LLM second      │
                                  │   opinion (--llm) │
                                  └───────────────────┘

• Parser: slopfence uses Python's built-in ast and tokenize (no dependencies). tree-sitter is planned so new languages can be added without rewriting the detectors.
• Registry lookups are cached locally (~/.cache/slopfence) to stay fast and avoid rate limits. If PyPI can't be reached, nothing is flagged: an unknown answer is never treated as "missing". Import names are only sent with --check-imports (see What slopfence sends over the network).
• Optional LLM mode (planned, not built yet) would send only the unclear cases for a second opinion. Never required.

Challenges (and how we plan to handle them)

Roadmap

v0.1 (MVP): Python

• CLI: slopfence . and slopfence --diff <branch>
• SLOP001 packages that don't exist on PyPI (dependency files and imports)
• SLOP010 placeholder comments
• SLOP020 / SLOP021 / SLOP022 fake tests
• SLOP051 leftover chat text
• Ignore comments
• JSON and SARIF output
• GitHub Action and pre-commit hook
• Publish to PyPI

v0.2: private code, new rules (released)

Tracked in the v0.2.0 milestone. Upcoming work is on the roadmap board.

Planned features

• Config file: [tool.slopfence] in pyproject.toml (#10)
• SLOP030 near-duplicate functions (#11)

Reliability

• Test the GitHub Action in a real workflow, including SARIF upload (#13)
• Test the pre-commit hook with pre-commit (#14)
• Allowlist for private packages (#15)
• Better import-name to package-name mapping (#16)
• Detect private indexes from pip.conf, uv and Poetry (#17)
• --fail-on severity threshold (#18)
• Option to fail on unparseable files (#19)
• Fewer SLOP010 false positives from "for demo purposes" (#20)
• Import lookups are opt-in, so private package names aren't sent to PyPI (#34)
• Smaller source distribution (#35)

New rules

• SLOP040 except Exception that silently swallows errors (#21)
• SLOP011 stub functions that only pass or return fake data (#22)

Project

• Demo GIF in the README (#24)
• Test coverage measured in CI (#48)
• Release v0.2.0 (#25)

Later

• SLOP050 comments that only restate the code (#23)
• Parallel processing for large repos (#12)
• JavaScript / TypeScript (npm registry)
• Slopsquatting risk scoring (SLOP002)
• VS Code extension
• Optional --llm second opinion

Contributing

The project is at the very start, which is the best time to shape it.

• 💡 Have an example of AI-generated junk? Open an issue with a code snippet. Real examples are the most valuable input for designing detectors.
• 🐛 Know a pattern we're missing? Propose a detector in an issue.
• 🗣️ Disagree with the approach? Open a discussion. Better now than after v1.

Please read CONTRIBUTING.md before opening a pull request. Everyone taking part is expected to follow our Code of Conduct. Found a security issue? Report it privately as described in SECURITY.md. Need help? See SUPPORT.md.

License

MIT