build-quality-agent

English | 中文

Claude-powered git pre-push reviewer for indie OSS projects. Stops the bad commit before it costs you a Vercel build minute.

Built by Alex Ji — solo founder shipping VibeXForge and Orallexa. Born from this thought:

I just spent $131.92 in Vercel build minutes this month because I keep pushing commits with type errors and missing imports.

What it does

Before every git push, it runs Claude over the diff and decides:

• PASS — push proceeds
• BLOCK — push is aborted, you fix the issue locally

That's the whole pitch. No CI loop. No remote build that fails 6 minutes in. Catches the obvious stuff (type errors, removed imports, hardcoded secrets, reverted auth checks) before your laptop fan even spins up.

--build flag (v0.3+) — also run the actual build

--build runs the project's local build before review (auto-detects: npm/pnpm/bun/yarn run build for JS, python -m build, cargo check, go build). If the build fails, the build log is appended to the Claude prompt for a unified explanation, and the push is always BLOCKed.

build-quality-agent --build              # one-off
BUILD_AGENT_BUILD=1 git push              # default for this push

The 4-minute build cap is generous; most local builds for indie projects are 30-90s. Combined cost of --build + diff review: ~$0.0006 + ~30-60s of laptop time, vs ~$0.12/min × 6min = $0.72 saved per build that would have failed remotely.

Install

# 1. Clone
git clone https://github.com/alex-jb/build-quality-agent.git
cd build-quality-agent
pip install -e .

# 2. Set your Anthropic key (graceful no-op without it)
export ANTHROPIC_API_KEY=sk-ant-...

# 3. Wire into a target repo
cd ~/path/to/your/repo
bash ~/Desktop/build-quality-agent/scripts/install-hook.sh

That's it. Next git push will trigger a review.

Bypass

If the agent is wrong (it sometimes is — Claude reviews a diff, not a full repo, so context-free changes occasionally trip it):

BUILD_AGENT_SKIP=1 git push

This is the explicit, loud bypass. --no-verify also works but is silent. We prefer loud.

Usage examples

# Manual run on the most recent commit
python3 -m build_quality_agent --diff-range HEAD~1..HEAD

# Review without blocking (advisory mode)
python3 -m build_quality_agent --no-block

# Quiet unless something's wrong
python3 -m build_quality_agent --quiet

# Force a specific model
BUILD_AGENT_MODEL=claude-sonnet-4-6 python3 -m build_quality_agent

# Token + cost report (aggregates ~/.build-quality-agent/usage.jsonl)
python3 -m build_quality_agent --usage

Design choices

• Default Haiku 4.5, not Sonnet. Diff review is a fast cheap task — Haiku gets ~10s response and pennies per push. Sonnet only kicks in if you set BUILD_AGENT_MODEL.
• PASS by default on any internal failure. Network down, key missing, Claude flake — the agent prints a warning and lets the push through. Better unverified push than blocking real work.
• 50kB diff cap, junk paths excluded. Lockfiles (package-lock.json, bun.lock, etc.), generated types (next-env.d.ts), build output (.next/, dist/), and binary assets (images, fonts, MP4s) are stripped before review so the budget gets spent on real source.
• Vercel-aware prompt. The agent specifically looks for the patterns that crash Next.js / Vercel builds: missing default export on page.tsx / layout.tsx, client hooks without "use client", server-only imports leaking into client components, undefined symbols, hardcoded secrets.
• Reads git's pre-push stdin. When invoked as a hook, the agent parses the <local_ref> <local_oid> <remote_ref> <remote_oid> lines git passes in. That makes the review range exactly match what's being pushed — including new branches without upstream tracking.
• No build runner inside the hook. Running npm run build in pre-push would add 5-6 min to every push. Out of scope here. This agent reviews intent + obvious bugs; a separate CI build still catches everything.

Cost tracking

Every review writes a row to ~/.build-quality-agent/usage.jsonl. Run python3 -m build_quality_agent --usage to see total runs, pass/block split, token counts, and an estimated dollar cost (Haiku 4.5: $1/MTok in, $5/MTok out).

Roadmap

• v0.1 — Pre-push hook · Claude diff review · graceful degradation
• v0.2 — pip install -e . portability · git stdin parsing · junk-path filter · Vercel-aware prompt · pytest suite · --usage cost report
• v0.3 — Project-specific rule files (.build-quality-agent.toml)
• v0.4 — --build flag for projects that want the slow runtime build
• v0.5 — Auto-suggested fix (Claude proposes the smallest patch that would PASS)

MCP server (Claude Desktop / Cursor / Zed)

Review a diff inline from your AI assistant.

pip install 'build-quality-agent[mcp]'

Then in ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "build-quality": {
      "command": "build-quality-mcp",
      "env": { "ANTHROPIC_API_KEY": "..." }
    }
  }
}

Tools: review_diff(diff) · review_range(diff_range) · usage_summary()

License

MIT.

🧩 Part of the Solo Founder OS stack

A growing collection of MIT-licensed agents that share solo-founder-os as their base — Source/MetricSample contracts, HITL queue, AnthropicClient, notifiers, scheduler. Each agent is independently useful; together they cover the full solo-founder workflow.

Each agent's own row is omitted from its README. Install whichever solve real problems for you.