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 - Place all settings before commands
• •config-output-first - Declare output at file start
• •config-shell-explicit - Explicitly set shell type
• •config-typing-speed-global - Set global TypingSpeed early
• •config-dimensions-explicit - Set explicit terminal dimensions
• •config-comments-document - Use comments to document tape structure

2. Dependency Management (CRITICAL)

• •deps-require-early - Use Require for dependency validation
• •deps-require-order - Place Require before settings
• •deps-require-all - Require all external commands
• •deps-system-requirements - Verify system dependencies

3. Command Syntax (HIGH)

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

4. Timing & Synchronization (HIGH)

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

5. Output Optimization (MEDIUM-HIGH)

• •output-format-selection - Choose output format based on use case
• •output-framerate - Optimize framerate for file size
• •output-dimensions-optimize - Right-size terminal dimensions
• •output-loop-offset - Use LoopOffset for seamless loops
• •output-multiple-formats - Generate multiple output formats
• •output-relative-paths - Use relative paths for portability

6. Visual Quality (MEDIUM)

• •visual-font-readable - Choose readable font settings
• •visual-theme-selection - Select appropriate theme
• •visual-window-decoration - Add window decorations for polish
• •visual-spacing - Adjust letter and line spacing
• •visual-padding-margin - Use padding and margins effectively
• •visual-cursor-visibility - Ensure cursor visibility

7. CI/Automation (MEDIUM)

• •ci-github-action - Use official VHS GitHub Action
• •ci-auto-commit - Auto-commit generated assets
• •ci-golden-files - Use golden files for integration testing
• •ci-matrix-builds - Generate platform-specific demos
• •ci-caching - Cache VHS dependencies in CI

8. Advanced Patterns (LOW)

• •advanced-source-include - Use Source for reusable tape components
• •advanced-clipboard - Use Copy and Paste for complex input
• •advanced-recording-live - Record live sessions then edit
• •advanced-server-mode - Use server mode for remote access

How to Use

Read individual reference files for detailed explanations and code examples:

• •Section definitions - Category structure and impact levels
• •Rule template - Template for adding new rules

Reference Files