🧹 Slop Fixer

Slop Fixer is your automated design QA engineer. When you open a pull request, the bot spins up your React application, renders your configured routes across mobile and desktop viewports, and captures visual snapshots.

Before Slop Fixer	After Slop Fixer

Using Gemini 3.1 Pro's advanced spatial reasoning, it aggressively hunts for:

• AI-Generated Slop: Unnecessary sparkle emojis, unsolicited glowing borders, and generic default gradients.
• Inconsistent States: Missing focus/hover cues, disjointed shadows, and fragmented components.
• Classic Bugs: Overlapping elements, accessibility (WCAG) contrast failures, and broken CSS layouts.

The bot posts a detailed review right on your PR, attaching your screenshots annotated with exact bounding boxes around the problematic UI elements. It even generates a ready-to-use Fix Prompt that you can feed directly into Cursor, Windsurf, or Copilot to instantly resolve all the visual issues with zero manual effort!

Architecture

GitHub webhook → FastAPI server → clone + dev server
    → agent-browser screenshots → Gemini analysis → PR comment

Quick Start

Prerequisites

• Python 3.11+
• Node.js 18+ (for agent-browser and running target React apps)
• agent-browser: npm install -g agent-browser && agent-browser install
• A GitHub App (see Setup)
• A Gemini API key from Google AI Studio

Installation

# Clone the repo
git clone https://github.com/your-org/slop-fixer.git
cd slop-fixer

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -e ".[dev]"

# Copy and configure environment variables
cp .env.example .env
# Edit .env with your GitHub App credentials and Gemini API key

GitHub App Setup

1. Go to GitHub Settings → Developer settings → GitHub Apps → New GitHub App
2. Configure:
   • Webhook URL: Your server URL + /webhook (use smee.io for local dev)
   • Webhook secret: Generate a random string, put it in .env
   • Permissions:
     • Pull requests: Read & Write
     • Contents: Read
   • Events: Pull request
3. Generate a private key and save as private-key.pem in the project root
4. Note the App ID and add it to .env

Running Locally

# Start the webhook server
python server.py

# For local development, proxy GitHub webhooks via smee:
npx smee -u https://smee.io/YOUR_CHANNEL --target http://localhost:8080/webhook

Target Repo Configuration

Add a .slop-fixer.yml to any repo where the app is installed:

routes:
  - /
  - /login
  - /dashboard

viewports:
  - { width: 1440, height: 900, label: "Desktop" }
  - { width: 375, height: 812, label: "Mobile" }

dev_command: "npm run dev"
dev_port: 3000
startup_timeout: 60

See .slop-fixer.example.yml for a full example.

Running Tests

pytest tests/ -v

Tech Stack

Component	Technology
Server	Python / FastAPI
Browser automation	agent-browser
AI analysis	Gemini (multimodal)
Agent framework	Agentor
GitHub integration	PyJWT + httpx

License

MIT