Session recording

Toowl can record the focused pane's output to an asciinema cast v2 file. The result is a plain .cast that plays back anywhere the asciinema ecosystem reaches — asciinema play recording.cast in a terminal, or uploaded to asciinema.org to share a link. No conversion, no proprietary format.

Start & stop

• Press Cmd+Opt+R (macOS) / Ctrl+Alt+R (Linux, Windows). Shift+R is deliberately left to roost_active_pane, so recording takes the Alt variant rather than shadowing it.
• Or use the ≡ menu in the tab strip — it reads Start Recording / Stop Recording depending on the focused pane.
• Or the command palette (Cmd+Shift+P / Ctrl+Shift+P) → Toggle recording (toggle_recording).
• A red dot appears on the tab while a recording is live.
• A toast confirms start, and stop — reporting the elapsed time and file size.

Where recordings land

Configure the output folder in the [recording] section of ~/.config/toowl/config.toml:

[recording]
# Defaults to ~/Desktop. "~" is expanded at record time.
# Set empty ("") to fall back to <data_dir>/toowl/recordings
# (e.g. ~/.local/share/toowl/recordings on Linux).
dir = "~/Desktop"

The folder is also editable from Settings (Cmd+, / Ctrl+,) — focus the Recording folder row and press Enter to edit it inline. Changes take effect on the next recording; one already in flight keeps writing to where it started.

Turn a recording into a GIF or video

A .cast is a timed text log, not pixels, so it stays tiny and stays greppable. When you need something to drop into a README or a chat, render it with agg:

# GIF, straight from the cast
agg session.cast session.gif

# Smaller: cap the idle gaps and the frame rate
agg --idle-time-limit 2 --fps-cap 15 session.cast session.gif

# MP4 (agg renders frames, ffmpeg encodes)
agg session.cast session.gif
ffmpeg -i session.gif -movflags faststart -pix_fmt yuv420p \
  -vf "scale=trunc(iw/2)*2:trunc(ih/2)*2" session.mp4

Or skip the file entirely: asciinema upload session.cast gives you a shareable link with selectable text.