web-uplift

web-uplift

web-uplift is an agentic modern-web quality auditor and fixer.

Install it into a web project, then run /web-audit <url> inside your coding agent. The agent gathers real browser evidence, judges the site against modern web-quality principles, writes report.json and report.md, and, when local source is available, can apply fixes and re-audit until the issues are gone.

It is not a conventional check runner. There is no fixed list of coded checks and no canned fixer. The model is the auditor: it chooses the evidence to gather at inspection time, reasons over what it sees, consults Modern Web Guidance, and decides what passes or fails.

Quick Start

Install the audit skill and evidence tools into your project:

npx -y web-uplift@latest install --agent codex

Use the agent you actually run:

npx -y web-uplift@latest install --agent claude        # Claude Code
npx -y web-uplift@latest install --agent codex         # Codex
npx -y web-uplift@latest install --agent gemini        # Gemini CLI
npx -y web-uplift@latest install --agent opencode      # opencode
npx -y web-uplift@latest install --agent all           # install every wrapper
npx -y web-uplift@latest install --dry-run --agent all # preview files without writing

Then, inside your agent session:

/web-audit https://example.com

To fix a local site, pass the served URL and source directory:

/web-audit http://localhost:8080 --source ./src --fix

Reports are retained under reports/<host>/<runId>/, with a latest pointer. Fix mode also emits a before/after comparison so you can see what changed.

What You Get

An audit writes:

• report.md - a readable report with evidence, findings, and a prioritised task list.
• report.json - structured findings that validate against schema/findings.schema.json.
• evidence/ artifacts - screenshots, layout JSON, trace summaries, HARs, heap summaries, videos, Lighthouse output, or other probes the model chose.

Each finding is tied to:

• a principle from knowledge/principles.json,
• the evidence used to prove it,
• a suggested fix backed by Modern Web Guidance,
• and a deduplicated task in taskList.

Requirements

The machine running the audit needs:

• Node 20 or newer.
• Chrome or Chromium. The evidence CLI checks common paths and honours CHROME_BIN.
• ffmpeg if the agent records transition videos.
• Network access for npx, Modern Web Guidance, and optional Lighthouse.
• A coding agent that can read files and run shell commands.

No Playwright, Puppeteer, or browser-automation MCP server is required. web-uplift drives Chrome directly over the Chrome DevTools Protocol.

Agent Install Matrix

web-uplift install copies the one canonical audit skill plus the raw-CDP evidence tools into your project. Each agent gets only a thin wrapper pointing at the same SKILL.md, so the method does not drift.

Agent	Install	What gets placed	Run
Claude Code	npx -y web-uplift@latest install --agent claude	.claude/skills/web-audit/SKILL.md	/web-audit <url>
Codex	npx -y web-uplift@latest install --agent codex	.codex/skills/web-audit/SKILL.md + AGENTS.md snippet	/web-audit <url>
Gemini CLI	npx -y web-uplift@latest install --agent gemini	.gemini/commands/web-audit.toml	/web-audit <url>
Antigravity	npx -y web-uplift@latest install --agent antigravity	.agents/skills/web-audit.md	/web-audit <url>
GitHub Copilot	npx -y web-uplift@latest install --agent copilot	.github/prompts/web-audit.prompt.md + instructions snippet	/web-audit <url>
opencode	npx -y web-uplift@latest install --agent opencode	.opencode/command/web-audit.md + AGENTS.md snippet	/web-audit <url>
all	npx -y web-uplift@latest install --agent all	everything above	per agent

Every install also vendors the evidence CLI, principles, schemas, and guidance lookup notes under .web-uplift/ so the in-session model can call them directly. It also writes .web-uplift/manifest.json with the package version that produced the installed copy.

Keeping Installs Current

Use @latest whenever you install or refresh the skill:

npx -y web-uplift@latest update --agent all

web-uplift update refreshes the canonical skill, evidence CLI, schemas, principles, guidance notes, wrappers, and .web-uplift/manifest.json. If an older manifest is present, the CLI prints the installed version and the version it is updating to.

The CLI also performs a lightweight npm registry update check at most once every 24 hours and prints a warning to stderr when a newer package is available. Set WEB_UPLIFT_NO_UPDATE_CHECK=1 to disable it. For serious broken releases, maintainers can additionally use npm deprecate on old versions so npm itself warns during install.

Claude Code Plugin