Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (site-improver) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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

Detect the framework (Next.js, Vite, CRA, Astro), package manager, styling stack, git state.
Boot your project's dev server on a free port.
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.
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.
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).
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