Vacuum — Product Guide & Tool Reference

The System

Vacuum has two independent halves. The Chrome extension runs inside the browser — it captures DOM, styles, and interactions with zero AI, zero network calls. The Vacuum plugin is installed into Claude Code and contains two things: an MCP server (51 deterministic tools) and Skills (guided workflows where Claude orchestrates those tools).

Where the AI lives: Not inside any tool. All 51 MCP tools are deterministic code — zero LLM calls, fully reproducible. Some are simple data operations (list, get, delete). Others use sophisticated heuristics: deltaE color matching, sibling similarity detection, CSS property normalization, zone boundary detection. Smart, but not AI. The AI is Claude Code itself — skills guide it through multi-tool workflows where it reads tool output, reasons about it, makes integration decisions, and writes code.

EXT	Chrome Extension — runs in the browser, captures pages. Standalone.
PLUGIN	Vacuum Plugin — installed into Claude Code. Contains the MCP server and Skills.
MCP	51 deterministic tools — no LLM calls inside. Called by Claude Code over stdio/HTTP.
SKILL	AI-orchestrated slash command — guides Claude through MCP tool chains.

Heuristic	Smart algorithms, no LLM
AI-Orchestrated	Claude reasons + writes code

Chrome Extension EXT

Deterministic capture engine — no AI, no network calls, all local

Activate with the toolbar icon or Ctrl+Shift+E
Captures full DOM tree, all stylesheets, computed styles, hover/focus states, and interaction patterns
Dual capture engine: stylesheet capture (for HTML+CSS) runs in parallel with computed capture (for Tailwind/React)
Outputs 4 formats: HTML+CSS, HTML+Tailwind, TSX+CSS, TSX+Tailwind
Every element gets a NID (node ID) — the ground truth anchor for downstream verification
Captures auto-sync to the local MCP server over HTTP

Vacuum Plugin PLUGIN

Installed into Claude Code — contains MCP 51 tools + SKILL 3 guided workflows

Headless capture from the CLI — no browser window needed
Computed-to-computed scoring: renders output in Playwright, compares getComputedStyle per NID against captured ground truth
Auto-patching: capture_style_fix fixes CSS mismatches and returns corrected HTML
Decomposition: splits pages into semantic zones (header, hero, cards, footer) with NID refs
Handshake integration: maps captured zones to your real project components and design tokens
One-click deploy to Cloudflare Pages for shareable preview URLs

Extension Capture Modes

Two capture scopes — element or full page — plus the data engine that powers both.

Element Capture

Hover and click to capture a single component, section, or region. The extension highlights the selection boundary in real-time. Captures the element plus its full subtree — all children, styles, pseudo-elements, and interactions.

Page Capture

Captures the entire visible page in one shot. Grabs every stylesheet, all computed styles, SVGs, web fonts, background images, and interaction states. Outputs a single self-contained file.

Data Capture

What the engine actually records: full DOM tree, all stylesheets (original CSS rules + cascade), computed styles per element, hover/focus/active state diffs, interaction patterns, SVGs, web fonts, and NID ground truth. All deterministic, all local.

Hold modifier keys during element capture to change selection behavior:

Click

Normal

Smart boundary — picks the most useful component-level element

⌥ Option

Deep

Deepest element under cursor. Penetrates Shadow DOM boundaries.

⇧ Shift

Parent

Walk up ancestors — select larger containers

⌘ Cmd

Copy

Pin tooltip, click to copy values to clipboard

Tool Inventory

All

Quick Clone

Verify & Fix

Handshake

Materialize

Design System

Multi-Page

Deploy

Other tools

Extension Capture Engine

Built into the Chrome extension — these run in the browser, not through MCP

Element Capture

EXT

Select and capture any component on a live page

Click to capture an element and its full subtree. Normal mode picks smart boundaries, Deep mode (⌥) penetrates Shadow DOM to reach the deepest node, Parent mode (⇧) walks up ancestors.

Captures through Shadow DOM — reaches inside web components that other tools can't see.

