PULSE — Frontend Deployment Reviewer

PULSE is an AI skill for Claude Code. Point it at two URLs — your live production build and your new local/staging build — and it tells you whether the deployment is safe to ship.

It collects Lighthouse metrics and JS bundle sizes automatically, detects regressions in Core Web Vitals and bundle size, traces the root cause to a specific package or file, scores the deployment risk from 0 to 10, and suggests concrete fixes with code snippets.

You: compare prod vs my local build:
     https://app.example.com  vs  http://localhost:3000

PULSE: Risk Score: 7.4 / 10  —  RED · BLOCK

       Top regressions:
       · LCP  1.8s → 4.3s  (+2.5s)  green → red  ✗ threshold crossed
       · TBT  90ms → 410ms (+320ms) green → red  ✗ threshold crossed

       Root cause: recharts was added as a sync import in the entry chunk
       (+312 KB gzipped). This blocks the main thread on every page load.

       Fix 1 — Dynamic import recharts (est. impact: LCP −2.1s, TBT −280ms)
         const { LineChart } = await import('recharts')

---

Requirements

Before installing PULSE you need three things:

1. Claude Code

PULSE is a Claude Code skill. It will not work without Claude Code.

Download it free from https://claude.ai/download

Claude Code runs:

• Inside VS Code (install the extension from the marketplace)
• Inside JetBrains IDEs (install the plugin)
• As a standalone terminal tool (claude CLI)

You need a Claude account (free tier works).

2. Python 3

The analysis pipeline is Python. Check if you have it:

python --version   # or: python3 --version

If not, download from https://python.org/downloads (3.8 or later).

3. Node.js

Required to install Lighthouse (the installer does this for you if missing).

node --version

Download from https://nodejs.org (LTS version recommended).

---

Install

Clone this repo once. Then run the installer — it sets PULSE up globally so it works in every project without any per-project config.

Windows

git clone <this-repo-url>
cd pulse
.\install.ps1

If you get an "execution policy" error, run this once first, then retry:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

macOS / Linux

git clone <this-repo-url>
cd pulse
chmod +x install.sh && ./install.sh

The installer:

1. Checks all prerequisites (exits with clear instructions if anything is missing)
2. Installs Lighthouse globally if not already present
3. Copies PULSE to ~/.claude/pulse/
4. Registers a global Claude Code skill at ~/.claude/commands/pulse.md
5. Adds the Puppeteer MCP server to Claude user config (~/.claude.json) and preserves compatibility with ~/.claude/settings.json

After installing: restart Claude Code (or reload the VS Code window) once so the MCP change takes effect.

---

Usage

Open any project in Claude Code. No /pulse command needed — just describe what you want:

compare prod vs localhost:
https://app.example.com  and  http://localhost:3000

is this deploy safe? staging: https://staging.example.com  prod: https://app.example.com

review this PR for performance regressions

PULSE triggers automatically on any deployment review request. It collects data, runs the analysis pipeline, and returns a structured report.

What the report includes

Section	What it tells you
Risk score + verdict	0–10 score and GREEN / YELLOW / RED band
Top regressions	Every metric that crossed a threshold, with old → new values
Root cause	The specific package or file responsible, with corroborating signals
Suggested fixes	Ranked by expected impact, with code snippets for your actual packages
Signal breakdown	Full per-metric Lighthouse data + bundle size deltas
Score breakdown	Transparent table of how each point was assigned

If you only have files (no live URLs)

PULSE also works with pre-exported files. Provide any combination of:

• webpack --json > stats.json (old + new)
• Lighthouse JSON: lighthouse <url> --output json --output-path report.json (old + new)
• package-lock.json from the new build

Drop them into your conversation and PULSE uses whatever is available.

---

How it scores risk

Points accumulate from signals in three categories — Lighthouse metrics, bundle changes, and dependency issues:

Signal	Points
LCP crossed red threshold (>4s)	2.5
CLS crossed red threshold (>0.25)	2.0
TBT / INP crossed red threshold	1.8
Performance score dropped ≥10 pts	2.0
Bundle grew ≥25%	2.0
Heavy library newly sync-imported in entry chunk	1.5 (capped 3.0)
New render-blocking resource	1.0 (capped 2.0)
New high-blocking third-party script	1.0
Duplicate dependency version	0.5 (capped 1.5)

Verdict bands: 0–0.9 GREEN PASS · 1.0–3.9 CAUTION · 4.0–8.9 REVIEW · 9.0–10 RED BLOCK

---

Tuning for your team

All thresholds and weights are in plain Markdown files — edit them directly:

File	What it controls
references/cwv_thresholds.md	Green / yellow / red bands for each metric
references/scoring_rubric.md	Point weights per signal
references/regression_patterns.md	12 regression fingerprints
references/fix_playbook.md	Code snippets for each fix

After editing, re-run install.ps1 / install.sh to push the changes to your global install.

---

Troubleshooting

"PULSE skill not found" Make sure you ran the installer and restarted Claude Code afterward.

"Puppeteer MCP not available" / live URL collection fails Run the installer again — it registers the MCP. Then fully restart Claude Code (not just reload).

Lighthouse command not found

npm install -g lighthouse

Analysis runs but confidence is low PULSE says which inputs are missing. If live URLs aren't accessible (VPN, firewall), export the files manually and paste them in instead.