feat: add VHS terminal demo tape files

[rubenmarcus]

Summary

• Add charmbracelet/vhs tape files for Figma, GitHub, Linear, and Notion demos
• Each tape generates GIF + MP4 for docs, blog posts, and social media
• Includes README with install instructions and usage
• Output directory gitignored (generated artifacts)

Test plan

• Install VHS: brew install charmbracelet/tap/vhs
• Run vhs demos/figma.tape — produces demos/output/figma-demo.gif and .mp4
• Verify all 4 tapes generate without errors
• Review generated GIFs for quality and timing

🤖 Generated with Claude Code

[github-actions]

Issue Linking Reminder

This PR doesn't appear to have a linked issue. Consider linking to:

• This repo: Closes #123
• ralph-ideas: Closes multivmlabs/ralph-ideas#123

Using Closes, Fixes, or Resolves will auto-close the issue when this PR is merged.

---

If this PR doesn't need an issue, you can ignore this message.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 78bfdca6d5

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Add CLI setup before demo generation steps

The README’s Generate demos section assumes vhs is enough, but every tape runs the ralph-starter binary (for example demos/github.tape uses Type "ralph-starter run ..."). In a fresh clone, that command is not available on PATH until the project is built/installed, so following these instructions produces command not found captures instead of the intended demo flow. Please add a prerequisite to build/link/install ralph-starter, or change the tapes to call the local CLI entrypoint directly.

Useful? React with 👍 / 👎.

[greptile-apps]

Greptile Summary

This PR introduces a demos/ directory containing four VHS tape files (figma.tape, github.tape, linear.tape, notion.tape) for generating terminal demo GIFs and MP4s, along with a README, a .gitkeep placeholder, and a .gitignore rule to exclude generated artifacts. The approach fits well with the repository's documentation tooling — the gitignore pattern is correct and the README instructions are clear.

Issues found:

• Missing Require ralph-starter in all four tape files — VHS Require directives abort the recording with a clear error if the binary is absent. Without one, running a tape without ralph-starter installed will silently produce a GIF showing a command not found error. All four tapes declare Require echo but none guard for the actual binary being demoed.
• github.tape, linear.tape, and notion.tape are sleep-only after the first Enter — unlike figma.tape which types responses to interactive prompts, these three tapes just sleep for cumulative ~13 seconds after pressing Enter, recording blank terminal time with no visible output. Adding Hide/Show blocks with echo calls to simulate representative output at each stage would produce significantly more useful recordings.

Confidence Score: 2/5

• Safe to merge from an infrastructure standpoint, but two of the four tape files will produce low-quality or non-functional demo recordings without fixes.
• No production code is touched — this is purely a demo/documentation addition. The .gitignore and .gitkeep changes are correct. However, all four tape files are missing a Require ralph-starter guard, meaning a bad recording could be silently generated if the binary is absent. Additionally, three of the four tape files (github.tape, linear.tape, notion.tape) lack any simulated output and will record blank terminal time, undermining the primary purpose of creating useful demo assets. These are non-breaking issues but directly impact demo quality.
• demos/github.tape, demos/linear.tape, and demos/notion.tape need simulated output added; all four tape files need Require ralph-starter guards before running them to generate demo artifacts.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Developer runs\n`vhs demos/*.tape`] --> B{ralph-starter\ninstalled?}
    B -- No --> C[❌ command not found\nBlank/error GIF recorded\nNo Require guard to abort early]
    B -- Yes --> D[VHS executes tape]
    D --> E[Type command + Enter]
    E --> F{Tape type?}
    F -- figma.tape --> G[Interactive prompts\nType responses to each step]
    F -- github/linear/notion.tape --> H[Sleep-only blocks\nNo simulated output]
    G --> I[Sleep + finish]
    H --> I
    I --> J[✅ Output written to\ndemos/output/*.gif\ndemos/output/*.mp4]

Loading

_{Last reviewed commit: 78bfdca}

[greptile-apps]

All four tape files declare Require echo but none declare Require ralph-starter. The Require directive causes VHS to abort with a clear error before recording begins if the binary is not found. Without it, VHS will silently record a GIF that shows a command not found (or similar shell error) instead of a working demo.

Add a Require ralph-starter line alongside the existing Require echo. The same issue exists in demos/github.tape:7, demos/linear.tape:7, and demos/notion.tape:7.

Suggested change

	Require echo
	Require echo
	Require ralph-starter

Prompt To Fix With AI

This is a comment left during a code review.
Path: demos/figma.tape
Line: 7

Comment:
All four tape files declare `Require echo` but none declare `Require ralph-starter`. The `Require` directive causes VHS to abort with a clear error before recording begins if the binary is not found. Without it, VHS will silently record a GIF that shows a `command not found` (or similar shell error) instead of a working demo.

Add a `Require ralph-starter` line alongside the existing `Require echo`. The same issue exists in `demos/github.tape:7`, `demos/linear.tape:7`, and `demos/notion.tape:7`.

```suggestion
Require echo
Require ralph-starter
```

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

After pressing Enter on the command, this tape (and similarly linear.tape and notion.tape) only uses Sleep statements with no Type, Show, or Hide+echo blocks to simulate terminal output. The resulting GIF will show a terminal sitting blank while the process runs silently offscreen, producing a confusing or empty recording.

Compare with figma.tape, which types interactive responses to simulate a real prompt-driven flow. Consider using Hide/Show blocks with echo calls to print representative output at each stage, which is a common VHS pattern for demos that can't rely on a live binary:

Hide
  Type "echo 'Fetching issue #42 from acme/webapp...'" Enter
  Sleep 200ms
Show
Sleep 1s

Hide
  Type "echo '✓ 3 iterations · tests passing'" Enter
  Sleep 200ms
Show
Sleep 1s

Without simulated output, the Sleep 2s / Sleep 4s blocks record dead air. The same concern applies to demos/linear.tape:26-37 and demos/notion.tape:26-37.

Prompt To Fix With AI

This is a comment left during a code review.
Path: demos/github.tape
Line: 26-37

Comment:
After pressing `Enter` on the command, this tape (and similarly `linear.tape` and `notion.tape`) only uses `Sleep` statements with no `Type`, `Show`, or `Hide`+`echo` blocks to simulate terminal output. The resulting GIF will show a terminal sitting blank while the process runs silently offscreen, producing a confusing or empty recording.

Compare with `figma.tape`, which types interactive responses to simulate a real prompt-driven flow. Consider using `Hide`/`Show` blocks with `echo` calls to print representative output at each stage, which is a common VHS pattern for demos that can't rely on a live binary:

```
Hide
  Type "echo 'Fetching issue #42 from acme/webapp...'" Enter
  Sleep 200ms
Show
Sleep 1s

Hide
  Type "echo '✓ 3 iterations · tests passing'" Enter
  Sleep 200ms
Show
Sleep 1s
```

Without simulated output, the `Sleep 2s` / `Sleep 4s` blocks record dead air. The same concern applies to `demos/linear.tape:26-37` and `demos/notion.tape:26-37`.

How can I resolve this? If you propose a fix, please make it concise.

_{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[github-actions]

🔗 Docs Preview

Preview URL: https://feat-vhs-terminal-demos.ralph-starter-docs.pages.dev

This preview was deployed from the latest commit on this PR.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.