Add session replay functionality to tmux-viewer

- Add replay mode with play/pause (Space), speed controls (+/-), restart (r)
- Support --replay flag to start in replay mode automatically
- Auto-advance through captures chronologically like a video player
- Speed options: 0.5s, 1.0s, 1.5s, 2.0s, 3.0s, 5.0s per capture
- Fix session-loader to find captures in captures/ subdirectory
- Update knowledge files with tmux helper scripts documentation

Author: brandonkachen

.agents/tmux-viewer/README.md

@@ -8,6 +8,9 @@ Interactive TUI for viewing tmux session logs. Designed to work for **both human
 # Interactive TUI (for humans)
 bun .agents/tmux-viewer/index.tsx <session-name>
 
+# Start in replay mode (auto-plays through captures like a video)
+bun .agents/tmux-viewer/index.tsx <session-name> --replay
+
 # JSON output (for AIs)
 bun .agents/tmux-viewer/index.tsx <session-name> --json
 
@@ -30,12 +33,38 @@ cd .agents && bun run view-session <session-name>
 - **Timeline panel**: Navigate through captures with ↑↓ arrows
 - **Capture panel**: View terminal output at each point in time
 - **Metadata display**: Session info, dimensions, command count
+- **Replay mode**: Auto-play through captures like a video player
 - **Keyboard shortcuts**:
-  - `↑↓` or `jk`: Navigate captures
+  - `Space`: Play/pause replay
+  - `+` / `-`: Adjust playback speed (faster/slower)
+  - `r`: Restart from beginning
+  - `↑↓` or `jk`: Navigate captures (pauses replay)
   - `←→` or `hl`: Switch panels
   - `q` or Ctrl+C: Quit
   - Use the `--json` flag on the CLI entrypoint for JSON output
 
+### Replay Mode
+
+Replay mode auto-advances through captures chronologically, like a video player:
+
+```bash
+# Start replay immediately
+bun .agents/tmux-viewer/index.tsx my-session --replay
+
+# Or press Space in the TUI to start/stop replay
+```
+
+**Playback controls:**
+- `Space` - Toggle play/pause
+- `+` or `=` - Speed up (shorter interval between captures)
+- `-` or `_` - Slow down (longer interval between captures)
+- `r` - Restart from the first capture
+- Arrow keys - Manual navigation (automatically pauses replay)
+
+**Available speeds:** 0.5s, 1.0s, 1.5s (default), 2.0s, 3.0s, 5.0s per capture
+
+The footer shows the current position (e.g., `3/10`), playback speed (e.g., `@1.5s`), and play/pause status.
+
 ### For AIs (JSON Output)
 Use the `--json` flag to get structured output:
 

.agents/tmux-viewer/components/session-viewer.tsx

@@ -2,12 +2,12 @@
  * SessionViewer - Interactive TUI for viewing tmux session data
  *
  * Designed to be simple and predictable for both humans and AIs:
- * - Humans: navigate captures with arrow keys / vim keys
+ * - Humans: navigate captures with arrow keys / vim keys, or use replay mode
  * - AIs: typically use the --json flag on the CLI entrypoint instead of the TUI
  */
 
 import { TextAttributes } from '@opentui/core'
-import React, { useEffect, useState } from 'react'
+import React, { useCallback, useEffect, useRef, useState } from 'react'
 
 import { getTheme } from './theme'
 
@@ -22,11 +22,20 @@ interface SessionViewerProps {
    * For now, AIs should call the CLI with --json instead.
    */
   onJsonOutput?: () => void
+  /**
+   * Start in replay mode (auto-playing through captures)
+   */
+  startInReplayMode?: boolean
 }
 
