tmux-video-evidence

Tmux Video Evidence for Agent Work Verification

Purpose

Prove terminal execution against a specific commit and publish reviewable evidence that both humans and agents can consume directly from the PR.

Required Outputs

Every terminal evidence package must include:

• A terminal video (.mp4 preferred)
• A browser-friendly preview artifact (.gif recommended)
• Captions for that video (burned-in preferred; .vtt/.srt acceptable)
• Sanitized terminal/test output (no machine-specific absolute paths)
• GitHub-hosted URL(s) published by automation
• A downloadable high-fidelity artifact (.mp4 or .mp4.zip)

Mandatory Video Sections

Record these sections in order:

#	Section	Must show
1	Git Provenance	git rev-parse HEAD, branch, merge-base
2	Commit Log	git log --oneline origin/main..HEAD
3	Code Diffs	git diff origin/main...HEAD (not just --stat)
4	PR Status	gh pr view <N>
5	Live Work	Real test/deploy/command output
6	Post-run SHA	Same git rev-parse HEAD as section 1

Evidence Script Template

Create /tmp/<work_name>_evidence.sh:

#!/usr/bin/env bash
set -euo pipefail

REPO_ROOT="<absolute path to repo>"
cd "$REPO_ROOT"

HEAD_SHA="$(git rev-parse HEAD)"

echo "=== 1. GIT PROVENANCE ==="
echo "HEAD: $HEAD_SHA"
git branch --show-current
git merge-base HEAD origin/main

echo "=== 2. COMMIT LOG ==="
git log --oneline origin/main..HEAD

echo "=== 3. CODE DIFFS ==="
git diff origin/main...HEAD -- <important file 1> | head -80
git diff origin/main...HEAD -- <important file 2> | head -80

echo "=== 4. PR STATUS ==="
gh pr view <PR_NUMBER> --json number,title,url,state,headRefName

echo "=== 5. LIVE TEST EXECUTION (SANITIZED) ==="
<test command> 2>&1 \
  | sed -E \
      -e 's#/Users/[^/]+/#/Users/REDACTED/#g' \
      -e 's#/private/var/folders/[^[:space:]]+#/private/var/folders/REDACTED#g'

echo "=== 6. POST-RUN SHA ==="
POST_SHA="$(git rev-parse HEAD)"
echo "PRE=$HEAD_SHA"
echo "POST=$POST_SHA"
[ "$HEAD_SHA" = "$POST_SHA" ] && echo "SHA MATCH"

Recording

chmod +x /tmp/<work_name>_evidence.sh

# Option A: direct screen recording (mp4)
# (Use Kap or equivalent and run /tmp/<work_name>_evidence.sh in the visible terminal)

# Option B: asciinema capture, then convert to mp4
timeout 120 asciinema rec /tmp/<work_name>.cast --command "/tmp/<work_name>_evidence.sh" --idle-time-limit 5 --overwrite
agg --cols 120 --rows 50 /tmp/<work_name>.cast /tmp/<work_name>.gif
ffmpeg -y -i /tmp/<work_name>.gif -movflags +faststart -pix_fmt yuv420p /tmp/<work_name>.mp4

Captions (MANDATORY)

For every tmux video, provide captions by either:

1. Burning captions into the video (preferred), or
2. Producing /tmp/<work_name>.vtt and linking it in PR + gist.

Use ~/.claude/skills/video-caption/SKILL.md when you need to generate burned-in captions reliably.

Publish in PR (GitHub-Hosted, Zero-Touch)

Preferred path:

zip -j /tmp/terminal.mp4.zip /abs/path/to/terminal.mp4
gh release create evidence-pr-<PR_NUMBER> --draft --title "PR #<PR_NUMBER> Evidence" --notes "" 2>/dev/null || true
gh release upload evidence-pr-<PR_NUMBER> /tmp/terminal.mp4.zip /abs/path/to/terminal.gif /abs/path/to/terminal.srt --clobber
gh release view evidence-pr-<PR_NUMBER> --json assets,url
gh pr comment <PR_NUMBER_OR_URL> --body-file /tmp/evidence_comment.md

Behavior:

• Keeps publication fully zero-touch via gh
• Publishes durable GitHub-hosted release URLs for the .gif, .mp4.zip, and captions
• Avoids dependence on a browser session cookie

Optional path:

• $HOME/.claude/scripts/github_pr_media_upload.py can still be used when native user-attachments URLs are explicitly desired and browser auth is available

Compression Guidance

GitHub free plans often cap video uploads at 10 MB. Compress when needed:

ffmpeg -y -i /tmp/<work_name>.mp4 -vcodec h264 -crf 23 -preset medium /tmp/<work_name>.compressed.mp4

Reviewer Checklist

A reviewer should reject evidence if any are missing:

1. Pre/post SHA match
2. Real command output (not echo-only)
3. Captions present
4. Sanitized logs (no machine-specific absolute paths)
5. GitHub-hosted media URL(s) in PR
6. Automated gh release/comment workflow or optional native-attachment helper used instead of manual drag-drop
7. Matching entry in self-contained gist