site-improver

Diagnose and patch frontend issues — automatically.

site-improver is a CLI that runs against any Node-based web project (Next.js, Vite, CRA, Astro). It boots your dev server, loads pages in headless Chromium across multiple viewports, measures Lighthouse + axe-core + console errors, asks Claude to diagnose what's wrong, and proposes patches with a unified-diff preview that you approve one Y/N at a time.

The product promise: you only press Y/N. Everything else is automatic.

Install / use

Run without installing:

npx site-improver@latest

Or install globally:

npm install -g site-improver
site-improver

site-improver operates on the current directory by default. Pass a path to point at another project:

site-improver ./apps/web

Requirements

• Node 20+
• claude CLI logged in — site-improver uses your local Claude Code credentials. Install Claude Code, then run claude /login. (Alternatively set ANTHROPIC_API_KEY in your environment.)
• A Node project with a package.json that has a dev script.

What it does

1. Detect the framework (Next.js, Vite, CRA, Astro), package manager, styling stack, git state.
2. Boot your project's dev server on a free port.
3. Observe each page across 5 viewports (iPhone SE / iPhone 14 Pro / iPad / desktop 1280 / desktop 1920) — full-page screenshot, axe-core a11y violations, console errors, network errors. With --lighthouse, also runs Lighthouse for mobile + desktop.
4. Diagnose by sending the compressed observation summary to Claude. The diagnoser is read-only: Read/Glob/Grep only. Returns a list of Issues — severity, category, suggested fix, candidate files.
5. Patch one issue at a time. Every Edit/Write/MultiEdit Claude proposes is intercepted and shown to you as a unified diff. You press y (apply), n (skip), a (apply all remaining), or q (quit).
6. Verify by re-measuring just the affected (page, viewport) pairs and comparing before/after metrics.

What it doesn't do (yet)

• Backend code analysis
• E2E test generation
• Adding or removing npm dependencies
• Multi-route auto-discovery (pass --page per route to test)
• Login flows for sites that require authentication
• Visual regression across runs (only within-run before/after)

Flags

| flag | default | description | |---|---|---| | [path] | cwd | project to operate on | | -p, --page <path...> | [/] | pages to test (repeatable) | | -f, --focus <ui\|perf\|both> | both | category bias | | --lighthouse | off | opt in to Lighthouse measurements (slower, better perf signal) | | --auto | off | skip per-edit confirmation (requires --yes) | | --yes | — | safety acknowledgement, required with --auto | | --dry-run | off | run everything but never write files; diffs are still shown | | --force | off | proceed even if git working tree is dirty | | --no-color | — | disable ANSI colors | | -V, --version | — | print version | | -h, --help | — | print help |

Examples

Interactive review on the current directory:

site-improver

A specific path, with Lighthouse, focused on performance:

site-improver ./apps/web --lighthouse --focus perf

Non-interactive — apply every proposed edit:

site-improver --auto --yes --lighthouse

Preview only — never modify files:

site-improver --dry-run

Multiple pages:

site-improver --page / --page /about --page /pricing

Cost

site-improver runs Claude through your local claude CLI. A typical run on a small project costs about $0.50 – $2.00 (one diagnose + 1–3 patches). The summary screen prints the exact total.

Privacy & safety

• No telemetry. site-improver doesn't phone home.
• Source files are read by Claude only via its Read/Glob/Grep tools during diagnosis and patching.
• Sensitive paths blocked at the hook level — .env*, **/secrets/**, **/.aws/**, **/.ssh/**, **/.gnupg/**, id_rsa, *.pem, .netrc, credentials.*, lockfiles, and node_modules/ cannot be read or written, even if Claude proposes it.
• Every edit is gated. In interactive mode, you press y/n on each Edit. In --auto mode you opt in via --yes. In --dry-run no file is ever written.
• Git is your safety net. site-improver refuses to run on a dirty working tree unless you pass --force. To revert any run: git restore . (or git checkout . for older git).

Troubleshooting

✗ No Claude credential found. — Install the Claude Code CLI and run claude /login, or set ANTHROPIC_API_KEY.

✗ Git working tree is not clean. — Commit or stash your changes first, or pass --force.

✗ Node X is too old — site-improver requires Node 20+. With nvm: nvm install 20 && nvm use 20.

Refusing to run with --auto without --yes — --auto skips every confirmation, so we require --yes as an explicit acknowledgement. Use both together.

Patcher reports skipped — Claude decided the issue was already fixed in source. Re-run with DEBUG=site-improver:* to see what the diagnoser actually picked up.

Full stack trace — On any error, the full stack is written to ~/.site-improver/logs/<timestamp>.log. The CLI prints that path so you don't have to dig.

Cancel a run — Press Ctrl-C once and the run will finish the current step (so you don't end up with a half-applied patch). Press it twice to force-quit.

Status

This is the v0.1 release. The pipeline (detect → boot → observe → diagnose → patch → verify) is end-to-end working with Next.js and Vite projects on macOS / Linux. Windows is best-effort. Expect rough edges around: Lighthouse on dev mode (noisy metrics), the patcher prompt on edge cases, and HMR settling on very large projects.

License

MIT