![\"Judges](\"docs/terminal-output.svg\")
\n\n \n
http://localhost:4567/webhook via ngrok http 4567 and configure the GitHub App webhook URL accordingly.\n\n### Use in GitHub Actions\n\nAdd Judges to your CI pipeline with zero configuration:\n\n```yaml\n# .github/workflows/judges.yml\nname: Judges Code Review\non: [pull_request]\n\njobs:\n judges:\n runs-on: ubuntu-latest\n permissions:\n contents: read\n security-events: write # only if using upload-sarif\n steps:\n - uses: actions/checkout@v4\n - uses: KevinRabun/judges@main\n with:\n path: src/api.ts # file or directory\n format: text # text | json | sarif | markdown\n upload-sarif: true # upload to GitHub Code Scanning\n fail-on-findings: true # fail CI on critical/high findings\n```\n\n**Outputs** available for downstream steps: `verdict`, `score`, `findings`, `critical`, `high`, `sarif-file`.\n\n### Use with Docker (no Node.js required)\n\n```bash\n# Build the image\ndocker build -t judges .\n\n# Evaluate a local file\ndocker run --rm -v $(pwd):/code judges eval --file /code/app.ts\n\n# Pipe from stdin\ncat api.py | docker run --rm -i judges eval --language python\n\n# List judges\ndocker run --rm judges list\n```\n\n### Or use as an MCP server\n\n### 1. Install and Build\n\n```bash\ngit clone https://github.com/KevinRabun/judges.git\ncd judges\nnpm install\nnpm run build\n```\n\n### 2. Try the Demo\n\nRun the included demo to see all 45 judges evaluate a purposely flawed API server:\n\n```bash\nnpm run demo\n```\n\nThis evaluates [`examples/sample-vulnerable-api.ts`](examples/sample-vulnerable-api.ts) — a file intentionally packed with security holes, performance anti-patterns, and code quality issues — and prints a full verdict with per-judge scores and findings.\n\nThe demo now also includes an **App Builder Workflow (3-step)** section. In a single run, you get both tribunal output and workflow output:\n- Release decision (`Ship now` / `Ship with caution` / `Do not ship`)\n- Plain-language summaries of top risks\n- Prioritized remediation tasks and AI-fixable `P0/P1` items\n\n**Sample workflow output (truncated):**\n\n```text\n╔══════════════════════════════════════════════════════════════╗\n║ App Builder Workflow Demo (3-Step) ║\n╚══════════════════════════════════════════════════════════════╝\n\n Decision : Do not ship\n Verdict : FAIL (47/100)\n Risk Counts : Critical 24 | High 27 | Medium 55\n\n Step 2 — Plain-Language Findings:\n - [CRITICAL] DATA-001: Hardcoded password detected\n What: ...\n Why : ...\n Next: ...\n\n Step 3 — Prioritized Tasks:\n - P0 | DEVELOPER | Effort L | DATA-001\n Task: ...\n Done: ...\n\n AI-Fixable Now (P0/P1):\n - P0 DATA-001: ...\n```\n\n**Sample tribunal output (truncated):**\n\n```\n╔══════════════════════════════════════════════════════════════╗\n║ Judges Panel — Full Tribunal Demo ║\n╚══════════════════════════════════════════════════════════════╝\n\n Overall Verdict : FAIL\n Overall Score : 43/100\n Critical Issues : 15\n High Issues : 17\n Total Findings : 83\n Judges Run : 33\n\n Per-Judge Breakdown:\n ────────────────────────────────────────────────────────────────\n ❌ Judge Data Security 0/100 7 finding(s)\n ❌ Judge Cybersecurity 0/100 7 finding(s)\n ❌ Judge Cost Effectiveness 52/100 5 finding(s)\n ⚠️ Judge Scalability 65/100 4 finding(s)\n ❌ Judge Cloud Readiness 61/100 4 finding(s)\n ❌ Judge Software Practices 45/100 6 finding(s)\n ❌ Judge Accessibility 0/100 8 finding(s)\n ❌ Judge API Design 0/100 9 finding(s)\n ❌ Judge Reliability 54/100 3 finding(s)\n ❌ Judge Observability 45/100 5 finding(s)\n ❌ Judge Performance 27/100 5 finding(s)\n ❌ Judge Compliance 0/100 4 finding(s)\n ⚠️ Judge Testing 90/100 1 finding(s)\n ⚠️ Judge Documentation 70/100 4 finding(s)\n ⚠️ Judge Internationalization 65/100 4 finding(s)\n ⚠️ Judge Dependency Health 90/100 1 finding(s)\n ❌ Judge Concurrency 44/100 4 finding(s)\n ❌ Judge Ethics & Bias 65/100 2 finding(s)\n ❌ Judge Maintainability 52/100 4 finding(s)\n ❌ Judge Error Handling 27/100 3 finding(s)\n ❌ Judge Authentication 0/100 4 finding(s)\n ❌ Judge Database 0/100 5 finding(s)\n ❌ Judge Caching 62/100 3 finding(s)\n ❌ Judge Configuration Mgmt 0/100 3 finding(s)\n ⚠️ Judge Backwards Compat 80/100 2 finding(s)\n ⚠️ Judge Portability 72/100 2 finding(s)\n ❌ Judge UX 52/100 4 finding(s)\n ❌ Judge Logging Privacy 0/100 4 finding(s)\n ❌ Judge Rate Limiting 27/100 4 finding(s)\n ⚠️ Judge CI/CD 80/100 2 finding(s)\n```\n\n### 3. Run the Tests\n\n```bash\nnpm test\n```\n\nRuns automated tests covering all judges, AST parsers, markdown formatters, and edge cases.\n\n### 4. Connect to Your Editor\n\n#### VS Code (recommended — zero config)\n\nInstall the **[Judges Panel](https://marketplace.visualstudio.com/items?itemName=kevinrabun.judges-panel)** extension from the Marketplace. It provides:\n\n- **Inline diagnostics & quick-fixes** on every file save\n- **`@judges` chat participant** — type `@judges` in Copilot Chat, or just ask for a \"judges panel review\" and Copilot routes automatically\n- **Auto-configured MCP server** — all 45 expert-persona prompts available to Copilot with zero setup\n\n```bash\ncode --install-extension kevinrabun.judges-panel\n```\n\n#### VS Code — manual MCP config\n\nIf you prefer explicit workspace config (or want teammates without the extension to benefit), create `.vscode/mcp.json`:\n\n```json\n{\n \"servers\": {\n \"judges\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@kevinrabun/judges\"]\n }\n }\n}\n```\n\n#### Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"judges\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@kevinrabun/judges\"]\n }\n }\n}\n```\n\n#### Cursor / other MCP clients\n\nUse the same `npx` command for any MCP-compatible client:\n\n```json\n{\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@kevinrabun/judges\"]\n}\n```\n\n### 5. Use Judges in GitHub Copilot PR Reviews\n\nYes — users can include Judges as part of GitHub-based review workflows, with one important caveat:\n\n- The hosted `copilot-pull-request-reviewer` on GitHub does not currently let you directly attach arbitrary local MCP servers the same way VS Code does.\n- The practical pattern is to run Judges in CI on each PR, publish a report/check, and have Copilot + human reviewers use that output during review.\n\n#### Option A (recommended): PR workflow check + report artifact\n\nCreate `.github/workflows/judges-pr-review.yml`:\n\n```yaml\nname: Judges PR Review\n\non:\n pull_request:\n types: [opened, synchronize, reopened]\n\njobs:\n judges:\n runs-on: ubuntu-latest\n permissions:\n contents: read\n pull-requests: write\n\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n\n - name: Setup Node\n uses: actions/setup-node@v4\n with:\n node-version: 20\n cache: npm\n\n - name: Install\n run: npm ci\n\n - name: Generate Judges report\n run: |\n npx tsx -e \"import { generateRepoReportFromLocalPath } from './src/reports/public-repo-report.ts';\n const result = generateRepoReportFromLocalPath({\n repoPath: process.cwd(),\n outputPath: 'judges-pr-report.md',\n maxFiles: 600,\n maxFindingsInReport: 150,\n });\n console.log('Overall:', result.overallVerdict, result.averageScore);\"\n\n - name: Upload report artifact\n uses: actions/upload-artifact@v4\n with:\n name: judges-pr-report\n path: judges-pr-report.md\n```\n\nThis gives every PR a reproducible Judges output your team (and Copilot) can reference.\n\n#### Option B: Add Copilot custom instructions in-repo\n\nAdd `.github/instructions/judges.instructions.md` with guidance such as:\n\n```markdown\nWhen reviewing pull requests:\n1. Read the latest Judges report artifact/check output first.\n2. Prioritize CRITICAL and HIGH findings in remediation guidance.\n3. If findings conflict, defer to security/compliance-related Judges.\n4. Include rule IDs (e.g., DATA-001, CYBER-004) in suggested fixes.\n```\n\nThis helps keep Copilot feedback aligned with Judges findings.\n\n---\n\n## CLI Reference\n\nAll commands support `--help` for usage details.\n\n### `judges eval`\n\nEvaluate a file with all 45 judges or a single judge.\n\n| Flag | Description |\n|------|-------------|\n| `--file