rules-clinic

Paste a GitHub repo. See every AI agent config file it ships — CLAUDE.md, AGENTS.md, .cursorrules, .windsurfrules, GEMINI.md, .github/copilot-instructions.md, .clinerules, ROO.md, .codeium/instructions.md, .aider.conf.yml, CONVENTIONS.md, .continue/config.json, and any .cursor/rules/*.mdc. Diff them against each other. See the conflicts, duplications, drift, missing imports and bloat. Get a unified AGENTS.md merge proposal.

Live: https://holyai.me/rules-clinic/

Why

By May 2026, AI coding agents read different files. Claude Code reads CLAUDE.md. Codex CLI, Cursor, Copilot, Windsurf, Aider and many others read AGENTS.md (stewarded by the Agentic AI Foundation under the Linux Foundation, adopted by 60,000+ open-source projects). Gemini CLI reads GEMINI.md. Cline reads .clinerules. Cursor and Windsurf also still read their legacy .cursorrules / .windsurfrules files.

Most non-trivial teams now ship 3–7 of these files. They drift. The agents quietly read different things and produce inconsistent output. rules-clinic is the audit tool for that mess.

Per Anthropic's May 2026 docs, Claude Code does not read AGENTS.md directly — the recommended pattern is to put @AGENTS.md at the top of CLAUDE.md, or to symlink the two. rules-clinic flags this when both files exist but the import is missing.

Stack

• Node.js 20+, Express 4
• better-sqlite3 (WAL)
• node-cron (leaderboard refresh every 6 hours)
• helmet, compression
• Vanilla JS SPA, dark theme, single HTML file
• highlight.js + DOMPurify from CDN for the file viewer

Real data sources (no mocks, no seeds, no Math.random)

| Source | URL | Frequency |
|--------|-----|-----------|
| GitHub REST: repo metadata | https://api.github.com/repos/{owner}/{repo} | On every scan + every 6 h for the curated leaderboard |
| GitHub REST: file contents | https://api.github.com/repos/{owner}/{repo}/contents/{path}?ref={branch} | Per scan, one call per candidate path. 404 is expected and silently skipped. |
| GitHub REST: directory listing | https://api.github.com/repos/{owner}/{repo}/contents/.cursor/rules?ref={branch} | Per scan, when applicable |

No LLM calls. No third-party APIs. The only seed file is seed/leaderboard.json — and it contains only the names of 25 well-known public repos. Every stat about those repos (file count, conflicts, chaos score) comes from live GitHub fetches.

Auth

There is none. Every endpoint, including the scan submission endpoint, is public.

Running

npm install
node server.js

Open http://127.0.0.1:4864/rules-clinic/

Environment

| Var | Default | Notes |
|----------------|---------|-------|
| PORT | 4864 | HTTP port |
| NODE_ENV | (unset) | Set to production in deploy |
| GITHUB_TOKEN | (unset) | Optional. With a token, GitHub allows 5000 requests/hour (vs 60 unauthenticated). Use any classic or fine-grained PAT with public-repo read scope. The product works fine without it, just rate-limits faster. |

Endpoints

All mounted under /rules-clinic:

| Method | Path | Description |
|--------|-------------------------------|-------------|
| GET | /health | {ok, db, leaderboard_age_sec} |
| POST | /api/scans | Body: {owner, repo, branch?}; runs a scan, returns summary |
| GET | /api/scans/:share_code | Full scan detail (files, findings, merge proposal) |
| GET | /api/scans/recent | Last 20 user-submitted scans |
| GET | /api/leaderboard | The 25 curated repos with their latest scan summary |
| GET | /api/stats | Aggregate stats over user-submitted scans |
| GET | /s/:share_code | Server-rendered HTML with OpenGraph meta (Twitter/Slack/HN unfurls) |

The 9 analysis rules

| Rule | Severity | What it detects |
|----------------------------|----------|-----------------|
| package_manager_conflict | high | Two files mention different package managers (npm / yarn / pnpm / bun) |
| test_command_conflict | high | Two files specify different "how to test" commands |
| lint_command_conflict | med | Two files specify different lint/format tools |
| language_version_drift | high | Two files mention different language versions (Python 3.10 vs 3.12, Node 18 vs 20, ...) |
| style_drift | med | Contradictory tabs-vs-spaces or quote-style rules |
| commit_style_drift | med | Contradictory commit-message style guidance |
| import_missing | med | Both CLAUDE.md and AGENTS.md exist, but CLAUDE.md does not @AGENTS.md import |
| duplicate_paragraph | low | The same ≥200-char paragraph appears in 2+ files |
| bloat | low | A single config file exceeds 8,000 estimated tokens |

Chaos score formula

chaos = clamp(high*15 + med*6 + low*2 + file_count*1.5, 0, 100)

verdict:
< 15 Low drift
< 40 Watch out
< 70 High chaos
≥ 70 Critical drift
```

License

MIT.