Introducing clean-vibe — AI Clean Code scanner for GitHub repos

Lisa McCormack — Sun, 15 Mar 2026 02:04:05 +0000

Every codebase accumulates debt. Not the big architectural decisions — those get debated in PRs. The quiet stuff. The function that does three things. The variable named d. The catch block that swallows errors silently. The magic number buried in a conditional.
Martin's Clean Code has been the standard reference for over fifteen years. Most developers have read it — or at least know they should have. But reading the book and consistently applying its principles across a 50,000-line codebase are very different things.
clean-vibe closes that gap.

"Leave the code cleaner than you found it." — Robert C. Martin, Clean Code

How it works
Connect any GitHub repository — public or private — paste in your GitHub token and Anthropic API key, and clean-vibe fetches the full file tree. It estimates scan time per directory so you can run in batches rather than waiting for a monorepo to finish overnight.

Full repo traversal — fetches every scannable file via GitHub API, skips lockfiles, dist, maps, and generated code automatically
Two-pass AI analysis — Haiku for fast full-coverage scanning, Sonnet for deep blocker analysis with root cause and refactored examples
Session persistence — results saved to localStorage after every file, scan a directory today and another tomorrow, merge into one report
Markdown export — download the full report as a .md file at any point, paste it into a PR, a ticket, or a team retrospective

Three levels of severity
Not all violations are equal. A magic number in a config file is not the same as a catch block that silently swallows errors in a health data platform. clean-vibe sorts accordingly.
blocker — Must fix before merge. Dangerous, incorrect, or violates a hard rule. Will cause real bugs or silent failures in production.
warning — Should fix soon. Clear Clean Code violation that degrades maintainability, obscures intent, or makes the next developer's job harder.
suggestion — Worth considering. Naming or structural improvement. Small changes that compound over time into a significantly cleaner codebase.
What it actually finds
Here's a real example. A function that looks fine at a glance:
js// ✗ before
async function proc(d, t) {
// process the data
if (d && t === true) {
try {
await save(d);
} catch(e) {
console.error(e);
}
} else {
return -1;
}
}
ts// ✓ after
async function saveIfActive(
record: Record,
isActive: boolean
): Promise {
if (!isActive) return;
try {
await saveRecord(record);
} catch (error) {
showError('Could not save record.');
throw error;
}
}
The violations: cryptic parameter names (d, t), a flag argument, a silent catch, an error code return, and a comment describing what the code already says. Five violations in eight lines — none of them obvious without a systematic review.
The two-pass model
Speed matters when you're scanning hundreds of files. clean-vibe uses Claude Haiku for the first pass — fast, cheap, covering every file. The cost for a 200-file repo is roughly $0.15.
After the Haiku pass, any file with blocker-level violations gets a second pass with Claude Sonnet. Sonnet does what Haiku can't: root cause analysis, code smell categorization from Martin's taxonomy, and a concrete refactored example showing the correct approach. This is where the report goes from a list of complaints to an actionable improvement plan.
Zero dependencies. Zero build step.
clean-vibe is a single index.html file. No npm install, no webpack, no server. Open it locally or serve it from any static host. Your API keys stay in your browser — they never pass through any server except Anthropic's and GitHub's directly.
bashgit clone https://github.com/Triple-Moon-Goddess/clean-vibe.git
open clean-vibe/index.html
Free for non-commercial use
If you're using clean-vibe for personal projects, learning, or open source work — it's free, forever, no account required. Bring your own Anthropic API key and GitHub token.
Commercial use requires a license. Three tiers: Individual ($100/year), Team up to 10 developers ($500/year), and Organization unlimited seats ($1,500/year).

Try it on your codebase → triple-moon-goddess.github.io/clean-vibe
GitHub → Triple-Moon-Goddess/clean-vibe

Forem: Lisa McCormack

Introducing clean-vibe — AI Clean Code scanner for GitHub repos