gitwtfhub

wtf is specjudge?

joaquinruiz/specjudge — explained in plain English

Analysis updated 2026-05-18

2PythonAudience · developerComplexity · 2/5LicenseSetup · easy

TL;DR

A local-first CLI that reads your project specs and recommends the best-fitting AI model to implement them, without your specs ever leaving your machine.

Mindmap

mindmap
  root((repo))
    What it does
      Judges spec complexity
      Ranks models by fit
      Recommends before coding
    Tech stack
      Python CLI
      Ollama local judge
      YAML model catalog
    Use cases
      Pick right-sized model
      Compare fit not just price
      Contribute price updates
    Audience
      Spec-driven developers
      Cost-conscious teams

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Why would anyone build with this?

REASON 1

Check which AI model best fits a project's specs before spending tokens on implementation.

REASON 2

Compare AI model options by capability fit rather than raw power or price alone.

REASON 3

Add or update model prices in the shared data file with a simple pull request, no coding needed.

What's in the stack?

PythonOllamauvYAML

How it stacks up

joaquinruiz/specjudge0-bingwu-0/live-interpreter010zx00x1/faresnipe
Stars222
LanguagePythonPythonPython
Setup difficultyeasymoderateeasy
Complexity2/52/52/5
Audiencedevelopergeneralgeneral

Figures from each repo's GitHub metadata at analysis time.

How do you spin it up?

Difficulty · easy Time to first run · 5min

Requires Python 3.11+, uv, and Ollama with at least one local model pulled.

Use freely for any purpose, including commercial use, as long as you keep the copyright notice.

Wtf does this do

SpecJudge is a command line tool that reads the specification documents from a Spec Driven Development project and recommends which AI model actually fits the job, before you spend any tokens implementing it. The idea is to make that model choice at the moment it is cheapest to get wrong: right after you have written specs, but before any code exists. Running specjudge against a project folder produces a ranked comparison table showing each candidate model's fit rating, its price, and the date that price was recorded. Every model is judged not by raw power but by how well it fits the actual demands of your project: a rating of good means the model is capable enough and is the sweet spot, overkill means you are paying for capability the project will never use, fair means it falls somewhat short, and poor means it clearly is not capable enough. Price is shown for every model, but it only breaks ties between models that fit equally well. It never wins over a better fitting but pricier option, since choosing something incapable is treated as the most expensive mistake of all. A local, small model running through Ollama acts as the judge that estimates how demanding the project is across several dimensions. That estimate is then compared against a community maintained catalog of models and their declared capabilities using plain, readable rules, so every recommendation comes with a reason instead of being a black box. Because the judge model runs entirely on your own machine, your specs and business logic never leave it, and the optional browser report is a self contained file that loads nothing from the network. The tool is installed with a package manager called uv, requires at least one local model pulled through Ollama, and is used with a single command against any project path. It also reports clearly when it does not have enough information to make a confident recommendation, rather than guessing. The project explicitly invites contributions that need no coding at all, since the list of models and their prices is kept in a separate, human readable data file that anyone can update with a pull request.

Yoink these prompts

Prompt 1
Help me install SpecJudge with uv and run it against my Spec-Driven Development project.
Prompt 2
Explain what SpecJudge's good, overkill, fair, and poor ratings mean for choosing a model.
Prompt 3
Show me how to add a new model entry to SpecJudge's models.yaml catalog file.
Prompt 4
Walk me through why SpecJudge picked the model it recommended for my project.

Frequently asked questions

wtf is specjudge?

A local-first CLI that reads your project specs and recommends the best-fitting AI model to implement them, without your specs ever leaving your machine.

What language is specjudge written in?

Mainly Python. The stack also includes Python, Ollama, uv.

What license does specjudge use?

Use freely for any purpose, including commercial use, as long as you keep the copyright notice.

How hard is specjudge to set up?

Setup difficulty is rated easy, with roughly 5min to a first successful run.

Who is specjudge for?

Mainly developer.

View the repo → Decode another repo

This repo across BitVibe Labs

Don't trust strangers blindly. Verify against the repo.