roast-my-codebase 🔥

Get roasted. Get better. Ship faster.

A zero-config CLI that scans your codebase and delivers brutally honest (but funny) feedback. Every roast is backed by a real finding — not random noise.

npx roast-my-codebase

What it looks like

╔═════════════════════════════╗
║    Roast My Codebase    🔥  ║
╚═════════════════════════════╝

  Project: my-app

  Health Score: 42/100  F  Chaotic

  [████████████░░░░░░░░░░░░░░░░░░]

  Some findings require immediate attention.

  Project Summary
  ────────────────────────────────────────
  Files Scanned      138
  Total Files        412
  Lines of Code      28,904
  Dependencies       54
  Dev Dependencies   21

  Findings
  ────────────────────────────────────────
  ● 3 critical
  ● 18 warnings
  ● 11 info

  ✗ AuthService in src/auth/auth.service.ts has cyclomatic complexity of 34
     Gru's plan: write simple function → add one more condition → this.
  ✗ .env is tracked in git — secrets may be exposed
     Little Bobby Tables visited your repo. He felt at home.
  ⚠ src/auth/auth.service.ts is 1,847 lines
     Nobody: ... This file: *adds 200 more lines*
  ⚠ "lodash" appears unused — paying rent for no reason
     node_modules: the folder that makes SSD manufacturers nervous.
  ⚠ src/utils/helpers.ts has cyclomatic complexity of 22
     I've seen smaller decision trees at the DMV.

  The findings have formed a coalition.

  ────────────────────────────────────────

  Verdict

  Functional code with security issues is a solved problem waiting to be exploited.

  ────────────────────────────────────────

  Share your roast → https://x.com/intent/tweet?text=My%20codebase%20just%20got%20roasted...

  roast-my-codebase · github.com/rahuldk1105/roast-my-codebase

Add it to your CI in 30 seconds

Every PR gets a roast comment automatically. Teams screenshot them. They spread.

Step 1 — create .github/workflows/roast.yml in your repo:

name: Roast My Codebase

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  pull-requests: write

jobs:
  roast:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: rahuldk1105/roast-my-codebase@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

That's it. No secrets to configure. GITHUB_TOKEN is provided automatically by GitHub.

What the PR comment looks like:

## 🔥 Roast My Codebase — Health: 42/100 🔴

[████████████░░░░░░░░░░░░░░░░░░] 42/100

| Metric | Value |
|--------|-------|
| Files  | 138   |
| Lines  | 28k   |
| Deps   | 54    |

🔴 3 critical  ⚠️ 18 warnings  ℹ️ 11 info

- 🔴 `src/auth/auth.service.ts` — cyclomatic complexity of 34
- 🔴 `.env` is tracked in git — secrets may be exposed
- ⚠️ `src/auth/auth.service.ts` is 1,847 lines
- ⚠️ "lodash" appears unused — paying rent for no reason

> 🔥 **src/auth/auth.service.ts**: Nobody: ... This file: *adds 200 more lines*
> 🔥 **.env**: Little Bobby Tables visited your repo. He felt at home.
> 🔥 **codebase**: The findings have formed a coalition.

*Functional code with security issues is a solved problem waiting to be exploited.*

Generated by roast-my-codebase

Optional: fail PRs below a score threshold

- uses: rahuldk1105/roast-my-codebase@v1
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    fail-below: "60"

Optional: AI-powered roasts via Claude

- uses: rahuldk1105/roast-my-codebase@v1
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    ai-roasts: "true"
    anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}

Installation

# Run without installing
npx roast-my-codebase

# Install globally
npm install -g roast-my-codebase
roast-my-codebase

# Scan a specific path
roast-my-codebase ./path/to/project

What gets analyzed

| Check | What it finds | |-------|--------------| | File Size | Files over 500 / 1000 / 2000 lines | | Complexity | Functions with cyclomatic complexity 15+ | | TODOs | TODO, FIXME, HACK, XXX comments | | Dependencies | Unused or excessive packages | | Circular Deps | Import cycles between modules | | Duplicates | Copy-pasted code blocks | | Dead Exports | Exports that are never imported | | Type Safety | any, @ts-ignore, type bypasses | | Security | Secrets in git, hardcoded credentials, eval usage | | Test Coverage | Source files with no corresponding tests | | Git Insights | High-churn files, large PRs, stale branches | | Structure | Deep nesting, utils explosion, bloated folders |

