slopguard

SlopGuard CI Release v1.0.0 License: MIT

A fast, heuristic checker for common failure patterns in AI-generated code: Python AST rules, regex-based TypeScript/JSX rules, a C++20 byte prescreener and risk aggregator (with a pure-Python fallback), a Claude Code PostToolUse hook, and an MCP server.

AI coding agents can produce diffs faster than reviewers can spot recurring failure patterns: imports that do not resolve, empty .../pass/NotImplementedError stub bodies, except Exception: pass, tautological assert True or assertion-free tests, eval() sinks, and dead onClick={() => {}} handlers. slopguard flags these deterministically, typically in well under a millisecond per file, and exempts legitimate stubs (@abstractmethod, @overload, Protocol, .pyi, if TYPE_CHECKING:). It is a small rule-based linter (~1.75k lines of Python plus a ~170-line C++20 kernel), complementary to tests, type checkers and code review — not a replacement for them.


slopguard Audit Console

Architecture

flowchart LR
    Edit["Agent Code / Diff<br/>(.py · .ts · .tsx · Claude Hook stdin)"] --> Prescreen["C++20 Byte Scanner (clang++ -O3)<br/>(Bitmask flags: TODO / NotImplementedError / eval / assert True)"]
    Edit --> PyAST["Python AST Analyzer<br/>(Imports + Dead Stubs + Silent Excepts + Test Asserts)"]
    Edit --> TSUI["TypeScript / JSX UI Scanner<br/>(Empty handlers · Tautologies · XSS sinks)"]
    Prescreen --> RiskGate["C++20 Integer Risk Aggregator<br/>(0–100 score -> PASS / WARN / BLOCK)"]
    PyAST --> RiskGate
    TSUI --> RiskGate
    RiskGate -->|BLOCK exit=2| Hook["Claude Code PostToolUse Hook<br/>(Forces Self-Repair Before Final Turn)"]
    RiskGate --> UI["MCP stdio Server (.mcp.json)<br/>& Audit Console (:8120)"]

Measured Verification & Benchmarks

Verified locally (Python 3.13.9, clang++ -O3 C++20, Ollama qwen3.5:4b):

Check / Benchmark Exact Measured Result
Static Quality Gates 0 Ruff format issues · 0 Ruff lint issues · 0 Mypy --strict errors (21 files)
Pytest + Hypothesis Suite 12 passed · 97.12% statement coverage (differential C++20 vs Python parity across scan_bytes & aggregate_risk)
slopguard demo Latency 0.203ms (Sloppy Python BLOCK 100/100) · 0.284ms (Clean Python PASS 0/100) · 0.041ms (Sloppy React TSX BLOCK 70/100) · 0.030ms (Clean TSX PASS 0/100)
Claude Code Hook Gate Returns decision: "block" (exit=2) on hallucinated imports, TODO stubs, silent except: pass, and eval() sinks
Live qwen3.5:4b Repair Audit (6 tasks) v1 = 0.0% (0/6 passing) → v2 = 100.0% (6/6 passing + v2_syntax_valid = True) · 9 blockers eliminated · 2,157.07 ms avg repair time

Live Ollama (qwen3.5:4b) Guided Self-Repair Breakdown

Full artifact: benchmarks/real_qwen_slopguard.json

Task Lang v1 Slop (Blockers / Risk) v2 Guarded (Blockers / Risk) Syntax Valid Latency
SG-01 Hallucinated Import + JWT Stub python BLOCK (2 / 95) PASS (0 / 0) True 6003.52 ms
SG-02 Silent Except Swallow + Empty Dict python BLOCK (2 / 83) PASS (0 / 0) True 1437.16 ms
SG-03 Tautological Pytest (assert True) python BLOCK (1 / 65) PASS (0 / 0) True 800.17 ms
SG-04 Dead React onClick={() => {}} tsx BLOCK (1 / 72) PASS (0 / 0) True 1494.36 ms
SG-05 eval() Sink + NotImplementedError python BLOCK (2 / 100) PASS (0 / 0) True 2015.57 ms
SG-06 TypeScript expect(true).toBe(true) typescript BLOCK (1 / 85) PASS (0 / 0) True 1191.66 ms

Scope & Limitations

Install

# From PyPI (once published)
pip install slopguard

# From source (today)
git clone https://github.com/nagarjunak-pixel/slopguard.git && cd slopguard
uv sync --all-extras        # or: pip install .

The C++20 prescreener source (src/slopguard/_csrc/slopguard_kernels.cpp) ships inside the package and is compiled on first import with clang++ or g++ (cached in your temp dir). If no compiler is available, slopguard falls back to an equivalent pure-Python implementation. The React audit console (slopguard serve) and the recorded benchmark replay need a source checkout.


Quickstart

1. Install, Run Demo & Scan Any Repository

uv sync --all-extras
uv run slopguard demo
uv run slopguard scan . --strict

2. Enable Claude Code PostToolUse Auto-Verification Hook (.claude/settings.json)

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "uv run --directory /path/to/slopguard slopguard claude-hook"
          }
        ]
      }
    ]
  }
}

3. Drop-In Claude Code / Cursor MCP Server (.mcp.json)

{
  "mcpServers": {
    "slopguard": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/slopguard", "slopguard", "mcp-stdio"]
    }
  }
}

4. Interactive Audit Console & Live Ollama Re-Audit

cd ui && npm install && npm run build && cd ..
uv run slopguard eval-ollama --live-only
uv run slopguard serve --host 127.0.0.1 --port 8120

See ADR 0001 for the integer risk kernel and AST exemption rules.


Built by Nagarjuna Reddy Kamireddy (Nagarjuna Kamireddy / Nagarjuna K) — Lead AI Architect | Production Agentic AI, Hybrid RAG & LLM Evals (750K+ Workflows/Yr) | Ex-John Deere, GSK, Deloitte | AWS SA Pro & NVIDIA Agentic AI Certified.