| name | terminal-recording |
| description | Record a terminal session with asciinema and turn it into a GIF with agg or an MP4 with ffmpeg. Covers the asciicast format defaults, recording from inside the claudex sandbox, and the flags an MP4 needs to come out reproducible. Use when capturing a terminal session as an animated asset for a deck, a README, a blog entry or an issue. For wiring the result into a Marp deck, see `.claude/reference/slides/terminal-recording.md`. |
| keywords | asciinema, asciicast, .cast, gifski, ffmpeg, 録画, ターミナル録画, スクリーンキャスト |
- Record the
.cast under /tmp rather than into the working tree - it is a throwaway the GIF beside it already carries, agg reads it from anywhere, and no .gitignore in this repository covers *.cast, so one left behind shows up as untracked in every later git status
Pipeline
asciinema rec /tmp/demo.cast
agg /tmp/demo.cast demo.gif
asciinema writes asciicast-v3 whatever the file is named, and only a path ending in .txt selects another format.
End the session with <ctrl+d> or exit, and pause capture with <ctrl+\>.
agg reads the asciicast and encodes through gifski, so no intermediate step is needed.
asciinema refuses to overwrite an existing file, so re-recording over the same path needs --overwrite.
Recording From Inside the Sandbox
Use the same pipeline as above - the sandbox writes both /tmp and the working tree, but PrivateTmp=yes gives it a /tmp of its own, so only a GIF written into the working tree outlives the session.
Only what -c runs gets captured and the sandbox has no controlling terminal, so a session worth watching because someone is typing through it cannot be produced this way - drive an interactive recording from a real terminal on the host instead.
That same absent terminal leaves the geometry at 80x24 unless --window-size COLSxROWS sets one, and --cols and --rows are accepted in silence without setting anything.
MP4
A GIF of a long session grows fast, and base64-encoding it into an HTML page adds about a third on top.
Convert to MP4 when that matters:
ffmpeg -i demo.gif -vf "scale=trunc(iw/2)*2:trunc(ih/2)*2" -map_metadata -1 -fflags +bitexact -flags:v +bitexact -movflags +faststart -pix_fmt yuv420p demo.mp4
The scale filter is not optional.
libx264 rejects an odd width or height outright (width not divisible by 2), and a terminal geometry lands on one often enough to matter.
The -map_metadata and bitexact flags drop the container's encoder tag and the comment gifski leaves behind, and cut the stream's encoder tag down to Lavc libx264.
handler_name, language and the SEI string carrying the libx264 build id and its encoding options survive them, so an MP4 never comes out as clean as a stripped GIF.
Reference
If putting the result into a Marp deck:
Read: .claude/reference/slides/terminal-recording.md
