This skill should be used when the user names Charmbracelet VHS, asks to use the `vhs` CLI, wants a terminal recording, terminal GIF, terminal MP4/WebM, `.tape` file, scripted terminal demo, or a reproducible command-line screencast. Do NOT use for generic browser recording, full desktop screen capture, or unscripted secret-bearing interactive sessions.
This skill should be used when the user names Charmbracelet VHS, asks to use the `vhs` CLI, wants a terminal recording, terminal GIF, terminal MP4/WebM, `.tape` file, scripted terminal demo, or a reproducible command-line screencast. Do NOT use for generic browser recording, full desktop screen capture, or unscripted secret-bearing interactive sessions.
version
0.1.0
author
Trevin Chow
license
MIT
metadata
{"hermes":{"tags":["terminal","recording","vhs","charmbracelet","screencast","gif","mp4","webm","cli"],"category":"media","requires_toolsets":["terminal"]},"openclaw":{"emoji":"📼","homepage":"https://github.com/charmbracelet/vhs","requires":{"bins":["vhs","ttyd","ffmpeg"]},"install":[{"id":"homebrew","kind":"brew","formula":"vhs","bins":["vhs","ttyd","ffmpeg"],"label":"Install VHS with Homebrew"}]}}
VHS Terminal Recorder
When to use
Use this skill only when vhs or Charmbracelet VHS is actually the right surface:
user says vhs, Charmbracelet VHS, , terminal GIF, terminal recording, command-line screencast, or scripted terminal demo
.tape
docs need a reproducible recording of CLI behavior
an existing VHS tape needs authoring, validation, rendering, or debugging
Do not use it for arbitrary desktop capture, browser product tours, video editing, or one-off interactive work that cannot be made deterministic. Use a video/screen-capture workflow instead when the subject is not a terminal.
Mental model
VHS runs a tape file in a pseudo-terminal and renders the terminal session to GIF, MP4, or WebM. Treat a tape like a small executable test:
the tape must create or point at deterministic state
commands shown to viewers should be short and intentional
setup belongs behind Hide / Show
vhs validate checks tape syntax but does not prove the commands work
vhs <file> executes the tape and can mutate files, hit the network, or run project commands
This skill is not the VHS language reference. For exact syntax, generate or inspect live docs:
vhs --help
vhs manual
vhs new /tmp/example.tape
vhs validate /tmp/example.tape
vhs record --help
vhs validate --help
vhs publish --help
Rendering also depends on the local VHS render stack, especially ttyd and ffmpeg. If vhs validate passes but rendering fails before running the tape, check those binaries before changing tape logic.
If vhs is missing and the user wants it installed, prefer the upstream-supported package manager for the current machine. The common macOS/Linux path is:
brew install vhs
For Windows, Arch, Nix, Docker, Debian/RPM packages, or Go source installs, use the upstream installation section instead of copying commands from memory: https://github.com/charmbracelet/vhs#installation
First render can be slow because VHS may initialize browser/rendering caches. Do not misdiagnose that as a bad tape until validation passes and the render actually fails.
Authoring rules
Start from a hand-written tape for agent-created demos. Use vhs record only as a rough draft, then clean the tape before committing it.
Keep tapes deterministic:
keep Output, Require, and most Set commands at the top of the tape before visible actions; VHS docs call out top-of-file ordering for dependencies and settings
set Output, Set Shell, Set Width, Set Height, Set FontSize, Set TypingSpeed, and Set Theme explicitly
add Require <program> for every external command the tape depends on
create fixtures or temp files in hidden setup instead of relying on the user's current shell state
prefer fake/sample values over real accounts, tokens, private paths, or production URLs
constrain noisy commands with flags, known fixtures, or small output windows
keep Type lines simple; put complex setup in a script or separate hidden commands instead of relying on nested quotes or command substitution
use Wait+Screen@<timeout> /pattern/ or Wait@<timeout> /prompt-or-line/ for readiness; reserve Sleep for presentation timing after readiness has happened
when waiting on a server, file watcher, or network dependency, prefer a hidden shell readiness loop or a visible command followed by a VHS Wait+Screen; do not rely on a bare fixed sleep
Minimal skeleton:
Output demo.gif
Require bash
Require your-cli
Set Shell "bash"
Set Width 1200
Set Height 700
Set FontSize 28
Set Theme "Builtin Dark"
Hide
Type "mkdir -p /tmp/vhs-demo && cd /tmp/vhs-demo"
Enter
Type "your-cli init --fixture small >/dev/null"
Enter
Show
Type "your-cli status"
Enter
Wait+Screen@5s /ready|ok|complete/
Sleep 1s
Best-practice scenarios
Create a docs GIF. Author a tape beside the docs or examples it supports, use a small deterministic fixture, validate it, render it, then inspect the output file before reporting success:
vhs validate docs/demo.tape
vhs docs/demo.tape
Render another format. Prefer GIF for lightweight README embeds. Use MP4 or WebM when quality or file size matters:
Output demo.mp4
Output demo.webm
Use Output frames/ for a PNG sequence when post-processing is needed. Use text outputs such as Output golden.ascii only for integration-test/golden-file workflows, not as the normal docs artifact.
Choose a theme. Do not guess theme names from memory. List them and copy the theme string exactly:
vhs themes
vhs themes --markdown
Validate several tapes. Quote globs so the shell does not expand or reject them before VHS sees the pattern, especially in zsh:
vhs validate 'docs/*.tape'
Debug a failing tape. Validate first. If validation passes, run each viewer-facing command directly in a clean shell or temp directory. Most VHS failures are ordinary command failures hidden inside a recording.
Use recording mode. Reach for vhs record only to capture an exploratory interaction or learn a rough sequence. Rewrite the result into a short scripted tape with hidden setup, explicit dimensions, and no accidental local state.
Safety and publishing
Rendering executes the tape. Read untrusted tapes before running them.
Never capture or publish secrets. Before rendering or committing, scan the tape for tokens, real customer data, private paths, .env output, shell history, git remotes, and account-specific prompts.
Publishing uploads a GIF to vhs.charm.sh. Treat it as an external side effect: only run vhs publish <file>.gif or vhs <file> --publish when the user has explicitly approved that exact file for public sharing.
Pitfalls
vhs validate is parse-only; it does not run Require checks or prove the demo commands succeed.
Unquoted globs can fail in the shell before VHS runs.
Long command output makes unreadable recordings. Shrink the scenario instead of increasing terminal height until everything fits.
Nested quoting and shell command substitution inside Type lines can produce confusing parse errors. Simplify the line or move setup into a small script.
Plain Wait /pattern/ watches the current line. Use Wait+Screen /pattern/ when matching command output anywhere on the terminal.
VHS supports useful commands beyond the common demo path, including Screenshot, Source, Copy, Paste, and version-dependent Env; check vhs manual before using them, and never use Env as a way to smuggle real secrets into recordings.
Default shell, prompt, theme, size, and font can vary by machine. Set the recording surface explicitly.
Sleep hides races in the final video. Use hidden readiness checks for anything that depends on a server, file watcher, background job, or network.
Do not commit generated videos unless the repo expects binary demo assets. If unsure, ask before adding large GIF/MP4/WebM files to version control.
