The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Glamour listing page.
Glamour is a local-first visual compiler and debugging workspace for coding agents. It renders an existing web implementation in pinned Playwright Chromium, compares it to one or more references, attributes visual residuals to DOM/SVG/Canvas/WebGL objects, tests temporary changes, and exports browser-validated vector geometry. Glamour does not generate application source code.
uv, pnpm, or a browser.uv.pnpm format, pnpm lint, and pnpm test include Ruff formatting/lint and pytest for the Python worker.
Projects and immutable run artifacts are stored in .glamour/ under the current directory. Set GLAMOUR_HOME to choose another store. Reference coordinates are CSS viewport pixels; device scale factor remains separate. A viewport PNG must have bitmap dimensions equal to viewport × DPR. Full-page screenshots are retained as structural data; the pinned browser compare currently renders viewport captures.
The minimum input is a lossless PNG plus exact viewport and DPR. For multi-state and responsive work, use a bundle directory with manifest.json and paths relative to it:
Bundle fields retain provenance (exact, provided, measured, derived, estimated, unknown) and confidence. Scene nodes can store raw measurements separately from semantic interpretation so an estimated role cannot overwrite exact geometry. Explicit facts are surfaced by analyze; measured pixel palette, full-page bitmap/content dimensions, and captured browser geometry are distinguished from supplied facts. Multiple references are rendered independently. Responsive changes are observations; breakpoint behavior remains a hypothesis unless supplied explicitly. Crops, assets, font metadata, text blocks, layout relations, scene graph, states, interactions, geometry, and chart data are preserved in the versioned Reference IR.
Each screenshot may set its own targetUrl, actions, and videoTimeSeconds so state references are reproducible against the live implementation. When videoTimeSeconds is supplied, compare/override/optimization pause each video, seek to that time when it is in a browser-reported seekable range, and capture the frozen frame. If the media does not expose that time as seekable, Glamour keeps the current frame and reports the limitation instead of silently claiming the requested time was used. Without videoTimeSeconds, the current frame is paused with a nondeterminism warning. Actions run in order before readiness checks and capture. Supported actions are click, hover, focus, fill, press, selectOption, check, and uncheck; the same setup is replayed for overrides and optimization. For example:
For an animated/video state, add "videoTimeSeconds": 2.4 to that screenshot record.
The core exports Zod schemas for the versioned bundle, screenshot/action, asset/font, typography, scene/layout, color/effect, crop, geometry, interaction, responsive mapping, and uncertainty records. Extended records preserve domain-specific fields while validating the shared typed fields.
The CLI and MCP server call the same core APIs. compare without a reference runs every viewport/state reference. Overrides are transient and never edit source. Optimizer search has a bounded evaluation and timeout budget.
Glamour is an agent tool, not a website builder UI. The coding agent edits the user's existing website; Glamour supplies MCP tools to measure browser output and verify corrections. The Codex plugin installs both the workflow skill and the MCP connection. It downloads the matching, version-pinned runtime on first activation, so users do not clone or build the Glamour repository.
Add the marketplace and install the plugin once:
Or use /plugins to install Glamour after adding the marketplace. Codex retrieves plugin files itself; you do not manually clone or build the Glamour repository.
Open the website project you want the agent to change. Do not open a Glamour checkout.
Attach a reference screenshot to the conversation. A prepared reference bundle is optional.
Ask: Implement this page in the current project from the attached reference. Use Glamour to compare it in the browser, fix the largest mismatches, and report anything still uncertain.
The plugin's first activation downloads its pinned Node and Python runtime. The first visual comparison downloads pinned Chromium automatically; all browser and runtime files are cached in the plugin's persistent data directory. The agent starts or reuses the target site's development server and invokes Glamour tools as part of its work.
The skill instructs the agent to inspect the site repository, create real semantic and responsive source code, compare all provided references, inspect the largest mismatches, try transient overrides where useful, apply verified changes, and report remaining uncertainty. No human-facing Glamour UI is part of this workflow.
After the public npm package is available, add this server to the agent's MCP settings. The config shape below is used by stdio MCP clients such as Claude Desktop and Cursor; other clients may call the section servers instead of mcpServers:
Alternatively, install the launcher globally with npm install --global glamour-mcp, then set the MCP command to glamour-mcp with no arguments.
The package contains only a small launcher. It downloads and caches the matching runtime on first start; no Glamour checkout, Python, uv, pnpm, or browser installation is required. Node.js 22+ and network access are needed for the first launch. The release workflow publishes the package to npm and adds its metadata to the official MCP Registry, where supported clients can install it from their server browser.
After connecting the server, open the website project in the agent, attach the reference screenshot, and ask: Implement this page in the current project from the attached reference. Use Glamour to compare it in the browser, fix the largest mismatches, and report anything still uncertain.
For local development, build with pnpm build and register apps/mcp-server/dist/index.js as an stdio MCP server. Example:
Tools: visual.create_project, visual.analyze_reference, visual.compare, visual.inspect, visual.extract_geometry, visual.test_overrides, visual.optimize, visual.finalize. Resources expose project manifest, Reference IR, latest Target IR, run diff/region, artifacts, and final report under visual://project/.... Responses include schemaVersion: "1"; larger images and vector output are referenced as resources/artifacts.
Metrics are lower-is-better normalized residuals, not a claim of percent-identical pixels. Chromium version, input SHA-256, target URL, viewport/DPR, artifacts, and warnings are recorded per run. networkidle is the default readiness strategy; applications with persistent connections should choose load or domcontentloaded and provide readySelector/predicate. Arbitrary time, randomness, server data, carousels, and external dependencies cannot be frozen automatically; supply stable fixtures/state where needed.
visual.extract_geometry invokes the internal OpenCV/NumPy/scikit-image worker through uv, emits SVG (or a Path2D string), and validates its browser render against the source crop. Open strokes are skeletonized and fitted as cubic curves; closed regions are traced as contours. Extraction is an approximate fallback: original vector assets or chart data should take precedence. Warnings and fit/validation loss are returned.
Canvas 2D drawing commands and WebGL/WebGL2 draw calls are instrumented before application scripts. Regions can be attributed to the rendering canvas; WebGL calls also report primitive type, vertex/index count, instance count, viewport bounds and their draw ID. A browser-rendered 3D scene is therefore compared and its WebGL draw activity can be inspected, while its engine-level scene graph, mesh semantics and source component are not inferred from pixels. For video, supply videoTimeSeconds on a screenshot reference to seek and freeze the target at a reproducible frame. Complex raster regions can still be inspected and passed through geometry extraction; reconstructed vectors remain approximations, so supplied scene assets or source data take precedence. WebGL clipping and source file/line mapping are not guaranteed.
See CONTRIBUTING.md for Conventional Commits, formatting, lint, TypeScript, Python, tests, and CI requirements.
Push a vMAJOR.MINOR.PATCH tag matching the plugin version to publish a GitHub Release. The release workflow reruns all quality gates and publishes source plus standalone Node/Python runtime archives for macOS arm64/x64, Linux arm64/x64, and Windows x64. Installed plugins fetch the archive matching the current machine. See CONTRIBUTING.md for the release process.