+// Available playback speeds (seconds per capture)
+const PLAYBACK_SPEEDS = [0.5, 1.0, 1.5, 2.0, 3.0, 5.0]
+const DEFAULT_SPEED_INDEX = 2 // 1.5 seconds
+
 export const SessionViewer: React.FC<SessionViewerProps> = ({
   data,
   onExit,
+  startInReplayMode = false,
 }) => {
   const theme = getTheme()
   const captures = data.captures
@@ -38,7 +47,57 @@ export const SessionViewer: React.FC<SessionViewerProps> = ({
     'timeline',
   )
 
-  // Keyboard input handling (q/Ctrl+C to quit, arrows + vim keys to navigate)
+  // Replay state
+  const [isPlaying, setIsPlaying] = useState(startInReplayMode)
+  const [speedIndex, setSpeedIndex] = useState(DEFAULT_SPEED_INDEX)
+  const playbackSpeed = PLAYBACK_SPEEDS[speedIndex]
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  // Auto-advance effect for replay mode
+  useEffect(() => {
+    if (!isPlaying || captures.length === 0) {
+      return
+    }
+
+    timerRef.current = setTimeout(() => {
+      setSelectedIndex((prev) => {
+        const next = prev + 1
+        if (next >= captures.length) {
+          // Reached the end, stop playing
+          setIsPlaying(false)
+          return prev
+        }
+        return next
+      })
+    }, playbackSpeed * 1000)
+
+    return () => {
+      if (timerRef.current) {
+        clearTimeout(timerRef.current)
+        timerRef.current = null
+      }
+    }
+  }, [isPlaying, selectedIndex, playbackSpeed, captures.length])
+
+  // Replay control functions
+  const togglePlay = useCallback(() => {
+    if (captures.length === 0) return
+    // If at end and pressing play, restart from beginning
+    if (!isPlaying && selectedIndex >= captures.length - 1) {
+      setSelectedIndex(0)
+    }
+    setIsPlaying((prev) => !prev)
+  }, [captures.length, isPlaying, selectedIndex])
+
+  const increaseSpeed = useCallback(() => {
+    setSpeedIndex((prev) => Math.max(0, prev - 1)) // Lower index = faster
+  }, [])
+
+  const decreaseSpeed = useCallback(() => {
+    setSpeedIndex((prev) => Math.min(PLAYBACK_SPEEDS.length - 1, prev + 1))
+  }, [])
+
+  // Keyboard input handling (q/Ctrl+C to quit, arrows + vim keys to navigate, space for play/pause)
   useEffect(() => {
     const handleKey = (key: string) => {
       // Quit: q or Ctrl+C
@@ -47,18 +106,49 @@ export const SessionViewer: React.FC<SessionViewerProps> = ({
         return
       }
 
+      // Space: toggle play/pause
+      if (key === ' ') {
+        togglePlay()
+        return
+      }
+
+      // +/= : increase speed (faster)
+      if (key === '+' || key === '=') {
+        increaseSpeed()
+        return
+      }
+
+      // -/_ : decrease speed (slower)
+      if (key === '-' || key === '_') {
+        decreaseSpeed()
+        return
+      }
+
+      // r: restart from beginning
+      if (key === 'r') {
+        setSelectedIndex(0)
+        return
+      }
+
       if (captures.length === 0) {
         return
       }
 
+      // Stop playback on manual navigation
+      const stopAndNavigate = () => {
+        setIsPlaying(false)
+      }
+
       // Up: arrow up or k
       if (key === '\x1b[A' || key === 'k') {
+        stopAndNavigate()
         setSelectedIndex((prev) => Math.max(0, prev - 1))
         return
       }
 
       // Down: arrow down or j
       if (key === '\x1b[B' || key === 'j') {
+        stopAndNavigate()
         setSelectedIndex((prev) =>
           Math.min(captures.length - 1, Math.max(0, prev + 1)),
         )
@@ -94,7 +184,7 @@ export const SessionViewer: React.FC<SessionViewerProps> = ({
         stdin.removeListener('data', onData as any)
       }
     }
-  }, [captures.length, onExit])
+  }, [captures.length, onExit, togglePlay, increaseSpeed, decreaseSpeed])
 
   const selectedCapture: Capture | undefined =
     selectedIndex >= 0 && selectedIndex < captures.length
@@ -136,8 +226,14 @@ export const SessionViewer: React.FC<SessionViewerProps> = ({
         />
       </box>
 
-      {/* Footer / help text */}
-      <Footer theme={theme} />
+      {/* Footer / help text with replay controls */}
+      <Footer
+        theme={theme}
+        isPlaying={isPlaying}
+        playbackSpeed={playbackSpeed}
+        currentIndex={selectedIndex}
+        totalCaptures={captures.length}
+      />
     </box>
   )
 }
@@ -369,25 +465,52 @@ const CapturePanel: React.FC<{
   )
 }
 
-// Footer component with help text
-const Footer: React.FC<{ theme: ViewerTheme }> = ({ theme }) => {
+// Footer component with help text and replay controls
+const Footer: React.FC<{
+  theme: ViewerTheme
+  isPlaying: boolean
+  playbackSpeed: number
+  currentIndex: number
+  totalCaptures: number
+}> = ({ theme, isPlaying, playbackSpeed, currentIndex, totalCaptures }) => {
+  const position = totalCaptures > 0 ? `${currentIndex + 1}/${totalCaptures}` : '0/0'
+  const speedDisplay = `${playbackSpeed.toFixed(1)}s`
+  const playIcon = isPlaying ? '⏸' : '▶'
+
   return (
     <box
       style={{
         flexDirection: 'row',
-        justifyContent: 'center',
+        justifyContent: 'space-between',
         borderStyle: 'single',
         borderColor: theme.border,
         paddingLeft: 1,
         paddingRight: 1,
-        gap: 2,
       }}
       border={['top']}
     >
-      <text style={{ fg: theme.muted }}>↑↓ / jk navigate</text>
-      <text style={{ fg: theme.muted }}>←→ / hl panels</text>
-      <text style={{ fg: theme.muted }}>q or Ctrl+C: quit</text>
-      <text style={{ fg: theme.muted }}>use --json for JSON output</text>
+      {/* Left: Replay status */}
+      <box style={{ flexDirection: 'row', gap: 1 }}>
+        <text style={{ fg: isPlaying ? theme.success : theme.muted }}>
+          {playIcon}
+        </text>
+        <text style={{ fg: theme.foreground }}>{position}</text>
+        <text style={{ fg: theme.muted }}>@{speedDisplay}</text>
+      </box>
+
+      {/* Center: Key hints */}
+      <box style={{ flexDirection: 'row', gap: 2 }}>
+        <text style={{ fg: theme.muted }}>space: play/pause</text>
+        <text style={{ fg: theme.muted }}>+/-: speed</text>
+        <text style={{ fg: theme.muted }}>↑↓: navigate</text>
+        <text style={{ fg: theme.muted }}>r: restart</text>
+        <text style={{ fg: theme.muted }}>q: quit</text>
+      </box>
+
+      {/* Right: Mode indicator */}
+      <box>
+        <text style={{ fg: theme.muted }}>--json for AI</text>
+      </box>
     </box>
   )
 }

.agents/tmux-viewer/index.tsx

@@ -6,6 +6,7 @@
  * Usage:
  *   bun .agents/tmux-viewer/index.tsx <session-name>
  *   bun .agents/tmux-viewer/index.tsx <session-name> --json
+ *   bun .agents/tmux-viewer/index.tsx <session-name> --replay
  *   bun .agents/tmux-viewer/index.tsx --list
  * 
  * Both humans and AIs can use this tool:
@@ -26,6 +27,7 @@ interface ParsedArgs {
   session: string | null
   json: boolean
   list: boolean
+  replay: boolean
 }
 
 function parseArgs(): ParsedArgs {
@@ -37,6 +39,7 @@ function parseArgs(): ParsedArgs {
     .version('0.0.1')
     .option('--json', 'Output session data as JSON (for AI consumption)')
     .option('--list', 'List available sessions')
+    .option('--replay', 'Start in replay mode (auto-playing through captures)')
     .argument('[session]', 'Session name to view')
     .parse(process.argv)
 
@@ -47,11 +50,12 @@ function parseArgs(): ParsedArgs {
     session: args[0] ?? null,
     json: options.json ?? false,
     list: options.list ?? false,
+    replay: options.replay ?? false,
   }
 }
 
 async function main(): Promise<void> {
-  const { session, json, list } = parseArgs()
+  const { session, json, list, replay } = parseArgs()
   const projectRoot = process.cwd()
 
   // List sessions mode
@@ -90,15 +94,16 @@ async function main(): Promise<void> {
     // Use the most recent session
     const mostRecent = sessions[0]
     console.log(dim(`Using most recent session: ${mostRecent}`))
-    return runViewer(mostRecent, json, projectRoot)
+    return runViewer(mostRecent, json, replay, projectRoot)
   }
 
-  return runViewer(session, json, projectRoot)
+  return runViewer(session, json, replay, projectRoot)
 }
 
 async function runViewer(
   sessionName: string,
   jsonMode: boolean,
+  replayMode: boolean,
   projectRoot: string
 ): Promise<void> {
   // Load session data
@@ -149,6 +154,7 @@ async function runViewer(
       data={data}
       onExit={handleExit}
       onJsonOutput={handleJsonOutput}
+      startInReplayMode={replayMode}
     />
   )
 }