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 press Cmd+Y on macOS or Ctrl+Shift+Y on Linux (Play Last Recording in 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.