docs: record demo GIF and embed in README#31
Merged
Merged
Conversation
Replaces the static text-block demo at the top of the README with a
real animated terminal recording of the killer feature firing on a
wrong-author commit.
Three files added:
docs/demo.tape The vhs source script — fully self-contained,
sets up a sandbox $HOME, seeds a gitswitch
identity bound to /tmp/demo with a deliberate
wrong local user.email, then records three
scenes:
1. git status + about-to-commit
2. the red bordered guard panel firing
3. unset the local override + commit succeeds
docs/demo.gif 205 KB · 1000×540 · loops cleanly. Embedded in
the README's hero block.
docs/demo.mp4 201 KB · for Twitter / Show HN / LinkedIn where
GIF compression looks worse than h264.
Reproduce locally:
brew install vhs
vhs docs/demo.tape
Tape is deterministic — same input gives the same output frame for
frame, so re-running for a future palette / scene tweak gives a
trustworthy diff.
The README now leads with the GIF directly under the badge row,
which is the layout viral CLI tools (lazygit, gh, starship, atuin)
all converged on. Visitors see the marquee moment before they
read a single sentence.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Maintainer pushback was right on both points:
- "play to much fast" → typing was 35ms, almost too fast to read
- "add more content" → only 3 commands shown, no setup context
What changed in docs/demo.tape:
* TypingSpeed 35ms → 60ms (still snappy, actually readable)
* Window 1000×540 → 1100×700 (more vertical room for output)
* Theme stays Catppuccin Mocha
* Added scenes 1 and 5:
Scene 1 gitswitch list — establishes that the user has
TWO identities (work + personal)
bound to two directories. Without
this, viewers see the red panel
with no context for what was
supposed to be active.
Scene 5 gitswitch why — replaces `gitswitch doctor` as
the victory lap. doctor depends
on real ssh-auth + gh, neither of
which work in the sandbox.
why works entirely from local
config and shows the full
resolution chain — better
storytelling for the closing
beat anyway.
* Sleep budgets bumped: red panel now held 5.5s (was 4.5s), final
why frame held 4.5s — viewers can actually read both.
One real bug fixed in the hidden setup. The per-identity gitconfig
that `gitswitch use` writes turns SSH commit signing on by default
(commit.gpgsign = true, signingkey pointing at a non-existent
fake key). In the sandbox that made the second commit fail with
`fatal: failed to write commit object`, completely undermining the
"and then it works!" beat. Setup now strips the signing/sshCommand
sections from the per-identity files post-`use` so the recording
actually shows a successful commit.
GIF grows 205 KB → 692 KB and runtime grows 11s → 26s. Still well
under the GitHub-renders-fine ceiling, and the extra duration is
the price for the extra story.
Reproducible with `vhs docs/demo.tape` as before.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Replaces the static text-block demo at the top of the README with a real animated terminal recording of the killer feature firing on a wrong-author commit.
The result
Three scenes, ~10 seconds:
git status+ about-to-commit (calm)git config --unset user.email+ retry → green commit succeedsWhat's new in this PR
docs/demo.tapedocs/demo.gifdocs/demo.mp4README.mdReproduce locally
The tape is deterministic — same input gives the same output frame for frame. Re-running it gives a trustworthy diff for future palette/scene tweaks.
Why a GIF in the README hero
Every viral CLI in our cohort (
lazygit,gh,starship,atuin) leads with one. Visitors decide whether to install in 5–10 seconds; a static code block is fine, an autoplaying GIF is one full step better. Especially forgitswitchwhere the killer feature is a visual moment (the red panel) — words don't sell that, the recording does.🤖 Generated with Claude Code
EOF
)