Quick Start Guide

This guide will help you get started with ai-slop-gate in minutes.

Installation

1. Clone the repository:

git clone https://github.com/SergUdo/ai-slop-gate.git
cd ai-slop-gate

2. Set up Python environment:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .

3. Initialize configuration:

python -m ai_slop_gate.cli init

This creates .ai-slop-gate.yml with default settings.

Environment Variables

Create a .env file in the project root:

# Required for GitHub PR commenting
GITHUB_TOKEN=your_github_personal_access_token

# Provider Keys (add based on your configuration)
GEMINI_API_KEY=your_google_gemini_api_key
SLOPE_GATE_GROQ=your_groq_api_key
GITLAB_TOKEN=your_gitlab_token  # For GitLab integration

Your First Analysis

Static Analysis (Fast, No API Keys Required)

python -m ai_slop_gate.cli run --provider static --policy policy.yml

This performs:

  • Secret detection (hardcoded API keys, passwords)

  • Dangerous function detection (eval, exec)

  • Dockerfile security checks

  • PII detection

  • TODO/FIXME tracking

  • Supply chain validation

LLM Analysis (Requires API Key)

python -m ai_slop_gate.cli run --provider gemini --llm-local --policy policy.yml

This performs AI-powered analysis:

  • AI slop detection (repetitive, low-quality code)

  • Hallucination detection

  • Code quality assessment

  • Architecture anti-patterns

  • Automatically caches responses (saves ~67% of tokens!)

Compliance Check

python -m ai_slop_gate.cli run --compliance --policy policy.yml

This checks:

  • GDPR/DSGVO data residency

  • License compliance (GPL, AGPL detection)

  • Supply chain security

  • AI hallucination protection

Using Docker

Pull the image:

docker pull ghcr.io/sergudo/ai-slop-gate:latest

Run analysis:

docker run --rm -v $(pwd):/src \
  ghcr.io/sergudo/ai-slop-gate:latest \
  run --provider static --policy /src/policy.yml --path /src

See 🐳 Docker Guide for ai-slop-gate for complete Docker documentation.

Test on Demo Repository

Try ai-slop-gate on our demo repository with intentional violations:

git clone https://github.com/SergUdo/slop_test
python -m ai_slop_gate.cli run --provider gemini --llm-local --path slop_test

This repository contains:

  • Hardcoded secrets

  • AI-generated slop

  • License violations

  • Security issues

Live Example: Check this PR where ai-slop-gate automatically analyzed violations.

Supported Providers

Provider

Type

Cache

Description

static

Static Analysis

❌ No

Fast static analysis (secrets, eval, Dockerfile, PII)

gemini

LLM

✅ Yes

Google Gemini (local or GitHub PR)

groq

LLM

✅ Yes

Groq (Llama 3.3)

ollama

LLM

✅ Yes

Local Ollama models (100% private)

compliance

Compliance

❌ No

GDPR, EU residency, license checks

Common Use Cases

1. Local Development (Before Commit)

# Quick check
python -m ai_slop_gate.cli run --provider static

# Deep analysis (with cache)
python -m ai_slop_gate.cli run --provider static gemini --llm-local

2. Pull Request Analysis

export GITHUB_TOKEN="ghp-xxxxxxxxxxxx"
export GEMINI_API_KEY="your-key"

python -m ai_slop_gate.cli run \
  --provider gemini \
  --github-repo owner/repo \
  --pr-id 123

3. CI/CD Pipeline

# GitHub Actions example
- name: AI Slop Gate
  run: |
    docker run --rm -v $(pwd):/src \
      -e GEMINI_API_KEY=${{ secrets.GEMINI_API_KEY }} \
      ghcr.io/sergudo/ai-slop-gate:latest \
      run --provider gemini --llm-local --path /src

See CI/CD Integrations Guide for complete CI/CD setup.

4. Local LLM (100% Private)

# Start Ollama
docker-compose up -d

# Run analysis (code never leaves your machine)
python -m ai_slop_gate.cli run --provider ollama --llm-local

Next Steps

Troubleshooting

“Provider skipped: insufficient context”

Missing API key. Set environment variable:

export GEMINI_API_KEY="your-key"

“Cache not working”

Check verbose output:

python -m ai_slop_gate.cli run --provider gemini --llm-local --verbose

See cache directory:

ls -la .ai-slop-cache/

“Permission denied”

Fix permissions:

chmod -R u+rw .ai-slop-cache/

For more help, see: