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.

Play it back

.cast has no default handler on any operating system, so a recording you double-click normally does nothing. toowl plays its own recordings — no asciinema required:

toowl play session.cast

It opens in a new tab with a transport strip along the bottom: play/pause, elapsed time, a scrub bar, and a speed control. Space toggles play, ←/→ jump five seconds, [/] jump thirty, s toggles idle-skipping, and . cycles the speed. Dead air longer than two seconds is skipped by default — a recording of real work is mostly waiting.

You can also drag a .cast onto a toowl window, double-click one in Finder, or run Play Last Recording from the palette to replay whatever you just recorded. The replay is an ordinary pane, so selection, search and scrollback all work on it; it is pinned to the size the recording was made at, so nothing reflows.

Send one to someone without toowl

Export a single self-contained HTML file — the frames and a small player, inlined. No network, no dependencies, opens in any browser:

toowl play session.cast --export-html
# -> session.html

The page is rendered through toowl's own terminal parser at export time, so what it shows is exactly what toowl would draw — colours, bold, everything — and there is no terminal emulator running in the browser to disagree with it. Frames carry only the rows that changed, so a typical recording exports to a handful of kilobytes.

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.