Terminal demo gif

Terminal Demo GIF

Create README-ready terminal demo GIFs from command-line material. The output should be visually polished while remaining honest about its source.

Workflow

1. Gather source material.

   • If the user wants a real command demo, run commands in a safe scratch directory and capture stdout/stderr.
   • If the user provides logs or terminal text, use that transcript directly.
   • If the user wants README assets, copy final media into a stable repo asset directory such as assets/<demo-name>/.

2. Preserve evidence.

   • Save the cleaned transcript as terminal-transcript.txt.
   • Save raw logs when commands were actually run.
   • Save a small verification.json when there are pass/fail claims, important result markers, or source distinctions to preserve.

3. Render the demo.

   • Use scripts/render_demo.sh to gate the environment, install local dependencies, and generate a GIF and PNG cover from the transcript.
   • Before first use or after changing renderer/assets, run scripts/selftest.sh so dependency setup and both supported render styles are verified by script.
   • Prefer concise transcript text; long paths and raw JSON should be summarized before rendering while raw logs stay available beside the media.
   • Use a clear title and subtitle describing the workflow.
   • Use --claude-simulated-status only for clearly labeled simulated Claude Code demos. Do not add synthetic status metadata to real command transcripts.

4. Review the generated GIF and PNG before delivery.

   • Treat GIF/PNG review as a required delivery gate, not an optional polish pass.
   • Verify both output files exist, open successfully, and have the expected format, dimensions, frame count, and nonblank pixels.
   • Visually inspect the PNG cover and the GIF/final animated state when possible. Check that text is readable, important commands/results are visible, colors are legible, and there is no awkward wrapping, clipping, overlap, or blank/mostly empty frame.
   • Spawn a subagent for an independent review whenever the environment supports subagents and the user has not explicitly forbidden delegation. Ask it to inspect the generated GIF/PNG, transcript, provenance notes, README-facing paths, and stable workflow risks. Incorporate or explain its findings before final delivery.
   • If the output is README-facing, regenerate the tracked assets through scripts/render_demo.sh and run scripts/selftest.sh so stale GIF/PNG files are caught before delivery.
   • Iterate on transcript length, title/subtitle, font size, or render style until the image is clear enough for a public README.

5. Describe provenance clearly.

   • Say "generated from real transcript/logs" when rendering from captured output.
   • Say "generated from provided terminal text" when the user supplied the transcript.
   • Say "simulated transcript" when illustrative terminal text or simulated Claude Code status metadata is used.
   • Do not call a generated terminal animation a screen recording unless an actual screen recorder was used.

Renderer

Run:

bash scripts/render_demo.sh \
  --transcript /path/to/terminal-transcript.txt \
  --out-dir /path/to/assets/demo-name \
  --name demo-name \
  --title "CLI demo" \
  --subtitle "generated from real logs"

Outputs:

• <name>.gif
• <name>.png

Useful options:

• --width 1280 --height 720
• --font-size 20
• --footer "Generated from terminal transcript."
• --claude-simulated-status for clearly labeled simulated Claude Code demos only

Transcript Style

Use a simple line-oriented transcript:

# project demo
$ command --flag
important output
result: OK

Rendering colors are inferred from line prefixes:

• # for title/context lines
• $ for commands
• prompt: and constraint: for explanatory lines
• result:, child result:, OK, PASS, success for success lines
• error, failed, FAIL for failure lines

Keep the animated transcript short enough to fit on screen. Put detailed evidence in raw logs, not in the GIF.