Add YAML-based tmux session logging and OpenTUI viewer

- Update tmux helper scripts to use YAML format:
  - session-info.yaml for session metadata
  - commands.yaml for command history
  - YAML front-matter on capture files

- Create .agents/tmux-viewer/ OpenTUI package:
  - Interactive TUI for viewing session captures chronologically
  - --json flag for AI consumption (single source of truth)
  - --list flag to show available sessions
  - Timeline navigation with arrow keys

- Update cli-tmux-tester.ts to reference new viewer tool
- Update README.md with new YAML format documentation

Author: brandonkachen

.agents/cli-tmux-tester.ts

@@ -186,17 +186,52 @@ sleep 2
 
 ## Session Logs (Paper Trail)
 
-Captures are **automatically saved** to \`debug/tmux-sessions/{session-name}/\` whenever you capture output.
+All session data is stored in **YAML format** in \`debug/tmux-sessions/{session-name}/\`:
+
+- \`session-info.yaml\` - Session metadata (start time, dimensions, status)
+- \`commands.yaml\` - YAML array of all commands sent with timestamps
+- \`capture-{sequence}-{label}.txt\` - Captures with YAML front-matter
 
 \`\`\`bash
 # Capture with a descriptive label (recommended)
 ./scripts/tmux/tmux-cli.sh capture "$SESSION" --label "after-help-command" --wait 2
 
-# Capture saved to: debug/tmux-sessions/{session}/capture-{timestamp}-after-help-command.txt
+# Capture saved to: debug/tmux-sessions/{session}/capture-001-after-help-command.txt
+\`\`\`
+
+Each capture file has YAML front-matter with metadata:
+\`\`\`yaml
+---
+sequence: 1
+label: after-help-command
+timestamp: 2025-01-01T12:00:30Z
+after_command: "/help"
+dimensions:
+  width: 120
+  height: 30
+---
+[terminal content]
 \`\`\`
 
 The capture path is printed to stderr. Both you and the parent agent can read these files to see exactly what the CLI displayed.
 
+## Viewing Session Data
+
+Use the **tmux-viewer** to inspect session data interactively or as JSON:
+
+\`\`\`bash
+# Interactive TUI (for humans)
+bun .agents/tmux-viewer/index.tsx "$SESSION"
+
+# JSON output (for AIs) - includes all captures, commands, and timeline
+bun .agents/tmux-viewer/index.tsx "$SESSION" --json
+
+# List available sessions
+bun .agents/tmux-viewer/index.tsx --list
+\`\`\`
+
+The viewer parses all YAML data (session-info.yaml, commands.yaml, capture front-matter) and presents it in a unified format.
+
 ## Debugging Tips
 
 - **Attach interactively**: \`tmux attach -t SESSION_NAME\`

.agents/package.json

@@ -6,6 +6,7 @@
   "scripts": {
     "typecheck": "bun x tsc --noEmit -p tsconfig.json",
     "test": "bun test __tests__",
-    "test:e2e": "bun test e2e"
+    "test:e2e": "bun test e2e",
+    "view-session": "bun run tmux-viewer/index.tsx"
   }
 }

.agents/tmux-viewer/README.md

@@ -0,0 +1,136 @@
+# tmux-viewer
+
+Interactive TUI for viewing tmux session logs. Designed to work for **both humans and AIs**.
+
+## Usage
+
+```bash
+# Interactive TUI (for humans)
+bun .agents/tmux-viewer/index.tsx <session-name>
+
+# JSON output (for AIs)
+bun .agents/tmux-viewer/index.tsx <session-name> --json
+
+# List available sessions
+bun .agents/tmux-viewer/index.tsx --list
+
+# View most recent session (if no session specified)
+bun .agents/tmux-viewer/index.tsx
+```
+
+Or using the npm script:
+
+```bash
+cd .agents && bun run view-session <session-name>
+```
+
+## Features
+
+### For Humans (Interactive TUI)
+- **Timeline panel**: Navigate through captures with ↑↓ arrows
+- **Capture panel**: View terminal output at each point in time
+- **Metadata display**: Session info, dimensions, command count
+- **Keyboard shortcuts**:
+  - `↑↓` or `jk`: Navigate captures
+  - `←→` or `hl`: Switch panels
+  - `q` or Ctrl+C: Quit
+  - Use the `--json` flag on the CLI entrypoint for JSON output
+
+### For AIs (JSON Output)
+Use the `--json` flag to get structured output:
+
+```json
+{
+  "session": {
+    "session": "cli-test-1234567890",
+    "started": "2025-01-01T12:00:00Z",
+    "dimensions": { "width": 120, "height": 30 },
+    "status": "active"
+  },
+  "commands": [
+    { "timestamp": "...", "type": "text", "input": "/help", "auto_enter": true }
+  ],
+  "captures": [
+    {
+      "sequence": 1,
+      "label": "initial-state",
+      "timestamp": "...",
+      "after_command": null,
+      "dimensions": { "width": 120, "height": 30 },
+      "path": "debug/tmux-sessions/.../capture-001-initial-state.txt",
+      "content": "[terminal output]"
+    }
+  ],
+  "timeline": [
+    { "timestamp": "...", "type": "command", "data": {...} },
+    { "timestamp": "...", "type": "capture", "data": {...} }
+  ]
+}
+```
+
+## Data Format
+
+The viewer reads YAML-formatted session data from `debug/tmux-sessions/{session}/`:
+
+- `session-info.yaml` - Session metadata
+- `commands.yaml` - Array of commands sent
+- `capture-*.txt` - Capture files with YAML front-matter
+
+### Session Info (session-info.yaml)
+```yaml
+session: cli-test-1234567890
+started: 2025-01-01T12:00:00Z
+started_local: Wed Jan 1 12:00:00 PST 2025
+dimensions:
+  width: 120
+  height: 30
+status: active
+```
+
+### Commands (commands.yaml)
+```yaml
+- timestamp: 2025-01-01T12:00:05Z
+  type: text
+  input: "/help"
+  auto_enter: true
+```
+
+### Capture Files (capture-001-label.txt)
+```yaml
+---
+sequence: 1
+label: initial-state
+timestamp: 2025-01-01T12:00:30Z
+after_command: null
+dimensions:
+  width: 120
+  height: 30
+---
+[terminal content here]
+```
+
+## Integration with cli-tmux-tester
+
+The `@cli-tmux-tester` agent can use this viewer to inspect session data:
+
+```typescript
+// In cli-tmux-tester output
+{
+  captures: [
+    { path: "debug/tmux-sessions/cli-test-123/capture-001-initial.txt", label: "initial" }
+  ]
+}
+
+// Parent agent can view the session
+// bun .agents/tmux-viewer/index.tsx cli-test-123 --json
+```
+
+## Development
+
+```bash
+# Typecheck
+cd .agents && bun run typecheck
+
+# Run directly
+bun .agents/tmux-viewer/index.tsx --list
+```