One command. AI-powered web performance optimization.
Analyze any URL with PageSpeed Insights and let your AI agent apply the fixes — automatically.
Why Pulse • Getting Started • Usage • How It Works • Contributing
You know your site is slow. PageSpeed Insights tells you what's wrong — but you still have to manually track down every render-blocking script, every oversized image, every missing cache header, and fix them one by one.
Pulse closes the loop. It fetches the PageSpeed report, formats it as structured markdown, and generates targeted optimization instructions — so your AI agent can read the diagnosis and apply the fixes directly in your codebase.
- Real PageSpeed data — Fetches live Lighthouse scores, Core Web Vitals, opportunities, and diagnostics via the PageSpeed Insights API v5
- Structured markdown report — Scores, metrics, field data (CrUX), opportunities sorted by impact, diagnostics, and passed audits
- AI-ready optimization plan — Generates specific, actionable instructions mapped to 20+ performance patterns
- Zero dependencies — Pure Node.js, no external packages
- Works with any AI agent — Claude Code, Cursor, Trae, Antigravity, or any tool that can read files
- Mobile & Desktop — Analyze either strategy with a single flag
Requirements:
- Node.js 18+
- A Google PageSpeed Insights API key (get one free)
Pulse is designed to be invoked through your AI agent chat. The agent runs the command, reads the output, and applies optimizations to your project automatically.
Step 1 — Open your AI agent chat (Claude Code, Cursor, Trae, Antigravity, etc.)
Step 2 — Paste this prompt:
Run `npx @isonnymichael/pulse optimize --url https://example.com --api-key YOUR_API_KEY` and execute the results
Step 3 — Done. The agent reads the report and applies performance optimizations to your project.
Flags:
| Flag | Required | Description |
|---|---|---|
-u, --url <url> |
Yes | The URL to analyze |
-k, --api-key <key> |
Yes | Google PageSpeed Insights API key |
-s, --strategy <strategy> |
No | mobile (default) or desktop |
--categories <list> |
No | Comma-separated: performance,accessibility,best-practices,seo |
Run `npx @isonnymichael/pulse optimize --url https://mysite.com --api-key AIza...` and execute the results
Run `npx @isonnymichael/pulse optimize --url https://mysite.com --api-key AIza... --strategy desktop` and execute the results
Run `npx @isonnymichael/pulse optimize --url https://mysite.com --api-key AIza... --categories performance` and execute the results
- Fetches — Calls the PageSpeed Insights API v5 with your URL and API key
- Analyzes — Extracts scores, Core Web Vitals, opportunities (sorted by impact), diagnostics, and field data
- Formats — Generates a structured markdown report with tables, scores, and details
- Instructs — Appends AI optimization instructions mapped to each detected issue (20+ patterns)
- Writes — Saves everything to
PULSE.mdin your project root - Executes — Your AI agent reads
PULSE.mdand applies the fixes to your codebase
Based on the report, the AI agent will:
- Eliminate render-blocking CSS/JS
- Convert images to modern formats (WebP/AVIF)
- Add lazy loading to offscreen images
- Remove unused CSS and JavaScript
- Enable text compression
- Optimize font loading with
font-display: swap - Reduce main-thread work
- Add preconnect hints for third-party origins
- Set efficient cache policies
- Fix layout shift issues
- And more — each action is mapped to a specific PageSpeed audit
The generated PULSE.md contains:
| Section | Description |
|---|---|
| Scores | Performance, Accessibility, Best Practices, SEO scores with visual indicators |
| Core Metrics | FCP, LCP, TBT, CLS, Speed Index, TTI with values and scores |
| Field Data | Real-user Chrome UX Report data (LCP, FID, CLS, INP, TTFB) when available |
| Opportunities | Actionable suggestions sorted by estimated time savings |
| Diagnostics | Additional performance information and warnings |
| Passed Audits | What your page already does well |
| AI Instructions | Specific optimization tasks for the AI agent to execute |
pulse/
├── bin/
│ └── pulse.cjs # CLI entrypoint
├── src/
│ ├── index.js # Argument parser and command router
│ ├── commands/
│ │ └── optimize.js # `pulse optimize` command logic
│ └── utils/
│ ├── pagespeed.js # PageSpeed Insights API client
│ └── formatter.js # Markdown report and AI instruction generator
└── package.json
- Go to the Google Cloud Console
- Create a new project (or select an existing one)
- Enable the PageSpeed Insights API
- Go to Credentials and create an API key
- Use the key with
--api-key
The API is free with generous rate limits (25,000 queries/day).
Run it on your production URL. Analyze the live site, not localhost. PageSpeed Insights needs a publicly accessible URL to measure real-world performance.
Start with mobile. Mobile is the default and usually the more constrained environment. Fix mobile performance first, then check desktop.
Focus on opportunities with the highest savings. The report sorts opportunities by estimated time savings. Tackle the top items first for maximum impact.
Re-run after applying fixes. Run Pulse again after your AI agent applies optimizations to verify improvements and catch remaining issues.
Contributions are welcome! See CONTRIBUTING.md for details.
The most valuable areas:
- New optimization patterns — Add detection and instructions for more PageSpeed audits
- New commands — Accessibility-focused analysis, SEO-focused analysis, comparison reports
- Report improvements — Better formatting, more detail extraction, trend tracking
- Bug fixes — Open an issue first if you're unsure
git clone https://github.com/isonnymichael/pulse.git
cd pulse
npm install
# Test locally
node bin/pulse.cjs optimize --url https://example.com --api-key YOUR_KEYGPL-3.0 © Sonny Michael
If Pulse saved you time, consider giving it a ⭐ — it helps others find it.
Want to support ongoing development? Sponsor on GitHub ♥