documentation
How graidr works
Graidr scores your repository across three dimensions on every push — no API keys, no configuration, free forever.
Getting started
Run this inside any git repository. Graidr installs a GitHub Actions workflow that scores your code on every push.
This writes two files to .github/workflows/: the workflow definition and a self-contained scorer. No secrets required — graidr uses your repository's built-in GITHUB_TOKEN and GitHub Models.
Run npx graidr init
Installs the workflow into your repo. Commit and push the two new files.
Push any branch
The GitHub Action runs automatically. No manual trigger needed.
See your score
A comment appears on your PR. Your repo appears on the leaderboard.
Scoring system
Each dimension is scored 0–100 in two phases. The overall score is the average of all three dimensions.
Phase 1 — Deterministic
15 binary checks run via shell against your git tree. Each check is worth 10 points (max 50 per dimension). Results are objective and reproducible — no AI involved.
Phase 2 — Subjective
GPT-4o reviews a smart sample of your files and scores 5 subjective criteria per dimension (0–10 each, max 50). Only judges what it can actually see.
Dimensions
Structure
Deterministic · 50 pts
- TypeScript present+10
- Test files found+10
- Largest file under 300 lines+10
- Build script in package.json+10
- Lint script in package.json+10
Subjective · 50 pts
- –Naming clarity across files and functions
- –Single-purpose functions and components
- –Separation of concerns and folder structure
- –No obvious duplication or god files
- –Organised imports and consistent conventions
Safety
Deterministic · 50 pts
- .gitignore present+10
- .env listed in .gitignore+10
- No .env files committed+10
- No potential secrets detected+10
- No eval() usage+10
Subjective · 50 pts
- –Error handling on async calls and API routes
- –Input validation at system boundaries
- –No hardcoded URLs or credentials
- –Auth checks on protected routes
- –No obviously risky patterns (SQL injection surface, etc.)
Completeness
Deterministic · 50 pts
- README over 10 lines+10
- Lock file committed+10
- No mixed lock files+10
- Fewer than 5 console.log calls+10
- Fewer than 5 TODO/FIXME comments+10
Subjective · 50 pts
- –Loading and error states handled
- –Empty states handled gracefully
- –No leftover boilerplate or placeholder copy
- –README explains what the project does and how to run it
- –Feels like an intentional project, not an abandoned scaffold
Grade scale
S
90–100
Exemplary
A
80–89
Solid
B
70–79
Adequate
C
50–69
Weak
D
0–49
Poor
Grades are fixed thresholds, not relative rankings. An A genuinely means solid code — not “better than most repos on the leaderboard.”
Deep scan
By default graidr samples up to 8 files (60 lines each). A deep scan increases this to 12 files and 80 lines, giving GPT-4o more context for a more thorough assessment.
Trigger via commit message
git commit -m "your message [grade:deep]"
Trigger via environment variable
DEEP_SCAN=true
Deep scans are tagged as gpt-4o-deep in the leaderboard.
PR comments
On every pull request, graidr posts a comment with your scores, specific issues to fix, and what's already working well.
Graidr score — 72/100 · Grade B
| Dimension | Score |
|--------------|------:|
| Structure | 65 |
| Safety | 80 |
| Completeness | 70 |
Top issues
– app/page.tsx is 640 lines — split into components
– 3 fetch() calls with no try/catch
– TODO comments left in lib/api.ts
Doing well
– TypeScript used consistently
– .env correctly gitignored
FAQ
Will graidr fail my pipeline?
No. The scorer always exits with code 0. A low score will never block a merge.
Does it cost anything?
No. Graidr uses your GITHUB_TOKEN to access GitHub Models (GPT-4o). This is free for all GitHub users and requires no separate API key.
What languages does it support?
The deterministic checks target TypeScript/JavaScript projects (package.json, .ts/.tsx files). The subjective phase can evaluate any source code GPT-4o can read.
Is my code sent anywhere?
A sample of your files is sent to GitHub Models (Microsoft Azure) for scoring — the same infrastructure that powers GitHub Copilot. Only scores and metadata are stored in the graidr database.
Can I game the score?
The deterministic phase is fully verifiable — it checks what is actually committed. The subjective phase is based on sampled file content. Scores reflect real code quality.