Page Capture

EXT

Capture an entire page as a self-contained file

Grabs every stylesheet, computed style, SVG, web font, background image, and interaction state. Produces a single HTML/TSX file that renders identically without the original server.

Dual Capture Pipeline

EXT Heuristic

Two capture strategies run in parallel for maximum accuracy

Stylesheet capture preserves original CSS rules, selectors, and cascade for HTML+CSS output. Computed capture reads getComputedStyle per element for Tailwind/React output. Both run simultaneously.

No other capture tool preserves both the authored CSS and the computed result at the same time.

Format Transformer

EXT Heuristic

Convert captured data into 4 production-ready output formats

HTML+CSS (vanilla, pixel-perfect), HTML+Tailwind (utility classes with snap tolerance), TSX+CSS (React with inline styles), TSX+Tailwind (React with Tailwind). Runs entirely in the extension, deterministic.

Interaction Capture

EXT Heuristic

Records hover, focus, and active states as CSS diffs

Detects interactive elements (buttons, links, inputs), captures the CSS property changes on hover/focus/active, and maps them to NID references for downstream reconstruction.

NID Tagging

EXT

Assigns a stable ground truth ID to every captured element

Each element gets a unique NID (node ID) with its computed styles stored in nid-styles.json. Downstream tools use NIDs to compare, verify, and patch individual elements without ambiguity.

Capture

Triggering, reading, and navigating captures

capture_trigger

MCP

Capture any URL from the command line — no browser window needed

Launches headless Chrome with the Vacuum extension, navigates to the URL, runs the full capture pipeline, syncs to the MCP server. Supports visible mode for auth flows, configurable wait timers, viewport size, and all 4 output formats.

Full browser-fidelity capture from the CLI. No headless approximation — runs the real extension.

capture_get

MCP

Read the full output code for a capture

Returns the transformed output (output.html or output.tsx). For large captures, use capture_get_continue to paginate through the remaining content.

capture_transform

MCP Heuristic

Re-run the transformer in a different output format

Converts an existing capture to a new format without re-capturing. Example: switch html-css to tsx-tailwind. Re-runs the deterministic transformer pipeline on the stored capture data.

capture_get_structure

MCP

View the DOM tree as a navigable hierarchy

Returns tag names, NID references, and nesting depth for every element. Understand page structure at a glance without reading the full HTML output.

capture_list_elements

MCP

Flat summary of every NID element in a capture

Compact list: tag, text preview, key styles, NID reference. Powers Studio AI editing and quick element lookup.

capture_get_interactions

MCP

Get the captured hover, focus, and active state map

Returns the interaction map: which CSS properties change on hover/focus/active for each interactive element, keyed by NID. Used to reconstruct interactivity in output code.

capture_get_subzone

MCP

Extract one zone's code from a full-page capture

Pull out just the header, hero, footer, or any named zone by its layout tree boundary. Returns clean HTML/TSX for that section only.

Quality & Verification

Measuring and improving capture-to-output fidelity

capture_style_fix

MCP Heuristic

Render, compare, score, and auto-patch CSS mismatches

Renders the output HTML in Playwright, runs getComputedStyle on every NID element, compares against captured ground truth. Returns: mismatch list, score (0-100), auto-fixed HTML with corrections applied, coverage ratio.

Computed-to-computed CSS verification. Renders both sides and auto-patches the diff — nothing else does this.

capture_visual_diff

MCP Heuristic

Pixel-level screenshot comparison: source vs. output

Screenshots the rendered output alongside the original source. Returns diff percentage, a visual diff image highlighting changes, and a pass/warn/fail verdict. The most honest metric — measures what the user actually sees.

capture_diagnose

MCP Heuristic

Root-cause analysis for visual mismatches

Renders in Playwright, inspects every NID, identifies why things look wrong — missing fonts, broken var() references, wrong colors, missing pseudo-elements. Returns actionable fix suggestions ranked by visual impact.

audit_get

MCP Heuristic