Supported languages

Full support: JavaScript · TypeScript · Python · Go · Rust · Java · C# · Ruby · PHP · Swift · Kotlin

Framework checks: Next.js · React · Vue 3 · Angular · Svelte · Express · FastAPI

Language detection is automatic — no config needed.

Health Score

Starts at 100. Deductions for real issues:

| Issue | Points | |-------|--------| | Extreme file (2000+ lines) | −5 | | Circular dependency | −5 | | Critical security issue | −10 | | Large file (1000+ lines) | −3 | | Unused dependency | −2 | | Complex function | −2 | | TODO/FIXME (each) | −0.25 |

Grades: 90–100 Excellent · 80–89 Good · 70–79 Fair · 60–69 Risky · 0–59 Chaotic

All options

# Output formats
roast-my-codebase --json              # Machine-readable JSON
roast-my-codebase --markdown          # Markdown to stdout
roast-my-codebase --markdown-file     # Save to .roast-report.md
roast-my-codebase --html-file         # Save to .roast-report.html
roast-my-codebase --ascii             # Big ASCII art grade (screenshot-worthy)
roast-my-codebase --badge             # Generate .roast-badge.svg for your README

# CI/CD
roast-my-codebase --json --threshold 80     # Exit code 1 if score < 80
roast-my-codebase --pr-comment              # Post GitHub PR comment
roast-my-codebase --init-ci                 # Drop a CI workflow into your repo

# AI roasts
roast-my-codebase --ai-roasts              # Claude-powered contextual roasts

# Interactive
roast-my-codebase --fix                    # Show fix suggestions
roast-my-codebase --interactive            # Walk through and apply fixes
roast-my-codebase --interactive --dry-run  # Preview fixes without applying

# Scanning
roast-my-codebase --incremental            # Only changed files since last commit
roast-my-codebase --since main             # Only files changed since branching from main
roast-my-codebase --watch                  # Re-run on file changes

# History and comparison
roast-my-codebase --track                  # Save score snapshot
roast-my-codebase --history                # Show last 30 days
roast-my-codebase --history 7              # Show last 7 days
roast-my-codebase --compare main           # Diff against a branch

Configuration

Create .roastrc.json in your project root:

{
  "thresholds": {
    "largeFile": 1000,
    "extremeFile": 3000
  },
  "scanners": {
    "disabled": ["test-coverage"]
  },
  "ignore": [
    "**/vendor/**",
    "**/generated/**"
  ],
  "deductions": {
    "secret": -20
  }
}

See CUSTOMIZATION.md for the full config reference and plugin development guide.

AI-Powered Roasts

export ANTHROPIC_API_KEY=your_key_here
npx roast-my-codebase --ai-roasts

Uses Claude to generate context-aware roasts specific to your actual code. Cached for 7 days. Typical cost: $0.01–0.05 per scan.

Generic roast: "This file contains several geological layers."

AI roast: "This 1,847-line auth service handles authentication, authorization, password reset, email verification, 2FA, and probably your taxes. Pick a lane."

VS Code Extension

Search "Roast My Codebase" in the VS Code marketplace for inline diagnostics, a live health score in the status bar, and findings in the Problems panel.

Design principles

1. Real value — humor is the presentation layer; analysis is the product
2. Zero config — works on any codebase with no setup
3. Completely offline — no telemetry, no data collection, no cloud
4. Fast — under 3 seconds on repos with fewer than 1000 files

Contributing

PRs welcome. Each scanner is independent and easy to add to.

src/
├── cli/          # Command setup
├── scanners/     # Modular analysis passes
├── scoring/      # Health score calculation
├── roasts/       # Roast message pools
├── report/       # Terminal + HTML rendering
├── types/        # Shared interfaces
└── utils/        # Shared helpers

License

MIT