timescale · murrayju · Mar 17, 2026 · Mar 17, 2026
@@ -21,7 +21,7 @@ ox config
 
 The wizard walks through sandbox provider, agent, model, and authentication setup. It writes to the project config file (`.ox/config.yml`).
 
-<!-- screenshot: docs/assets/config-wizard.gif -->
+<!-- screenshot: docs/images/config-wizard.gif -->
 
 ## Config Keys
 

@@ -1,6 +1,6 @@
 # VHS Tape Files
 
-This directory contains [VHS](https://github.com/charmbracelet/vhs) tape files for generating GIF screenshots of the ox TUI. The generated GIFs are saved to `docs/assets/`.
+This directory contains [VHS](https://github.com/charmbracelet/vhs) tape files for generating GIF screenshots of the ox TUI. The generated GIFs are saved to `docs/images/`.
 
 ## Prerequisites
 
@@ -36,7 +36,7 @@ Or run a single tape:
 vhs docs/tapes/prompt-screen.tape
 ```
 
-Generated GIFs are written to `docs/assets/`.
+Generated GIFs are written to `docs/images/`.
 
 ## Tape Files
 

@@ -10,16 +10,51 @@ set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+TMP_DIR="$(mktemp -d)"
+VHS_CONFIG_DIR="$TMP_DIR/ox-config"
+cleanup() {
+  rm -rf "$TMP_DIR"
+}
+trap cleanup EXIT
+if command -v vhs >/dev/null 2>&1; then
+  VHS_BIN="$(command -v vhs)"
+elif [ -x "$HOME/.local/bin/vhs" ]; then
+  VHS_BIN="$HOME/.local/bin/vhs"
+else
+  echo "Error: vhs not found on PATH or at \$HOME/.local/bin/vhs" >&2
+  exit 1
+fi
+
+if command -v chromium >/dev/null 2>&1; then
+  CHROMIUM_BIN="$(command -v chromium)"
+elif command -v chromium-browser >/dev/null 2>&1; then
+  CHROMIUM_BIN="$(command -v chromium-browser)"
+else
+  echo "Error: chromium not found on PATH" >&2
+  exit 1
+fi
+
+mkdir -p "$REPO_ROOT/docs/images"
+mkdir -p "$VHS_CONFIG_DIR"
 
-mkdir -p "$REPO_ROOT/docs/assets"
+cat >"$TMP_DIR/chromium" <<EOF
+#!/bin/sh
+exec "$CHROMIUM_BIN" --no-sandbox "\$@"
+EOF
+chmod +x "$TMP_DIR/chromium"
 
 run_tape() {
   local tape="$1"
   local name
   name="$(basename "$tape" .tape)"
   echo "Generating $name.gif..."
-  (cd "$REPO_ROOT" && vhs "$tape")
-  echo "  -> docs/assets/$name.gif"
+  (
+    cd "$REPO_ROOT" &&
+      PATH="$TMP_DIR:$REPO_ROOT:$PATH" \
+      OX_USER_CONFIG_DIR="$VHS_CONFIG_DIR" \
+      "$VHS_BIN" "$tape"
+  )
+  echo "  -> docs/images/$name.gif"
 }
 
 if [ $# -gt 0 ]; then

@@ -1,7 +1,7 @@
 # Prompt Screen
 # Shows the main TUI prompt screen with agent badge, model, and readiness indicators.
 
-Output docs/assets/prompt-screen.gif
+Output docs/images/prompt-screen.gif
 
 Set Shell bash
 Set Width 1000

@@ -1,7 +1,7 @@
 # Sessions List
 # Shows the sessions list view with session entries and filter controls.
 
-Output docs/assets/sessions-list.gif
+Output docs/images/sessions-list.gif
 
 Set Shell bash
 Set Width 1200

@@ -1,7 +1,7 @@
 # Slash Commands
 # Shows the slash command popover appearing when typing "/" in the prompt.
 
-Output docs/assets/slash-commands.gif
+Output docs/images/slash-commands.gif
 
 Set Shell bash
 Set Width 1000

@@ -1,7 +1,7 @@
 # Start Task
 # Shows starting a task from the CLI in follow mode.
 
-Output docs/assets/start-task.gif
+Output docs/images/start-task.gif
 
 Set Shell bash
 Set Width 1000

@@ -1,7 +1,7 @@
 # Theme Picker
 # Shows the theme picker with live preview of different themes.
 
-Output docs/assets/theme-picker.gif
+Output docs/images/theme-picker.gif
 
 Set Shell bash
 Set Width 1000

@@ -18,7 +18,7 @@ The TUI has several views. Navigate between them with keyboard shortcuts or the
 
 The main input area where you write task descriptions for the agent.
 
-<!-- screenshot: docs/assets/prompt-screen.gif -->
+![Prompt screen showing the main TUI input view](images/prompt-screen.gif)
 
 **Elements:**
 - **Text area** -- Multi-line input with the placeholder "Ask anything... Type '/' for commands"
@@ -53,7 +53,7 @@ The main input area where you write task descriptions for the agent.
 
 Browse and manage all sessions across providers.
 
-<!-- screenshot: docs/assets/sessions-list.gif -->
+![Sessions list showing filters and session entries](images/sessions-list.gif)
 
 **Keyboard shortcuts:**
 
@@ -131,7 +131,7 @@ Manage sandbox images, volumes, and snapshots.
 
 Press `ctrl+p` from any view to open the command palette -- a fuzzy-searchable list of all available actions.
 
-<!-- screenshot: docs/assets/command-palette.gif -->
+<!-- screenshot: docs/images/command-palette.gif -->
 
 The palette shows each command's name, description, keyboard shortcut, and category. Type to filter, use arrow keys to navigate, and press `Enter` to execute.
 
@@ -159,15 +159,15 @@ Type `/` in an empty prompt to open the slash command popover. Slash commands ar
 | `/plan` | Switch to plan mode |
 | `/feedback` | Send feedback to the ox team |
 
-<!-- screenshot: docs/assets/slash-commands.gif -->
+![Slash command popover filtered from the prompt screen](images/slash-commands.gif)
 
 Type a partial name to fuzzy-filter the list. Press `Enter` to execute or `Escape` to dismiss.
 
 ## Themes
 
 Ox ships with 33 built-in color themes. Change the theme with `/theme` or `ctrl+t` from the prompt screen.
 
-<!-- screenshot: docs/assets/theme-picker.gif -->
+![Theme picker with live preview while browsing themes](images/theme-picker.gif)
 
 Available themes:
 

@@ -27,6 +27,8 @@ Stream the agent's output to your terminal in real time:
 ox -f "Fix the failing integration tests"
 ```
 
+![Follow mode streaming a task in the terminal](images/start-task.gif)
+
 The process exits with the agent's exit code when the session finishes. Useful when you want to watch the agent work without the full TUI.
 
 ### Interactive TUI (`-i`)