Agent swarm build
When you finish building a site, the person sees you build it again, fast and visibly. A swarm of named cursors
(agent-01, agent-02, …) drags out a box for every container, scans each one in, types every heading and paragraph,
pops in the icons and traces the charts. They go screen by screen while the page really scrolls, then sweep back to
the top of the finished page. It is a reveal of the work, and a video people want to share.
Everything is one pure function render(t). The live replay and a frame-by-frame video render are identical, every
frame is deterministic, and the soundtrack can be placed on the build's own events.
How it works, in one paragraph
scripts/agent-build.js is injected into the live site (same origin) by a small replay page,
scripts/replay/index.html. The site runs in a frame with a fixed 1920×1080 viewport, so its layout never depends
on the window it's watched in. The engine lets the page settle (lazy images load, the page is scrolled through once
for reveal-on-scroll content, fonts load, then transitions and CSS animations freeze). It then marks every element
that paints:
- rect: containers, media, buttons and inputs. The box drags out, then a scan line wipes the element in.
- text: a block whose children are all inline. An I-beam types it, line by line.
- pop: icons, avatars and badges. They pop in.
- path: the longest stroked line of an SVG chart. A pencil traces it.
It packs the page into screens and plans the swarm: 10 to 48 agents, scaled to the page, with a pace solved to a target length. A child starts as soon as its parent's scan line has passed it.
Running it after a build
-
Find the static folder the site's server serves unchanged. That's
public/for Vite, Next.js, Astro, Remix and CRA,static/for SvelteKit, or the folder holdingindex.htmlfor a plain site. A plain site with no dev server is served withnode <skill>/scripts/serve.mjs <dir> [port]. -
Install the replay:
node <skill>/scripts/make-replay.mjs <static-dir> --title "Site name" --wall hillsIt writes
<static-dir>/__replay/and prints the path to open, e.g./__replay/?src=%2F&title=…&wall=hills. Point--srcat another route to build that page.- Wallpapers:
violet(abstract ribbons),alpine(lake at dawn),sage(soft folds),hills(green hills, sky) anddunes(golden-hour desert). - Pick one that suits the site. Use a different one for each video when someone makes several.
- Wallpapers:
-
Open it for them: start the dev server and open the printed path.
- If you have a browser pane (the Claude desktop app), start the server with
preview_startandnavigateto the replay URL. It can't openfile://pages or a server you start from the shell yourself. - Without a browser, give them the full URL to open, along with the contact sheet from step 4.
The cover ("the agents are getting ready…") stays up while the page settles, then the swarm plays. Space or R restarts it.
- If you have a browser pane (the Claude desktop app), start the server with
-
Check it before telling them it's ready:
node <skill>/scripts/stills.mjs "http://localhost:<port>/__replay/?src=%2F&title=…" <out-dir> autoThis headless capture works anywhere. It prints
__build(elements, agents, screens, pace) and any page errors, then writes six stills across the build pluscontact.png. Look at the sheet:- the first still should show the page mid-build;
- the last should be the finished site;
- nothing should be visible before its agent arrives.
If something looks wrong, see "When the automatic marks are wrong" below. Show them the contact sheet or a still along with the link, so they can see the swarm without opening it.
-
Tell them where it lives.
__replay/sits in a folder that deploys with the site, so suggest adding it to.gitignore, or delete it when they're done.
When __build.pace reports 0.3, the build is running at its fastest. The page has more to build than the target
allows, so the replay runs over. That's usually fine for a live replay. Don't push the pace further; a frantic swarm
reads worse than a longer one. If length matters, compress it in the video with the renderer's knots (a timelapse,
below). Use maxItems (fewer, grouped boxes) or a later src route only when the page itself is too busy.
Settings (URL parameters, or make-replay.mjs flags)
| Parameter | Default | What it does |
|---|---|---|
src | / | the route to build (same origin) |
title | — | the window title, usually the site's name |
wall | hills | the wallpaper; none for plain dark |
frame | window | bare drops the window, so the site fills the 16:9 stage |
target | 18 | seconds the build aims for; it's never faster than 3.3× natural, so long pages run over |
agents | auto | the number of agents: 10 for a small page, up to 48 for a swarm with smaller cursors |
ending | top | top sweeps back up to the finished hero; hold stays at the bottom |
accent | #4B89FF | the colour of boxes, scan lines and labels; use the brand colour when it reads well on the site |
vw, vh | 1920, 1080 | the site's viewport, e.g. vw=1440&vh=900 for a laptop-sized layout |
mark | — | 1 loads __replay/mark.js for hand-marking (below) |
Making a video of it
Render it when they want something to share, or when you were asked for a video. Plan for about 15–18 s for social.
- Picture: compress long builds with the renderer's knots. They retime smoothly, as a timelapse, without cutting anything.
- Sound: comes from the bundled Higgsfield library (
assets/sfx/) over a synthesized music bed.
# 1. frames → muted MP4 (exactly 60/1, no B-frames); saves <name>.cues.json beside it
node <skill>/scripts/render-video.mjs "http://localhost:3000/__replay/?src=%2F&title=Acme&wall=hills" \
acme-build-18s-silent.mp4 18 60 /tmp/chrome-render '[[0,0],[18,<__LOOP>]]'
# 2. score from the cues, master to −16 LUFS, mux
node <skill>/scripts/mix-audio.mjs acme-build-18s-silent.cues.json <skill>/assets/sfx acme-build-18s.wav \
--knots '[[0,0],[18,<__LOOP>]]' --video acme-build-18s-silent.mp4 --out acme-build-18s.mp4
- Length: read
__LOOPfrom the page first. Use[[0,0],[L,L]]for real speed. Keep typing-heavy openings closer to real speed with an extra knot. - Before delivering, check that
ffprobeshowsr_frame_rate=60/1andavg_frame_rate=60/1, the length is exact, and there's an audio stream. Look at six frames and check one sound against its frame. - Deliver the video with sound and the silent copy, named by length.
- Details, flags and why they matter:
references/video-and-sound.md.
When the automatic marks are wrong
Automatic marking classifies by what each element paints, so it works on any stack. If a replay looks off, read
references/engine.md. The usual fixes:
- A giant wrapper gets a box you don't want. It paints a background or border. Hand-mark it instead.
- A page has hundreds of tiny items and feels noisy. Lower
maxItems, which folds busy subtrees into group boxes, or hand-mark groups. - Something stays visible from the first frame. It paints in a way the engine doesn't see, such as a pseudo-element on an unmarked parent or a fixed overlay. Mark it.
For hand-marking, write __replay/mark.js and open the replay with &mark=1:
window.__agentBuildMark = ({ A, wrap, $, $$, autoMark }) => {
autoMark(); // start from the automatic marks, then adjust…
$$('.hero, .pricing-grid').forEach(e => A(e, 'rect', 'Section'));
A($('.logo'), 'pop'); // A(el, 'rect'|'text'|'pop'|'path', label?) · wrap(el) splits mixed text
};
WebGL and 3D sites
A canvas is built as one "Scene" box, so the standard replay works on any site. For a 3D world the stronger version
builds the scene itself: objects appear as wireframe, resolve to solid and are placed just ahead of the camera, with
the swarm working on screen-projected boxes. That needs hooks in the site's own engine and a virtual clock. Read
references/webgl-swarm.md; it has two worked examples (a paper-plane flight and a jewellery film).
Presenting a piece that already animates itself
If a page already defines window.__render(t) and window.__LOOP (a build study, a motion piece), don't rebuild it.
Wrap it in the window and wallpaper and render it. See references/presenting.md, which also covers the chat-tool
shell, where a prompt is typed and the build plays in a preview pane.
Things that went wrong before, and why the scripts do what they do
- Window-dependent layout. A site laid out against the real window switched to its narrow breakpoint (one-column pricing) while the measurements came from the wide one, so the cursors drew boxes over empty space. That's why the site always runs in a fixed 1920×1080 frame, and nothing is measured against the browser window.
- Hidden frames hang. A frame hidden with
opacity:0gets no animation frames, so a page waiting onrequestAnimationFramenever loads. The replay covers the frame instead of hiding it. - Frame rate. B-frames left a 2-frame edit-list offset that one upload checker read as 60.1 fps and refused.
render-video.mjsencodes with-bf 0and a 60000 timescale, andmix-audio.mjskeeps the video stream untouched. - Same origin. The replay must be served by the site's own server. A cross-origin or
file://frame can't be scripted, and the replay says so on its cover. - Credits. The sound effects were generated once with Higgsfield and are bundled. Generating new ones costs credits (about 0.7 each), so ask first.