demo-recording
Skill34 starsChanged 6 months agoMITView on GitHub
Use when recording, updating, or troubleshooting the hero demo GIF in `demo/`. Covers the full pipeline (asciinema -> Playwright -> GIF), font/rendering issues, and editing the simulated Claude Code sessions.
- Installs packages
5 other projects use a version of this.
Adopted by
Most recently taken up by
- SamRome1/devrel-skillstheir own version, first seen Nov 8, 2026
- ai-ecoverse/slicctheir own version, first seen Nov 1, 2026
- product-llc/claude-skillstheir own version, first seen Oct 8, 2026
- masonhuemmer/dopstheir own version, first seen Mar 24, 2026
- rundops/dopstheir own version, first seen Mar 24, 2026
Other versions5 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 5
- ai-ecoverse/slicc★ 37same name
- masonhuemmer/dops★ 3same name
- rundops/dops★ 3same name
- SamRome1/devrel-skills★ 1same name
- product-llc/claude-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository4 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- amux-pr-workflowSkill
- amuxSkill
The file
We split this skill into the rules it gives an agent
3 rules. 0 are common, 1 is distinctive, and 2 are very specific to this project.
0
Common
Most of the 5 edited versions we read keep these.
1
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 50
All tuning flags are in record.sh and passed to cast2gif.mjs:
- Distinctive: line 75
Verify the GIF renders the Claude Code logo and tool indicators correctly before committing.
- Very specific: line 76
Use absolute paths in record.sh — relative paths break when the working directory differs.
“Common” is measured: kept by at least 6 in 10 of the 5 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Demo Recording
Quick Start
bash demo/record.sh # records + converts to GIF in one commandFirst run installs Playwright automatically (cd demo && npm install && npx playwright install chromium).
Dependencies: brew install asciinema ffmpeg node jq. The amux binary must be on $PATH.
Architecture
asciinema rec -> .cast file -> cast2gif.mjs (Playwright) -> hero.gifcast2gif.mjs loads the .cast file in asciinema-player inside headless Chromium, screenshots at 1/fps intervals, and assembles frames into a GIF with ffmpeg.
Why Playwright instead of agg
agg (asciinema's official GIF generator) cannot render block element characters (the Claude Code logo), uncommon symbols, or font fallback. The browser's text rendering engine handles all of these correctly.
Why asciinema v2 format
The converter supports both v2 and v3, but v2 absolute timestamps are easier to inspect manually. Record with --output-format asciicast-v2.
Why real-time playback (not seek)
asciinema-player.seek() does not render terminal state -- it produces blank frames. The converter plays at 1x speed and screenshots at intervals, so conversion takes as long as the recording (~20s).
How driver.sh Works
The driver runs inside asciinema's recorded PTY with a foreground/background split:
- Background agent waits for the amux server socket, then drives the demo via
amuxCLI commands (spawn, split, send-keys, wait idle, capture) - Foreground amux client renders the TUI into the PTY that asciinema records
- Agent kills the client (via saved PID) to end the recording
Each Claude pane uses a fake claude.sh that shows the startup banner and blocks on read. The agent then sends prompts via amux send-keys so text appears naturally at the prompt. When read completes, a per-pane response script (resp-server.sh, resp-tests.sh, resp-review.sh) simulates Claude Code tool use output with printf + sleep.
Tuning the GIF
All tuning flags are in record.sh and passed to cast2gif.mjs:
--font "Menlo" # Font family (browser must have it installed)
--font-size 20 # CSS pixels
--scale 2 # Device pixel ratio (2 = retina)
--window-size 160x40 # cols x rows for the recorded terminal
--fps 8 # Frames per second (lower = smaller file, choppier)Font matters for block elements. JetBrains Mono and Fira Code render block characters too narrow. Menlo has better proportions. No browser font perfectly matches terminal emulators, which draw block elements programmatically.
File size target: < 1MB for README. Current output is ~700KB at 2x scale.
Editing the Demo Content
- Response scripts: Edit
write_sim_scripts()indriver.sh-- each pane has a response script (resp-server.sh,resp-tests.sh,resp-review.sh). - Prompts: Edit the Phase 2
send-keyscalls in theagent()function. - Pane layout: The
agent()function usesspawn,focus && split v, andfocus && split root. Note thatsplit rootcan rearrange the layout tree, moving panes out of vertical splits and breakingminimize. - Utility pane: The rightmost pane content comes from the inline
send-keyscommand inagent()(line ~178). Thedevlog.shreference on line ~165 is a no-op (the file is not created). To refactor, add adevlog.shtowrite_sim_scripts()and remove the inline send-keys block.
Rules
- GIF must be under 1MB for README rendering performance.
- Clean up
.castintermediate files after conversion. - Verify the GIF renders the Claude Code logo and tool indicators correctly before committing.
- Use absolute paths in
record.sh— relative paths break when the working directory differs.
Output Checklist
demo/hero.gifgenerated and under 1MB.- No
.castintermediate files left behind. - GIF animates correctly (check key frames: startup banners, claude responses, JSON capture).
README.mdreferencesdemo/hero.gifand renders inline on GitHub.
Troubleshooting
Blank GIF frames -- asciinema-player did not load (CDN unreachable or font timeout). Increase the font-loading wait in cast2gif.mjs.
Unicode renders as boxes or [?] -- Using agg instead of Playwright, or the browser lacks the font. Use cast2gif.mjs and install Noto Sans Symbols 2 if needed.
Logo looks "smooshed" -- Font renders block elements with narrow proportions. Switch to Menlo or increase font-size.
"amux server socket not found" -- amux binary not on PATH. Run go build -o ~/.local/bin/amux . and ensure ~/.local/bin is in PATH.
Recording only captures 1-2 events -- Wrong path to driver.sh. record.sh uses ${SCRIPT_DIR}/driver.sh (absolute path).
"cannot minimize: pane is not in a vertical split" -- A split root rearranged the layout. Reorder splits so vertical splits happen after root splits, or skip minimize.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

