BuildOver Setup

BuildOver wraps your existing dev server with a reverse proxy + AI chat widget. You visit localhost:<buildover-port> instead of your original port, and a floating panel lets you ask Claude to edit your source files live with HMR.

Packages (all pulled in by the buildover CLI):

buildover — CLI (buildover dev)
buildover-server — auto-installed dependency
buildover-widget — auto-installed dependency

Workflow

1. Check Existing Installation

buildover --version 2>/dev/null || npx buildover --version 2>/dev/null

2. Install BuildOver

Global (recommended):

npm install -g buildover

Local dev dependency:

npm install --save-dev buildover
# pnpm add -D buildover / yarn add -D buildover

3. Detect Target Port

Read package.json to find the dev port:

cat package.json | grep -E '"dev"|"start"'

Common defaults if not specified:

3000 — React CRA, Next.js
5173 — Vite
4200 — Angular
8080 / 8000 — generic / Django / Flask

Ask the user to confirm if unclear.

4. Configure API Key

grep "ANTHROPIC_API_KEY" .env 2>/dev/null || echo "not set"

If missing, add to .env (create if needed):

ANTHROPIC_API_KEY=sk-ant-...

Get a key at https://console.anthropic.com/settings/keys.

The proxy and widget work without a key — only AI chat requires it.

5. Start BuildOver

# Global install:
buildover dev --target <target-port> --port <buildover-port>

# Local install:
npx buildover dev --target <target-port> --port <buildover-port>

Default --port is 4100. Use 10001 to avoid common conflicts.

Example (Next.js on 3000, BuildOver on 10001):

buildover dev --target 3000 --port 10001
# → Open http://localhost:10001

6. (Optional) Cloudflare Tunnel for Remote Access

If the user wants a public HTTPS URL:

# Install (macOS)
brew install cloudflared

# Authenticate & create tunnel
cloudflared tunnel login
cloudflared tunnel create <tunnel-name>

Create ~/.cloudflared/config.yml:

tunnel: <tunnel-id>
credentials-file: /Users/<username>/.cloudflared/<tunnel-id>.json

ingress:
  - hostname: your-subdomain.yourdomain.com
    service: http://localhost:<buildover-port>
  - service: http_status:404

cloudflared tunnel run <tunnel-name>

Verification Checklist

No ⚠ No authentication configured at startup → API key loaded ✓
Banner shows correct target and BuildOver URLs ✓
Opening http://localhost:<buildover-port> shows original site + floating chat button ✓
Sending a chat message triggers [Agent] logs in the server output ✓

Common Issues

Issue	Fix
`EADDRINUSE` on BuildOver port	`lsof -i :<port>` → kill the process
`⚠ No authentication configured`	Add `ANTHROPIC_API_KEY` to `.env` and restart server
Chat sends but no code changes	Check server logs for `[Agent] Error` — usually auth failure
Widget not visible	Hard-refresh; check `/buildover/widget.js` returns 200
HMR not working	Start the original dev server before BuildOver

buildover-setup