Skip to content

Add a real VHS-recorded demo of writ to the README - #34

Merged
Laaaaksh merged 3 commits into
masterfrom
fm/demo-writ
Aug 30, 2026
Merged

Add a real VHS-recorded demo of writ to the README#34
Laaaaksh merged 3 commits into
masterfrom
fm/demo-writ

Conversation

@Laaaaksh

Copy link
Copy Markdown
Owner

Summary

  • Records a genuine, unstaged end-to-end run of the writ CLI with VHS: propose → approve --yes → an in-scope edit that gets attested and leaves status clean/auto-mergeable → an out-of-scope edit that status flags as drift, while staying quiet about the in-scope work. That signal-vs-noise contrast is the whole pitch, and both runs are captured back to back.
  • Adds docs/assets/demo.mp4 (1280px H.264/yuv420p, full quality) and docs/assets/demo.gif (960px, ~12fps palette-quantized, 832 KB — well under the 10 MB budget) for the README.
  • Adds a ## Demo section to the README right after the intro/badges, embedding the GIF and linking the MP4 for full quality.
  • Adds scripts/record-demo/record.sh + scripts/record-demo/demo.tape (the actual recording script, reviewable in the diff) + scripts/record-demo/README.md, and a Makefile with a demo target so the recording is one command (make demo) and reproducible.
  • Documents the workflow in AGENTS.md so future agents regenerate the assets via make demo instead of hand-editing them.

Note: the task brief mentioned a possibly-unverified demo GIF already embedded in the README under docs/assets/. There wasn't one — README had no ## Demo section and docs/assets/ only held writ-banner.svg — so there was nothing to delete/replace beyond adding the new assets.

Test plan

  • go build ./..., go vet ./..., gofmt -l . (clean), go test ./... all pass
  • make demo runs end to end: builds the real binary, seeds a throwaway repo, records with VHS, converts with ffmpeg
  • Verified docs/assets/demo.mp4 is H.264/yuv420p, 1280x800, 1148 frames (~46s)
  • Verified docs/assets/demo.gif is 960x600, 551 frames, 832 KB
  • Visually reviewed extracted frames: real terminal output, the clean auto-mergeable status (green) and the drift-flagged status (red, naming only the out-of-scope file) both genuinely appear
  • Confirmed no old demo asset existed to delete (README/docs/assets had none)

🤖 Generated with Claude Code

https://claude.ai/code/session_01UjNjr48C8W9go9PmcNjdh6

Records the actual propose -> approve -> implement -> attest -> status
loop against a freshly seeded throwaway repo: an in-scope edit that
gets attested and leaves status clean/auto-mergeable, then an
out-of-scope edit that status flags as drift while staying quiet
about the in-scope work - the signal-vs-noise contrast that is writ's
whole pitch. scripts/record-demo/record.sh builds the real binary,
seeds the repo, and drives scripts/record-demo/demo.tape end to end,
so the recording is reproducible via `make demo`.

Claude-Session: https://claude.ai/code/session_01UjNjr48C8W9go9PmcNjdh6
Points future agents at make demo / scripts/record-demo for
regenerating docs/assets/demo.{gif,mp4} instead of hand-editing them.

Claude-Session: https://claude.ai/code/session_01UjNjr48C8W9go9PmcNjdh6
- Drop Set Height from 800 to 480 so the recorded terminal fits its
  content instead of leaving most of every frame empty.
- Shorten the attest --note text so the criterion claim line
  ("retries-on-5xx ... claimed by agent ...") no longer wraps
  mid-phrase at the right edge.
- Also relocate the throwaway demo repo from
  scripts/record-demo/.demo-repo to .demo-repo at the repo root:
  the shorter absolute path keeps writ's "writ approved: <path>"
  output line under the terminal's column width too, since it was
  wrapping in the same way for the same reason (line too long for
  the terminal width) even though it wasn't flagged directly.

Re-recorded with the same tape end to end; re-verified dimensions
(1280x480 mp4, 960x360 gif), frame counts (1089 / 523), and file
sizes (473K / 868K, gif well under the 10 MB budget), and visually
confirmed no line wraps anywhere in the loop.

Claude-Session: https://claude.ai/code/session_01UjNjr48C8W9go9PmcNjdh6
@Laaaaksh

Copy link
Copy Markdown
Owner Author

Fixed the two cosmetic issues:

  1. Empty dark space: Set Height dropped from 800 to 480 in demo.tape — the terminal now fits its content instead of leaving most of every frame empty.
  2. Wrapping claim line: shortened the writ attest --note text so retries-on-5xx ... claimed by agent ... "retries Send on failure" fits on one line.

While verifying, I found the writ approved: <path> line was also wrapping for the same underlying reason (line too long for the terminal width) even though it wasn't called out — fixed it too by moving the throwaway demo repo from scripts/record-demo/.demo-repo to .demo-repo at the repo root, which shortens the absolute path writ prints.

Re-recorded end to end with make demo, re-verified: docs/assets/demo.mp4 is 1280x480 (1089 frames), docs/assets/demo.gif is 960x360 (523 frames, 868K — under the 10 MB budget), and I visually confirmed no line wraps anywhere in the loop.

@Laaaaksh
Laaaaksh merged commit 361b034 into master Aug 30, 2026
4 checks passed
@Laaaaksh
Laaaaksh deleted the fm/demo-writ branch August 30, 2026 14:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant