Project Overview & Architecture
rubenhassid1/remake (v0.1.0) is an open-source website remake and brand replacement engine created by How to AI newsletter author Ruben Hassid under the MIT license. Standard web scrapers and screenshot-to-code importers break during offline replay due to wall-clock drift, unseeded randomness, live API calls, or desynchronized scroll animations. Remake splits the workflow into four closed-loop stages—single-visit capture, frozen-time pixel verification, full-site content and image slot replacement, and private repository plus passcode-gated deployment—built for Claude Code's autonomous /goal loop (using remake report printing REMAKE COMPLETE as the finish condition).
The repository comprises two core components: the CLI engine in engine/bin/remake.mjs and engine/lib/*.mjs (built on Node.js >=20, playwright ^1.52.0, parse5 ^7.3.0, and pngjs ^7.0.0), and the Claude Code skill specification in plugins/remake/skills/remake/SKILL.md. All artifacts from remake init through remake ship live inside site/ (the deployable static site) and remake/ (HTTP cache, baseline screenshots, diff strips, and slot manifests) at the project root.
Stage 1 · Single-Visit Capture & Polite Fetcher: remake capture / fetch
- Opens the target URL once in Chromium across desktop 1440x900 and phone 390x844 viewports
- Records all HTTP and API responses into remake/.cache/http/, blocks trackers, and extracts source maps into remake/sources/
- Polite fetcher requests missing assets one at a time per host at 0.5 s (500 ms) intervals, falling back to Internet Archive CDX after 2 consecutive failures
Stage 2 · Offline Replay Runtime: site/ & runtime.js
- Rewrites external CDN assets under /_ext/<host>/... and strips integrity and CSP meta tags
- Injects runtime.js to replay fetch and XMLHttpRequest calls matched by HTTP method, URL, and request body FNV-1a 32-bit hash
- Disables service workers and beacons, and holds form submissions so external backends are never triggered
Stage 3 · Frozen Time & Seeded Randomness: freeze.mjs
- Pauses the Playwright clock at 2026-01-01T12:00:00Z before the first script executes, advancing in fixed 100 ms steps
- Replaces global Math.random with independent per-call-site RNG streams keyed by filename and line number (default seed 1337)
- Parks all video elements on frame 0, disables CSS animations during capture, and triggers scroll events via mouse wheel steps
Stage 4 · Noise Mask & Pixel Scoring: remake score / accept
- Loads the original site twice back-to-back and dilates any changing pixels by 3 px to build a blue noise mask
- Compares up to 40 screens per viewport plus 24 scrolling motion frames spaced 150 ms apart; a pixel differs if any RGB channel differs by more than 24/255
- Pass thresholds: >= 98% of stable pixels per screen, >= 95% per motion frame, and page height within <= 4 px
Stage 5 · Content Slots & Zero-Leak Image Replacement: remake slots / images / apply / board
- remake slots parses HTML via parse5 to catalog headlines, body copy, buttons, links, logos, images, videos, colors, and fonts in remake/content.json
- remake images measures a 64x64 canvas with k-means in Chromium to extract a 5-color palette, brightness, saturation, and aspect ratio without sending original photos to generators
- remake images --make generates replacements via Codex, OpenAI gpt-image-1, Gemini, CC0 stock, or palette art, while remake board builds /_remake/ and /_remake/swap/
Stage 6 · Private Repository & Passcode Gate Shipping: remake ship / report
- Moves _next/static/immutable to avoid Vercel reserved path errors and creates a private GitHub repository via gh
- Deploys via vercel behind middleware.js and REMAKE_PASSCODE (returning 401 when locked, setting a SHA-256 remake_pass cookie, and sending X-Robots-Tag noindex)
- remake report checks every gate and prints REMAKE COMPLETE so the /goal loop knows the task is finished
Source: docs/HOW-IT-WORKS.md, engine/bin/remake.mjs, and engine/lib/*.mjs.
Project Directory Layout & State Files
Running remake init <url> creates a workspace in ~/remakes/<site> by default, separating deployable files from verification state:
| Path | Stage | Purpose & Structure |
|---|---|---|
site/ | remake capture / apply / board | Deployable static site root pushed to Vercel, including /_ext/<host>/ external assets, the /_remake/ side-by-side drag proof page, and the /_remake/swap/ swap board. |
remake/remake.json | remake init | Project configuration storing target url, pages, maxPages (default 1), dual viewport dimensions, and score thresholds. |
remake/.cache/http/ | remake capture | Single-visit HTTP and API response store replayed by remake score without re-contacting external origin servers. |
remake/original/ | remake score | Baseline screenshots (NN.png), 3 px dilated noise masks (NN.noise.png), and meta.json across both viewports and scrolling motion. |
remake/score/ & remake/score.json | remake score | Per-screen and per-frame three-part diff strips (original | remake | red diff and blue noise mask) and structured score report. |
remake/content.json | remake slots | Full-site replaceable slot manifest containing original, swap, status, and the brand replacement completion percentage (summary.yours). |
remake/images.json & images-sheet-NN.png | remake images | Dimensions, orientation, 5-color palette, brightness, saturation, prompt, and 20-image contact sheets for every unswapped image slot. |
remake/credits.json | remake images --make | Attribution log recording the generation provider (Codex, OpenAI, Gemini, Openverse / Wikimedia Commons stock, or palette art) for each replacement image. |
remake/ship.json & REPORT.md | remake ship / report | Records the private GitHub repository URL, live Vercel URL, REMAKE_PASSCODE, external gate verification result, and final status report. |
Environment Requirements & Installation
Remake requires Node.js >=20, git, GitHub CLI (gh, signed in), Vercel CLI (vercel, signed in), and Playwright's Chromium browser.
Step 1: One-Line Installer & Claude Code Plugin Marketplace
Running the official install.sh script verifies prerequisites, symlinks the remake CLI to ~/.local/bin/remake, and installs the skill into ~/.claude/skills/remake; inside Claude Code you can also install from the plugin marketplace:
# Install Remake CLI and Claude Code skill with one command
curl -fsSL https://raw.githubusercontent.com/rubenhassid1/remake/main/install.sh | bash
# Or add the official plugin marketplace inside Claude Code
/plugin marketplace add rubenhassid1/remake
/plugin install remake@remakeStep 2: Manual Repository Clone & remake doctor --fix
To inspect the engine source or manage a custom installation directory, clone the repository into ~/.remake and run remake doctor --fix to install missing gh, vercel, and Playwright Chromium (150 MB) dependencies:
git clone https://github.com/rubenhassid1/remake.git ~/.remake
cd ~/.remake && npm install
mkdir -p ~/.local/bin
ln -sf ~/.remake/engine/bin/remake.mjs ~/.local/bin/remake
# Check and auto-install missing dependencies (Node 20+, git, gh, vercel, Chromium)
remake doctor --fixStep 3: Verify CLI Sign-In & Optional Image Generation Keys
remake ship requires authenticated GitHub and Vercel CLI sessions; remake images --make checks for a signed-in local Codex installation (~/.codex/auth.json), OPENAI_API_KEY, and GEMINI_API_KEY (or GOOGLE_API_KEY) in order, falling back to CC0 stock photos (stock) and palette geometry (art) when no keys are present:
# Authenticate GitHub or Vercel in your browser if flagged by remake doctor
gh auth login --web
vercel login
# Confirm all prerequisites are ready
remake doctorCore Skills & Command Toolchain
Remake's CLI and Claude Code skill consist of 6 core operational modules covering capture, debugging, pixel scoring, content swapping, and deployment.
Phase 01 · Single-Visit Capture
remake init <url> · remake capture [--archive]
Dual-viewport single-visit recording, source map extraction, and Polite queue fetching
remake init initializes the workspace (default ~/remakes/<site>); remake capture visits once on desktop (1440x900) and phone (390x844), writes site/, extracts source maps into remake/sources/, and fetches responsive srcset assets via a 0.5 s per-host Polite queue.
Phase 02 · Local Server & 404 Fetcher
remake serve [--port 4310] · remake fetch --missing
Local preview server, 404 missing-asset logger, and polite recovery
Starts the local server (including the /_remake/ proof page and /_remake/swap/ swap board) and logs missing fonts, images, or chunks to remake/missing.log; running remake fetch --missing downloads those files and rewrites paths.
Phase 03 · Frozen-Time Pixel Scorer
remake score [--viewport] [--no-motion] · remake accept
Frozen-clock pixel comparison, 3 px noise masking, and 24-frame scroll verification
Freezes page time and RNG seeds, masks unstable pixels with a 3 px dilated blue noise mask, scores every screen (threshold >= 98%), and verifies 24 scrolling motion frames (threshold >= 95%). Unfixable external diffs scoring >= 90% can be recorded via remake accept.
Phase 04 · Slot Parser & Visual Board
remake slots · remake board
Full-site content slot extraction, side-by-side drag proof page, and swap board
remake slots parses HTML with parse5 into remake/content.json; remake board builds the site/_remake/ drag-handle proof page, the site/_remake/swap/ interactive swap board, and the MAKE-IT-YOURS.md checklist.
Phase 05 · Privacy-Safe Image Replacer
remake images [--make] · remake apply
Zero-leak palette measurement, multi-provider image generation, and automated cropping
remake images measures dimensions, orientation, 5-color palettes, and brightness into remake/images.json; remake images --make generates new visuals via codex, openai, gemini, stock, or art; remake apply writes text, colors, Google Fonts look-alikes, and cropped images into site/.
Phase 06 · Private Passcode Shipping
remake ship [--name] [--passcode] · remake report
Private GitHub repo creation, passcode-gated Vercel deploy, and /goal completion gate
Creates a private GitHub repo and deploys to Vercel behind middleware.js and a noindex header, externally verifying 401 locking and 303 cookie unlocking; remake report checks all gates and prints REMAKE COMPLETE.
remake score & remake report Acceptance Thresholds
When running inside a Claude Code /goal loop, the agent repairs site/ and re-runs verification until every gate below passes:
| Verification Gate | Command | Pass Criteria & Behavior |
|---|---|---|
| Desktop & Phone Static Screens | remake score | Captures up to 40 screens per viewport (1440x900 and 390x844); after excluding the blue noise mask, every screen must match >= 98% of stable pixels. |
| Total Page Height Delta | remake score | Total document height (height.original vs height.remake) must match within 4 px on every scored viewport. |
| Desktop Scrolling Motion | remake score | Captures 24 consecutive scrolling frames (150 ms page-time steps) on the first desktop page; every frame must match >= 95% of stable pixels. |
| Accepted External Exceptions | remake accept | Only allowed after at least 3 repair attempts for unfixable external differences (such as commercial font rendering or cross-origin canvas) when the screen already scores >= 90%. |
| Passcode Gate & Noindex | remake ship | Unauthenticated requests must return HTTP 401 with X-Robots-Tag: noindex; POSTing the passcode to /_remake/gate must return 303 with a remake_pass= cookie and unlock the page. |
| Final Completion Report | remake report | Aggregates capture, score, slots, board, and deployment status; exits with code 0 and prints REMAKE COMPLETE only when all gates pass. |
Advanced Verification & Replacement Tips
The practices below are distilled from docs/HOW-IT-WORKS.md, plugins/remake/skills/remake/SKILL.md, and the engine/lib/ source.
Switch to --archive Mode When Blocked by Bot Walls
Remake never bypasses sign-in screens or bot challenges. If a target site returns 403 or a security challenge, run remake capture --archive (optionally passing a timestamp such as remake capture --archive 20250601) to load historical snapshots from the Internet Archive Wayback Machine.
Read Three-Part Diff Strips in remake/score/ to Diagnose Layout Shifts
Each <page>-<viewport>-<screen>.png generated by remake score shows the original screenshot, the remake screenshot, and the diff overlay (red for pixels differing by more than 24/255, blue for masked noise). If an entire block turns red, check remake/missing.log for missing fonts or CSS backgrounds, or inspect scrollSettleMs for lazy-loaded sections.
Stabilize Dynamic Components with Call-Site RNG Seeds and FNV-1a Replay
Do not strip application scripts when random ordering or API fetches cause visual diffs: freeze.mjs seeds Math.random per filename and line number (default seed: 1337), while runtime.js replays recorded API responses by matching the 32-bit FNV-1a hash of method, URL, and body. Normalize dynamic query timestamps inside site/ so requests hit the recorded cache.
Use Local Codex Authentication First for Zero-Cost Image Generation
When Codex is installed and signed in at ~/.codex/auth.json, running remake images --make --source codex selects a fast model to drive the image tool across all briefed orientations (1536x1024, 1024x1536, or 1024x1024) and look descriptors without requiring a separate paid API key.
Worked Example: Pixel-Accurate Remake & Brand Swap Deployment
This workflow demonstrates how to initialize a remake project for a public showcase site (https://example.com), verify pixel and motion parity, swap all brand copy and imagery, and ship to a passcode-protected Vercel deployment.
Step One: Initialize Workspace, Capture Once, and Fetch Missing Assets
Create the project, run remake capture, and check via remake serve whether any lazy-loaded 404 assets were logged:
# 1. Initialize project (defaults to ~/remakes/example-com, up to 1 page)
remake init https://example.com --pages 1
cd ~/remakes/example-com
# 2. Capture desktop (1440x900) and phone (390x844) in a single visit
remake capture
# 3. Politely fetch any lazy-loaded 404 files recorded in remake/missing.log
remake fetch --missingStep Two: Run Frozen-Time Pixel & Motion Scoring
Run remake score to compare the local remake against the recorded original; if a viewport falls below 98% or motion falls below 95%, re-score that single viewport during iteration:
# Run full dual-viewport screen scoring (>= 98%) and 24-frame desktop motion (>= 95%)
remake score
# Re-test only the phone viewport without motion for fast CSS debugging
remake score --viewport phone --no-motion
# Run full verification once all screens pass
remake scoreStep Three: Extract Content Slots, Generate Brand Images, and Build the Swap Board
Once SCORE: PASS is achieved, extract replaceable slots, measure image palettes, generate new brand visuals, and build the proof and swap boards:
# 1. Parse all text, button, color, font, and image slots into remake/content.json
remake slots
# 2. Measure original image dimensions and 5-color palettes into remake/images.json
remake images --theme "Warm minimalist ceramic studio in Kyoto"
# 3. After writing a prompt for each entry in remake/images.json, generate new images
remake images --make --parallel 3
# 4. After filling swap values in remake/content.json, write text, colors, fonts, and images to site/
remake apply
# 5. Build /_remake/ proof page, /_remake/swap/ swap board, and MAKE-IT-YOURS.md
remake boardStep Four: Ship to Private GitHub & Passcode-Gated Vercel
Run remake ship to relocate reserved Vercel paths, push to a private GitHub repository, configure REMAKE_PASSCODE, and verify the gate from outside, then run remake report:
# Create private GitHub repo and deploy to Vercel behind a passcode gate
remake ship --name remake-example-studio
# Verify all gates; prints REMAKE COMPLETE (exit code 0) when finished
remake reportSafety Boundaries & Limitations
Next Learning Paths
Code Animation Prompts Library: Explore 341 code-driven animation style prompts across 10 series, 196 reference stills, and the
render_video.pyframe-accurate MP4 exporter to build custom motion visuals for your remade hero sections.Huashu Art Motion Library: Browse 53 art style recipe cards, 9 explainer animation grammars, and 17 Canvas/SVG visual libraries rendered with Playwright to expand your brand's visual language after a site remake.
15 Code-Driven MG Animation Styles: Study 15 Claude Opus 5.5 10-second pure-code MG films, the
mgaudio103-sample soundtrack synthesizer, and therubric.mdtwo-round AI review workflow.