| name | freeze-capture |
| description | Capture terminal output or code as a static image (PNG/SVG/WebP) using charmbracelet/freeze. Use for proof-of-work screenshots when an agent finishes a task ("here's the green test run"), or for polished CLI/TUI demo stills for blog posts/social. NOT for animated demos — use terminal-demo-recorder (VHS) for those. Triggers on "freeze", "screenshot the output", "capture this command", "proof of work image", "make an image of", "snapshot the terminal". |
Freeze Capture
Static image of terminal output or code file. Two modes, same tool.
Decide mode first
| Goal | Mode | Output |
|---|
| Agent prove task worked (test passed, build succeeded, command ran) | proof | PNG, plain, no chrome |
| Demo for blog/social/README | demo | PNG/SVG, window chrome, theme, shadow |
| Code snippet from file (no execution) | code | SVG, syntax-highlighted |
Proof-of-work (default for agents)
Goal: cheap, readable image showing command + output. Drop in task folder.
freeze --execute "<COMMAND>" \
--output ".ai/$(date +%Y-%m-%d)/proof/<descriptive-name>.png" \
--width 120 \
--padding 20 \
--background "#1e1e2e" \
--theme "catppuccin-mocha"
Rules:
- Path:
.ai/YYYY-MM-DD/proof/ — create dir if missing.
- Name: describe what's proven (
pnpm-test-pass.png, nx-affected-build.png). No timestamps in name (date already in path).
- Width 120 cols handles most CLI output without wrapping. Bump to 160 for wide tables.
- PNG, not SVG — proof images get embedded in PR descriptions / pasted into Slack. PNG renders everywhere.
- If command exits non-zero, still capture it. Failure proof is also proof.
- Reference the file path back to the user so they can open it.
Example flow when agent wraps task:
mkdir -p .ai/$(date +%Y-%m-%d)/proof
freeze --execute "nx test my-lib" -o .ai/$(date +%Y-%m-%d)/proof/my-lib-test.png -W 140 -p 20
Demo (CLI/TUI showcase)
Goal: polished image for README, blog, X post. Window chrome on, shadow, generous padding.
freeze --execute "<COMMAND>" \
--output demo.png \
--window \
--background "#0b0b1a" \
--theme "dracula" \
--padding 40,60 \
--margin 30 \
--border.radius 8 \
--shadow.blur 20 --shadow.x 0 --shadow.y 10 \
--font.family "JetBrains Mono" --font.size 16
Tune:
- Bigger font (16-20) for social where image gets downsized.
--width and --height to enforce 16:9 or square aspect for X/LinkedIn.- Strip ANSI cursor codes if TUI leaves artifacts: pipe through
sed -r "s/\x1B\[[0-9;]*[a-zA-Z]//g" before capture, or use script for full PTY.
Code-from-file
freeze src/lib/foo.ts --output foo.svg --window --show-line-numbers --theme dracula
freeze src/lib/foo.ts --output foo.png --lines 12,40
SVG preferred for code — scales crisp, embeds in docs.
Caveats
- TUI capture is finicky. Programs that redraw (htop, vim, nx graph) won't render their final state via
--execute. For TUIs use VHS (terminal-demo-recorder skill) instead.
- PNG file size: a 120-col x ~30-row capture is ~5-8 MB at default settings. Drop
--font.size to 12 or use SVG to shrink.
- Color: freeze respects ANSI in
--execute output. If a CLI suppresses color when stdout isn't a TTY, force it (FORCE_COLOR=1, --color always, etc.) before piping into --execute.
- No animation. Single frame only. If user asks for "a recording" or "GIF", redirect to terminal-demo-recorder.
- Exit code is preserved by
--execute — image still produced.
After capture
- Print the absolute path of the output file so the user can open it.
- Bump
~/projects/dot-ai-config/USAGE.md row for freeze-capture (date + count).
More flags
See references/flags.md for the full list and references/recipes.md for copy-paste presets.
