Skip to main content
Glama

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)"]

Related MCP server: predictive-debugger

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

  • Heuristics, not proofs. Python checks are AST pattern rules; TypeScript/JSX checks are regex/line-based (no TS parser), so they can miss obfuscated cases and can false-positive on unusual formatting. The placeholder-phrase rule (e.g. "todo", "placeholder") is intentionally noisy in UI/text files.

  • Import resolution depends on the environment. "Unresolved import" means the module is not in the stdlib, not a workspace module, and not found by importlib.util.find_spec in the interpreter running slopguard. Run it in the project's own environment, or expect false positives.

  • Small, self-constructed benchmark. The live audit is 6 hand-written "sloppy" snippets repaired once by a local qwen3.5:4b model at temperature 0. v2 PASS means slopguard's own rules no longer fire and the output parses — it does not mean the repaired code is functionally correct, and the evaluation is circular by design (it measures whether findings are actionable).

  • Latency numbers are single runs of slopguard demo on small snippets on one laptop; large files and whole-repo scans will be slower.

  • Language coverage is Python and TypeScript/JSX only.

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables coding agents to run deterministic completeness audits on code before declaring 'done'—catching unwired modules, placebo tests, swallowed errors, and stubs via AST analysis, entirely offline and free.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables coding agents to identify likely runtime failures in JavaScript and TypeScript by ranking risky files, tracing dependencies, analyzing logs, and obtaining independent model reviews with line-level reasons.
      7
      53 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      It lets clients request design-time audits of Python and TypeScript agent applications for defects such as unbounded loops, ungated destructive actions, weak argument validation, insufficient run budgets, absent resiliency controls, overlooked evals, and poor observability. Findings include supporting evidence and feed an approval-driven mechanism for reviewing proposed fixes without mutating the original source.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables coding agents to check whether a repository already provides the helper they are about to reimplement, surface bloat, missing error handling and security findings after each edit, and block task completion until blocking issues are fixed.
      7
      MIT