Full quality report — style, visual, structural, and health in one call

Combines capture_style_fix, capture_visual_diff, capture_verify, and capture_health_check into a single comprehensive audit. One tool call, complete picture.

capture_health_check

MCP Heuristic

Fast integrity check — no Playwright needed

Checks NID count, unresolved var() references, CORS-blocked stylesheets, file integrity. Sub-second response. Run this first before committing to a full audit.

capture_verify

MCP

Structural verification — text, SVGs, repeating groups

Checks that text content survived, SVGs are present, repeating groups have the right count. Does NOT check visual styling — use capture_style_fix for that.

capture_score

MCP

Retrieve the last computed quality grade (A+ through F)

Returns the most recent score from style + visual accuracy checks. Quick lookup — doesn't re-run analysis.

capture_issues

MCP

Known issues and workarounds for a specific capture

Returns documented issues with IDs, status (open/unfixable), descriptions, and workarounds. Used by autoloop's circuit breaker to avoid infinite fix attempts.

capture_verify_styles

MCP

Deprecated — replaced by capture_style_fix

Legacy tool. Use capture_style_fix instead.

Decomposition & Analysis

Breaking captures into components, tokens, and patterns

capture_decompose

MCP Heuristic

Automatically split a page into semantic component zones

Heuristic rules + sibling similarity detection identify zones: header, nav, hero, card grids, footer. Each zone gets NID refs, bounding box, semantic name. Powers component extraction, zone-aware editing, and handshake integration.

Automatic component boundary detection — no manual slicing, no AI hallucination. Pure heuristic.

capture_extract_tokens

MCP Heuristic

Reverse-engineer a site's design tokens from its computed styles

Extracts color palette, spacing scale, typography scale, and border-radius values from computed styles. Outputs portable tokens ready for Tailwind config or CSS variables.

capture_match

MCP Heuristic

Score how well captured elements match a design system

Compares captured elements against a saved design system profile. Returns structural + style similarity scores per element, identifying which components from your library could replace each captured element.

capture_extract_shared

MCP Heuristic

Find shared UI patterns across multiple captures

Compares two or more captures to surface common elements: shared headers, repeated layouts, consistent color schemes. Useful for identifying reusable components across pages.

Handshake

Capture → project integration using your real components and tokens

handshake_build_bible

MCP Heuristic

Inventory your project's components, tokens, routes, and conventions

Deep-scans the target project: every component (name, props, import path), design tokens (CSS vars, Tailwind theme), routing structure, framework info. Stores as bible.json — the "what do you have?" step.

handshake_integrate

MCP Heuristic

One call: bible → zones → compose → validate → write files

The full integration pipeline in a single API call. Takes bible + capture, decomposes into zones, maps to your components, writes production code using your design tokens, validates against NID ground truth.

End-to-end integration in one call. AI composes with your components, NID ground truth validates the result.

handshake_analyze_capture

MCP Heuristic

Map captured zones to your project's components with confidence scores

Decomposes capture into zones, matches each zone to bible components. Returns confidence scores and mapping rationale. The "what maps to what?" step — review before committing to integration.

handshake_prepare_jsx

MCP Heuristic

Strip captured output into clean, minimal JSX for LLM consumption

Removes verbose inline styles, preserves semantic structure and intent. Produces readable JSX that an LLM can reason about without drowning in style noise.

handshake_validate

MCP Heuristic

Verify integration output compiles and renders correctly

Checks imports resolve, components match prop interfaces, syntax is valid, and rendered output passes NID ground truth comparison. The quality gate after integration.

handshake_get_bible

MCP

Read the cached project bible without re-scanning

Returns the previously built bible.json. Skips the scan step if the project hasn't changed.

handshake_adjust

MCP

Override zone decisions after integration

Skip zones, change component mappings, override token choices. Re-runs only the affected zones — doesn't redo the whole integration.

handshake_get_component_source

MCP

Read a component's full source code from the project bible

Returns the actual source file for a bible component. Used during integration to understand component API, prop types, and usage conventions.

