Charmbracelet VHS Best Practices

Comprehensive best practices guide for VHS terminal recordings, maintained by Charmbracelet. Contains 47 rules across 8 categories, prioritized by impact to guide creation of professional, portable, and optimized terminal demos.

When to Apply

Reference these guidelines when:

• Writing new VHS tape files
• Creating terminal demos for documentation
• Setting up CI/CD for automated GIF generation
• Optimizing recording file size and quality
• Troubleshooting tape file issues
• Reviewing tape files for best practices

Rule Categories by Priority

Quick Reference

1. Configuration Structure (CRITICAL)

• [config-settings-order](references/config-settings-order.md) - Place all settings before commands
• [config-output-first](references/config-output-first.md) - Declare output at file start
• [config-shell-explicit](references/config-shell-explicit.md) - Explicitly set shell type
• [config-typing-speed-global](references/config-typing-speed-global.md) - Set global TypingSpeed early
• [config-dimensions-explicit](references/config-dimensions-explicit.md) - Set explicit terminal dimensions
• [config-comments-document](references/config-comments-document.md) - Use comments to document tape structure

2. Dependency Management (CRITICAL)

• [deps-require-early](references/deps-require-early.md) - Use Require for dependency validation
• [deps-require-order](references/deps-require-order.md) - Place Require before settings
• [deps-require-all](references/deps-require-all.md) - Require all external commands
• [deps-system-requirements](references/deps-system-requirements.md) - Verify system dependencies

3. Command Syntax (HIGH)

• [cmd-type-syntax](references/cmd-type-syntax.md) - Use correct Type command syntax
• [cmd-enter-explicit](references/cmd-enter-explicit.md) - Always follow Type with Enter
• [cmd-key-repeat](references/cmd-key-repeat.md) - Use key repeat counts
• [cmd-ctrl-combinations](references/cmd-ctrl-combinations.md) - Use Ctrl combinations for terminal control
• [cmd-hide-show](references/cmd-hide-show.md) - Use Hide/Show for sensitive operations
• [cmd-env-variables](references/cmd-env-variables.md) - Use Env for environment variables
• [cmd-screenshot](references/cmd-screenshot.md) - Use Screenshot for static captures
• [cmd-multiline-type](references/cmd-multiline-type.md) - Handle multiline commands properly

4. Timing & Synchronization (HIGH)

• [timing-sleep-after-enter](references/timing-sleep-after-enter.md) - Add Sleep after commands for output
• [timing-wait-pattern](references/timing-wait-pattern.md) - Use Wait for dynamic command completion
• [timing-type-speed-override](references/timing-type-speed-override.md) - Override TypingSpeed for emphasis
• [timing-sleep-units](references/timing-sleep-units.md) - Use explicit time units
• [timing-final-sleep](references/timing-final-sleep.md) - End recordings with final Sleep
• [timing-natural-pauses](references/timing-natural-pauses.md) - Add natural pauses between actions
• [timing-wait-timeout](references/timing-wait-timeout.md) - Set appropriate Wait timeouts
• [timing-playback-speed](references/timing-playback-speed.md) - Use PlaybackSpeed for final adjustments

5. Output Optimization (MEDIUM-HIGH)

• [output-format-selection](references/output-format-selection.md) - Choose output format based on use case
• [output-framerate](references/output-framerate.md) - Optimize framerate for file size
• [output-dimensions-optimize](references/output-dimensions-optimize.md) - Right-size terminal dimensions
• [output-loop-offset](references/output-loop-offset.md) - Use LoopOffset for seamless loops
• [output-multiple-formats](references/output-multiple-formats.md) - Generate multiple output formats
• [output-relative-paths](references/output-relative-paths.md) - Use relative paths for portability

6. Visual Quality (MEDIUM)

• [visual-font-readable](references/visual-font-readable.md) - Choose readable font settings
• [visual-theme-selection](references/visual-theme-selection.md) - Select appropriate theme
• [visual-window-decoration](references/visual-window-decoration.md) - Add window decorations for polish
• [visual-spacing](references/visual-spacing.md) - Adjust letter and line spacing
• [visual-padding-margin](references/visual-padding-margin.md) - Use padding and margins effectively
• [visual-cursor-visibility](references/visual-cursor-visibility.md) - Ensure cursor visibility

7. CI/Automation (MEDIUM)

• [ci-github-action](references/ci-github-action.md) - Use official VHS GitHub Action
• [ci-auto-commit](references/ci-auto-commit.md) - Auto-commit generated assets
• [ci-golden-files](references/ci-golden-files.md) - Use golden files for integration testing
• [ci-matrix-builds](references/ci-matrix-builds.md) - Generate platform-specific demos
• [ci-caching](references/ci-caching.md) - Cache VHS dependencies in CI

8. Advanced Patterns (LOW)

• [advanced-source-include](references/advanced-source-include.md) - Use Source for reusable tape components
• [advanced-clipboard](references/advanced-clipboard.md) - Use Copy and Paste for complex input
• [advanced-recording-live](references/advanced-recording-live.md) - Record live sessions then edit
• [advanced-server-mode](references/advanced-server-mode.md) - Use server mode for remote access

How to Use

Read individual reference files for detailed explanations and code examples:

• [Section definitions](references/_sections.md) - Category structure and impact levels
• [Rule template](assets/templates/_template.md) - Template for adding new rules

Reference Files