Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

Refactor demo dependencies to auto-download and build

Maximilian Roosad2ba155a3f7
diff --git a/docs/demos/.gitignore b/docs/demos/.gitignore
index a94a555cf..95f691961 100644
--- a/docs/demos/.gitignore
+++ b/docs/demos/.gitignore
@@ -1,2 +1,2 @@
-# Built VHS binary with keystroke overlay
-vhs-keystrokes/
+# Auto-built/downloaded dependencies
+.deps/
diff --git a/docs/demos/CLAUDE.md b/docs/demos/CLAUDE.md
index b72cabc0a..7c78d0279 100644
--- a/docs/demos/CLAUDE.md
+++ b/docs/demos/CLAUDE.md
@@ -45,6 +45,13 @@ Regenerate a single demo:
## Prerequisites
+**Requires Go** — The VHS fork is built from source ([install Go](https://go.dev/dl/)).
+
+External dependencies are downloaded/built automatically on first run:
+- **VHS** — Custom fork with keystroke overlay (cloned and built from source)
+- **Claude Code binary** — Downloaded from Anthropic's release bucket
+- **Zellij plugin** — Downloaded from GitHub releases
+
Demos that launch Claude Code (wt-switch, wt-statusline, wt-zellij-omnibus) require `ANTHROPIC_API_KEY` in your environment:
```bash
@@ -71,40 +78,28 @@ To fetch published assets (without rebuilding):
Both build and fetch output to the same location (`docs/static/assets/`), so local builds override fetched assets.
-## vhs-keystrokes setup (REQUIRED for wt-select demos)
-
-The `wt-select` demos require a custom VHS fork with keystroke overlay. The `keypress-overlay` branch contains our features (bottom positioning, gold highlighting for newest key).
+## Modifying the VHS fork
-All commands run from **worktrunk root**:
+The VHS fork is cloned to `docs/demos/.deps/vhs/` and built automatically. To modify it:
```bash
-# First-time setup (requires Go)
-git clone -b keypress-overlay https://github.com/max-sixty/vhs.git docs/demos/vhs-keystrokes
-(cd docs/demos/vhs-keystrokes && go build -o vhs-keystrokes .)
-
-# Update existing clone
-git -C docs/demos/vhs-keystrokes pull origin keypress-overlay
-(cd docs/demos/vhs-keystrokes && go build -o vhs-keystrokes .)
-```
+# 1. Make changes in the cloned repo
+cd docs/demos/.deps/vhs
+# ... edit files ...
-The binary is gitignored. Build scripts skip wt-select GIF recording if missing.
-
-### Modifying the fork
-
-All commands run from **worktrunk root**:
-
-```bash
-# 1. Rebuild and test
-(cd docs/demos/vhs-keystrokes && go build -o vhs-keystrokes .)
+# 2. Rebuild and test
+go build -o vhs .
+cd ../../../..
./docs/demos/build docs --only wt-select
-# 2. Commit and push
-git -C docs/demos/vhs-keystrokes add -A
-git -C docs/demos/vhs-keystrokes commit -m "Description"
-git -C docs/demos/vhs-keystrokes push origin keypress-overlay
+# 3. Commit and push to the fork
+cd docs/demos/.deps/vhs
+git add -A
+git commit -m "Description"
+git push origin keypress-overlay
```
-**CRITICAL**: Always push to `origin keypress-overlay` after changes. The directory is gitignored from worktrunk—changes only persist in the vhs fork repo.
+**CRITICAL**: Push changes to `origin keypress-overlay`. The directory is gitignored—changes only persist in the fork repo.
### Keystroke timing calibration
diff --git a/docs/demos/build b/docs/demos/build
index 2b5ea75c7..50fee4491 100755
--- a/docs/demos/build
+++ b/docs/demos/build
@@ -42,17 +42,13 @@ from shared import ( # noqa: E402
SIZE_SOCIAL,
record_text,
build_tape_replacements,
+ ensure_vhs_binary,
)
REPO_ROOT = SCRIPT_DIR.parent.parent
OUT_DIR = SCRIPT_DIR.parent / "static" / "assets"
TAPES_DIR = SCRIPT_DIR / "tapes"
-# Custom VHS binary with keystroke overlay
-VHS_KEYSTROKES = os.environ.get(
- "VHS_KEYSTROKES", str(SCRIPT_DIR / "vhs-keystrokes" / "vhs-keystrokes")
-)
-
# =============================================================================
# Setup Helpers
@@ -273,43 +269,37 @@ echo "Add placeholder module for user profile settings."
# Demo Registrations
# =============================================================================
-# Format: (tape_file, output_name, setup_func, vhs_type)
+# Format: (tape_file, output_name, setup_func)
# All demos in a mode use that mode's default size.
# Note: setup_func must be a named function (not lambda) for multiprocessing.
DOCS_DEMOS = [
- ("wt-core.tape", "wt-core", prepare_with_hooks, "vhs"),
- ("wt-switch.tape", "wt-switch", prepare_switch, "vhs"),
- ("wt-list.tape", "wt-list", prepare_with_hooks, "vhs"),
- ("wt-commit.tape", "wt-commit", prepare_merge_demo, "vhs"),
- ("wt-statusline.tape", "wt-statusline", prepare_switch, "vhs"),
- ("wt-merge.tape", "wt-merge", prepare_merge_demo, "vhs"),
- ("wt-select.tape", "wt-select", prepare_basic, "vhs-keystrokes"),
- ("wt-zellij-omnibus.tape", "wt-zellij-omnibus", prepare_zellij_omnibus, "vhs"),
+ ("wt-core.tape", "wt-core", prepare_with_hooks),
+ ("wt-switch.tape", "wt-switch", prepare_switch),
+ ("wt-list.tape", "wt-list", prepare_with_hooks),
+ ("wt-commit.tape", "wt-commit", prepare_merge_demo),
+ ("wt-statusline.tape", "wt-statusline", prepare_switch),
+ ("wt-merge.tape", "wt-merge", prepare_merge_demo),
+ ("wt-select.tape", "wt-select", prepare_basic),
+ ("wt-zellij-omnibus.tape", "wt-zellij-omnibus", prepare_zellij_omnibus),
]
SOCIAL_DEMOS = [
- ("wt-switch.tape", "wt-switch", prepare_switch, "vhs"),
- ("wt-statusline.tape", "wt-statusline", prepare_switch, "vhs"),
- ("wt-list.tape", "wt-list", prepare_with_hooks, "vhs"),
- ("wt-list-remove.tape", "wt-list-remove", prepare_with_hooks, "vhs"),
- (
- "wt-hooks.tape",
- "wt-hooks",
- partial(prepare_with_hooks, include_deps=True),
- "vhs",
- ),
- ("wt-devserver.tape", "wt-devserver", prepare_devserver, "vhs"),
- ("wt-commit.tape", "wt-commit", prepare_merge_demo, "vhs"),
+ ("wt-switch.tape", "wt-switch", prepare_switch),
+ ("wt-statusline.tape", "wt-statusline", prepare_switch),
+ ("wt-list.tape", "wt-list", prepare_with_hooks),
+ ("wt-list-remove.tape", "wt-list-remove", prepare_with_hooks),
+ ("wt-hooks.tape", "wt-hooks", partial(prepare_with_hooks, include_deps=True)),
+ ("wt-devserver.tape", "wt-devserver", prepare_devserver),
+ ("wt-commit.tape", "wt-commit", prepare_merge_demo),
(
"wt-merge.tape",
"wt-merge",
partial(prepare_merge_demo, commit_generation=False, staged_changes=False),
- "vhs",
),
- ("wt-select.tape", "wt-select", prepare_basic, "vhs-keystrokes"),
- ("wt-core.tape", "wt-core", prepare_with_hooks, "vhs"),
- ("wt-zellij-omnibus.tape", "wt-zellij-omnibus", prepare_zellij_omnibus, "vhs"),
+ ("wt-select.tape", "wt-select", prepare_basic),
+ ("wt-core.tape", "wt-core", prepare_with_hooks),
+ ("wt-zellij-omnibus.tape", "wt-zellij-omnibus", prepare_zellij_omnibus),
]
TARGETS = {
@@ -335,10 +325,10 @@ def record_demo(
tape_file: str,
output_name: str,
setup_func,
- vhs_type: str,
mode_out_dir: Path,
themes: list[str],
demo_size: DemoSize,
+ vhs_binary: str,
text_mode: bool = False,
):
"""Record a single demo (runs in subprocess for parallel execution)."""
@@ -346,8 +336,6 @@ def record_demo(
if not tape_path.exists():
raise FileNotFoundError(f"{tape_file} not found")
- vhs_binary = VHS_KEYSTROKES if vhs_type == "vhs-keystrokes" else "vhs"
-
# Create fresh environment in temp directory
demo_env_dir = Path(tempfile.mkdtemp(prefix="wt-demo-"))
setup_demo_output(demo_env_dir)
@@ -446,10 +434,13 @@ Examples:
print("--shell and --text are mutually exclusive")
return
- # Check dependencies
- deps = ["wt", "vhs", "starship", "zellij"]
+ # Check dependencies (VHS is built from source, not required in PATH)
+ deps = ["wt", "starship", "zellij"]
check_dependencies(deps)
+ # Ensure VHS is built (requires Go)
+ vhs_binary = str(ensure_vhs_binary())
+
# Output goes to mode/theme subdirectories
mode_out_dir = OUT_DIR / args.target
starship_config = setup_demo_output(mode_out_dir)
@@ -461,26 +452,16 @@ Examples:
# Filter demos if --only specified
if args.only:
- demos = [(t, n, s, v) for t, n, s, v in demos if n == args.only]
+ demos = [(t, n, s) for t, n, s in demos if n == args.only]
if not demos:
- all_names = [n for _, n, _, _ in target_config["demos"]]
+ all_names = [n for _, n, _ in target_config["demos"]]
print(f"Unknown demo: {args.only}")
print(f"Available for {args.target}: {', '.join(all_names)}")
return
- # Check vhs-keystrokes availability
- vhs_keystrokes_available = Path(VHS_KEYSTROKES).exists()
- needs_keystrokes = any(vhs_type == "vhs-keystrokes" for _, _, _, vhs_type in demos)
-
- if needs_keystrokes and not vhs_keystrokes_available:
- print("Error: vhs-keystrokes required but not found", file=sys.stderr)
- print(f"Not found at: {VHS_KEYSTROKES}", file=sys.stderr)
- print("See docs/demos/CLAUDE.md for build instructions", file=sys.stderr)
- sys.exit(1)
-
# Handle --shell mode (interactive, must be sequential)
if args.shell:
- tape_file, output_name, setup_func, vhs_type = demos[0]
+ tape_file, output_name, setup_func = demos[0]
demo_env_dir = Path(tempfile.mkdtemp(prefix="wt-demo-"))
setup_demo_output(demo_env_dir)
env = DemoEnv(name=output_name, out_dir=demo_env_dir, repo_name="acme")
@@ -493,16 +474,16 @@ Examples:
if args.sequential or len(demos) == 1:
print(f"\nRecording {len(demos)} demo(s) sequentially...")
failed = []
- for tape_file, output_name, setup_func, vhs_type in demos:
+ for tape_file, output_name, setup_func in demos:
try:
record_demo(
tape_file,
output_name,
setup_func,
- vhs_type,
mode_out_dir,
themes,
demo_size,
+ vhs_binary,
args.text,
)
except Exception as e:
@@ -519,13 +500,13 @@ Examples:
tape_file,
output_name,
setup_func,
- vhs_type,
mode_out_dir,
themes,
demo_size,
+ vhs_binary,
args.text,
): output_name
- for tape_file, output_name, setup_func, vhs_type in demos
+ for tape_file, output_name, setup_func in demos
}
failed = []
diff --git a/docs/demos/shared/__init__.py b/docs/demos/shared/__init__.py
index 0a55804dd..a4e1c3937 100644
--- a/docs/demos/shared/__init__.py
+++ b/docs/demos/shared/__init__.py
@@ -27,6 +27,8 @@ from .lib import (
# Text output recording
record_text,
build_tape_replacements,
+ # External dependencies
+ ensure_vhs_binary,
)
from .themes import THEMES, format_theme_for_vhs
@@ -59,4 +61,6 @@ __all__ = [
# Text output recording
"record_text",
"build_tape_replacements",
+ # External dependencies
+ "ensure_vhs_binary",
]
diff --git a/docs/demos/shared/lib.py b/docs/demos/shared/lib.py
index bd0c5c556..bc6591fda 100644
--- a/docs/demos/shared/lib.py
+++ b/docs/demos/shared/lib.py
@@ -2,9 +2,11 @@
import json
import os
+import platform
import re
import shutil
import subprocess
+import urllib.request
from dataclasses import dataclass
from datetime import datetime, timedelta
from pathlib import Path
@@ -13,6 +15,157 @@ from .themes import THEMES, format_theme_for_vhs
REAL_HOME = Path.home()
FIXTURES_DIR = Path(__file__).parent / "fixtures"
+DEPS_DIR = Path(__file__).parent.parent / ".deps" # Downloaded dependencies
+
+# External dependency URLs
+_GCS_BUCKET = "https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases"
+_ZELLIJ_PLUGIN_URL = "https://github.com/Cynary/zellij-tab-name/releases/download/v0.4.1/zellij-tab-name.wasm"
+_VHS_FORK_REPO = "https://github.com/max-sixty/vhs.git"
+_VHS_FORK_BRANCH = "keypress-overlay"
+
+
+def _detect_platform() -> str:
+ """Detect platform for Claude Code binary download."""
+ system = platform.system().lower()
+ machine = platform.machine().lower()
+
+ if system == "darwin":
+ os_name = "darwin"
+ elif system == "linux":
+ os_name = "linux"
+ else:
+ raise RuntimeError(f"Unsupported OS: {system}")
+
+ if machine in ("x86_64", "amd64"):
+ arch = "x64"
+ elif machine in ("arm64", "aarch64"):
+ arch = "arm64"
+ else:
+ raise RuntimeError(f"Unsupported architecture: {machine}")
+
+ # Check for musl on Linux x64
+ if os_name == "linux" and arch == "x64":
+ try:
+ result = subprocess.run(
+ ["ldd", "--version"], capture_output=True, text=True, check=False
+ )
+ if "musl" in result.stderr.lower() or "musl" in result.stdout.lower():
+ return "linux-x64-musl"
+ except FileNotFoundError:
+ pass
+
+ return f"{os_name}-{arch}"
+
+
+def _download_file(url: str, dest: Path) -> None:
+ """Download a file from URL to destination (atomic)."""
+ dest.parent.mkdir(parents=True, exist_ok=True)
+ print(f"Downloading {dest.name}...")
+ temp = dest.with_suffix(".tmp")
+ try:
+ urllib.request.urlretrieve(url, temp)
+ temp.rename(dest)
+ except BaseException:
+ temp.unlink(missing_ok=True)
+ raise
+
+
+def _ensure_claude_binary() -> Path:
+ """Ensure Claude Code binary is downloaded, return path."""
+ claude_binary = DEPS_DIR / "claude"
+ if claude_binary.exists():
+ return claude_binary
+
+ plat = _detect_platform()
+ print(f"Fetching Claude Code for {plat}...")
+
+ # Get stable version
+ with urllib.request.urlopen(f"{_GCS_BUCKET}/stable") as resp:
+ version = resp.read().decode().strip()
+ print(f"Claude Code version: {version}")
+
+ # Download binary
+ _download_file(f"{_GCS_BUCKET}/{version}/{plat}/claude", claude_binary)
+ claude_binary.chmod(0o755)
+
+ # Verify
+ result = subprocess.run(
+ [str(claude_binary), "--version"], capture_output=True, text=True, check=False
+ )
+ if result.returncode != 0:
+ raise RuntimeError(
+ f"Claude binary downloaded but --version failed: {result.stderr or result.stdout}"
+ )
+
+ print(f"✓ Claude Code {version} ready")
+ return claude_binary
+
+
+def _ensure_zellij_plugin() -> Path:
+ """Ensure Zellij tab-name plugin is downloaded, return path."""
+ plugin_path = DEPS_DIR / "zellij-tab-name.wasm"
+ if plugin_path.exists():
+ return plugin_path
+
+ _download_file(_ZELLIJ_PLUGIN_URL, plugin_path)
+ print(f"✓ Zellij plugin ready")
+ return plugin_path
+
+
+def ensure_vhs_binary() -> Path:
+ """Ensure VHS binary is cloned and built, return path.
+
+ Uses a custom VHS fork with keystroke overlay support.
+ Requires Go to be installed.
+ """
+ vhs_dir = DEPS_DIR / "vhs"
+ vhs_binary = vhs_dir / "vhs"
+
+ if vhs_binary.exists():
+ return vhs_binary
+
+ # Check Go is available
+ if not shutil.which("go"):
+ raise RuntimeError(
+ "Go is required to build VHS. Install from https://go.dev/dl/"
+ )
+
+ # Clone if needed
+ if not vhs_dir.exists():
+ print(f"Cloning VHS fork...")
+ DEPS_DIR.mkdir(parents=True, exist_ok=True)
+ result = subprocess.run(
+ ["git", "clone", "-b", _VHS_FORK_BRANCH, "--depth=1", _VHS_FORK_REPO, str(vhs_dir)],
+ capture_output=True,
+ text=True,
+ )
+ if result.returncode != 0:
+ raise RuntimeError(f"Failed to clone VHS fork: {result.stderr}")
+
+ # Build
+ print(f"Building VHS...")
+ result = subprocess.run(
+ ["go", "build", "-o", "vhs", "."],
+ cwd=vhs_dir,
+ capture_output=True,
+ text=True,
+ )
+ if result.returncode != 0:
+ raise RuntimeError(f"Failed to build VHS: {result.stderr}")
+
+ # Verify
+ result = subprocess.run(
+ [str(vhs_binary), "--version"],
+ capture_output=True,
+ text=True,
+ check=False,
+ )
+ if result.returncode != 0:
+ raise RuntimeError(f"VHS built but --version failed: {result.stderr}")
+
+ print(f"✓ VHS ready")
+ return vhs_binary
+
# Shared content for demos
VALIDATION_RS = """//! Input validation utilities.
@@ -302,13 +455,12 @@ def setup_claude_code_config(
)
)
- # Copy claude binary to prevent "installMethod is native" warnings
+ # Copy claude binary (downloaded automatically if missing)
# Claude Code detects native install by checking if ~/.local/bin/claude exists
local_bin = env.home / ".local" / "bin"
local_bin.mkdir(parents=True, exist_ok=True)
- real_claude = REAL_HOME / ".local" / "bin" / "claude"
- if real_claude.exists():
- shutil.copy(real_claude.resolve(), local_bin / "claude")
+ claude_binary = _ensure_claude_binary()
+ shutil.copy(claude_binary, local_bin / "claude")
# Claude settings.json
claude_dir = env.home / ".claude"
@@ -328,23 +480,20 @@ def setup_zellij_config(env: DemoEnv, default_cwd: str = None) -> None:
"""Set up Zellij configuration for demo recording.
Creates config with warm-gold theme, minimal keybinds, and tab-rename plugin.
- Copies plugins from real HOME if available.
+ Plugin is downloaded automatically if missing.
Args:
env: Demo environment
default_cwd: Optional default working directory for new panes
"""
- real_zellij_plugins = REAL_HOME / ".config" / "zellij" / "plugins"
-
zellij_config_dir = env.home / ".config" / "zellij"
zellij_config_dir.mkdir(parents=True, exist_ok=True)
zellij_plugins_dir = zellij_config_dir / "plugins"
zellij_plugins_dir.mkdir(exist_ok=True)
- # Copy Zellij plugins from real HOME
- if real_zellij_plugins.exists():
- for plugin in real_zellij_plugins.glob("*.wasm"):
- shutil.copy(plugin, zellij_plugins_dir / plugin.name)
+ # Copy Zellij plugin (downloaded automatically if missing)
+ plugin_path = _ensure_zellij_plugin()
+ shutil.copy(plugin_path, zellij_plugins_dir / "zellij-tab-name.wasm")
default_cwd_line = f'default_cwd "{default_cwd}"' if default_cwd else ""