Design System

Detecting, storing, and exporting design tokens and component libraries

design_system_scan

MCP Heuristic

Detect a project's design system structure automatically

Finds component library structure, token definitions (CSS variables, Tailwind theme extensions), naming conventions, and export patterns. The foundation for matching and integration.

design_system_export

MCP

Export tokens as CSS variables, Tailwind config, or component JSON

Portable export of a design system in the format you need. CSS variables file, Tailwind config snippet, or full component inventory JSON.

design_system_save / get / list / delete

MCP

Persist and manage design system snapshots

Save, retrieve, list, and remove design system profiles. Stored snapshots are used by capture_match and handshake tools for component and token matching.

design_system_refresh

MCP

Re-scan and update a stored design system profile

Re-runs the scan on the project and updates the saved profile with any new tokens, components, or convention changes.

Rebuild

Capture → project code with route wiring and convention matching

capture_rebuild_execute

MCP Heuristic

Write capture code into a project with route wiring and active states

Writes page component, registers the route, wires navigation links, adds active states. Follows the project's existing file structure, naming, and code conventions.

capture_rebuild_survey

MCP Heuristic

Analyze how a capture should fit into an existing project

Scans the project's existing components, routes, and layout. Proposes integration decisions: which route path, which layout to use, which components to reuse vs. create new.

capture_rebuild_verify

MCP

Verify the rebuild output compiles and integrates correctly

Checks that imports resolve, routes are registered, components render, and TypeScript passes. Run after capture_rebuild_execute to catch integration issues.

Scaffold & Deploy

Generate complete apps and deploy shareable previews

capture_scaffold

MCP Heuristic

Generate a complete multi-page app from multiple captures

Takes N captures and produces a full app scaffold: file structure, routing, shared layout, cross-page navigation. Supports React and Vue. One command from captures to runnable app.

capture_deploy

MCP

Deploy a capture to Cloudflare Pages — get a public URL instantly

Deploys the capture output as a static site to Cloudflare Pages. Returns a public URL for sharing with stakeholders, clients, or team review.

Utility & Infrastructure

Internal: Autoloop SKILL AI-Orchestrated

Pipeline regression testing — not a user-facing workflow

/autoloop

SKILL AI-Orchestrated

Autonomous capture → score → fix → re-score loop for pipeline development

Internal tool for Vacuum developers. Captures a URL, scores visual fidelity, diagnoses mismatches, applies code fixes, re-scores — repeats until ≥95% or a known-issue circuit breaker halts. Used for regression testing the capture pipeline, not for end-user workflows.

Trigger: "autoloop" · "capture loop" · "regression test"

Utility

Server health, project detection, capture management, and local preview

status

MCP

Server health check — uptime, version, database stats

Returns server uptime, version, git commit, database stats, and capture count. First thing to check when tools aren't responding.

project_scan

MCP

Quick project stack detection — framework, structure, component count

Lightweight scan: detects framework (React, Vue, Next, etc.), reads package.json, maps src structure, counts components. Faster than handshake_build_bible when you just need the basics.

preview_serve

MCP

Serve a capture directory over HTTP for local browser preview

Points the local server at a capture directory so you can open it in a browser. Used by Studio and by scoring tools that need to render captures.

capture_list

MCP

List all captures with ID, title, URL, format, and timestamps

Returns all stored captures. Filter by domain or type (page/element). Shows asset counts, rule counts, and when each capture was taken.

capture_delete / capture_cleanup

MCP

Remove captures — by ID or bulk by age/count

capture_delete removes a specific capture by ID. capture_cleanup bulk-removes old captures, keeping the N most recent. Both clean disk and database.

capture_stats

MCP

Aggregate stats — total captures, disk usage, per-domain counts

Overview of what's stored: how many captures, how much disk space, which domains have the most captures.

profile_save / profile_get / profile_list

MCP

Save and reuse capture configuration profiles

Store capture preferences: output format, snap mode, viewport size, CSS selectors. Save once, reuse across captures for consistency.