repo-roast

A terminal CLI that reads a GitHub profile through the GitHub REST API — repos, language breakdown, stars, abandoned projects, and a sample of recent commit messages — then asks an LLM to roast the developer's coding habits.

It shows its receipts: every roast is preceded by an evidence table, and the model is instructed to only joke about facts that are actually in the data.

$ repo-roast roast torvalds --spice hot

Install

pip install -e .

Configure

cp .env.example .env

Then fill in:

Usage

repo-roast roast                        # roast yourself (the authenticated user)
repo-roast roast torvalds               # roast someone else
repo-roast roast torvalds --spice hot   # roast them harder
repo-roast roast torvalds --dry-run     # evidence + the exact prompt, no LLM call
repo-roast --help                       # the commands
repo-roast roast --help                 # the flags below

Breaking change in 0.2.0. The tool now takes a sub-command: repo-roast torvalds became repo-roast roast torvalds. This makes room for the commands that follow — compare, repo — without compare being ambiguous with a user who happens to be called compare. The old form prints the new one rather than a bare "No such command".

Flags

Flags belong to roast. --version belongs to the top level.

--dry-run is the quickest way to check the GitHub half on its own.

Scripting it

--format json prints one document to stdout and nothing else:

repo-roast roast torvalds -f json | jq '.stats.total_stars'
repo-roast roast torvalds -f json --dry-run | jq -r '.prompt.user'

Progress spinners and error messages go to stderr, so a pipe receives either a valid document or nothing at all — never half of one. Failures still exit non-zero, with the message on stderr where it belongs.

--format markdown prints the evidence table and the roast as Markdown, ready to paste into an issue or a README.

Provider

The default backend is Groq: free, no credit card, and OpenAI-compatible. repo-roast talks to it with the official openai SDK pointed at a custom base URL, so any OpenAI-compatible endpoint works — switching providers is just three environment variables.

Model strings change over time — if a call 404s, check the provider's current model list.

Running it with Docker

No local Python needed. Images are published to the GitHub Container Registry on every release, for linux/amd64 and linux/arm64:

docker run --rm -e GITHUB_TOKEN=ghp_... -e LLM_API_KEY=gsk_... \
  ghcr.io/amayyas/repo-roast roast torvalds --spice hot

Environment variables, not a mounted .env: simpler, and there is no file to accidentally bake into a container. LLM_BASE_URL and LLM_MODEL work the same way if you are pointing at a different provider.

Tags: latest tracks the newest release, vX.Y.Z pins a specific one — same versions as PyPI.

How it stays polite to the API

Repo metadata (languages, stars, descriptions, push dates) comes from the single repo listing that PyGithub already paginates. The only per-repo calls are for commit messages, and they are bounded on both axes: the --repos most recently pushed originals, up to 8 commits each.

Ethical use

repo-roast generates jokes about named, real people from their public GitHub activity. That comes with rules, not just a disclaimer:

• Roast the code and the habits — commit hygiene, abandoned repos, a suspicious TODO — never the person. No appearance, no identity, no protected characteristic. The system prompt enforces this on every call, and it's the first hard rule in roast.py.
• Don't use the output to harass, dogpile, or target someone who didn't ask for it. A roast run against a stranger without their knowledge is not the friendly-jab use case this tool is built for.
• This isn't only a prompt-level promise. SECURITY.md documents the structural defense that keeps a booby-trapped repo from turning the tool into a weapon against whoever is being roasted.

This project follows a Code of Conduct; the same spirit applies to how the tool itself gets used.

Support

Questions, bugs, or a roast that missed? See SUPPORT.md, or reach out directly at amayyas.aouadene@epitech.eu.

Found a security issue? See SECURITY.md instead of opening a public issue.

Want to contribute? See CONTRIBUTING.md. This project follows a Code of Conduct.

License

MIT © Amayyas Aouadene