Add VHS session recording commands

Author: pproenca

README.md

@@ -76,6 +76,19 @@ agent-tui wait "Loading complete"
 agent-tui kill
 ```
 
+### Session Recording (VHS)
+
+```bash
+# Record active session (background)
+agent-tui sessions record
+
+# Record active session to a directory
+agent-tui sessions record -o docs/recordings
+
+# Stop recording for a specific session
+agent-tui --session <id> sessions record stop
+```
+
 ## CLI Reference
 
 For the full CLI reference (auto-generated from clap), see `docs/cli/agent-tui.md`.
@@ -128,6 +141,8 @@ agent-tui screenshot --json
 | `AGENT_TUI_API_LISTEN` / `AGENT_TUI_API_ALLOW_REMOTE` / `AGENT_TUI_API_STATE` | Deprecated aliases for WS settings | - |
 | `AGENT_TUI_API_TOKEN` | Deprecated and ignored | - |
 | `AGENT_TUI_SESSION_STORE` | Session metadata log path | `~/.agent-tui/sessions.jsonl` |
+| `AGENT_TUI_RECORD_STATE` | Recording state file path | `~/.agent-tui/recordings.json` |
+| `AGENT_TUI_RECORDINGS_DIR` | Default recordings output directory | current working directory |
 | `AGENT_TUI_UI_URL` | External UI URL | - |
 | `AGENT_TUI_DETACH_KEYS` | Attach detach key sequence | `Ctrl+]` |
 | `AGENT_TUI_LOG` | Log file path (optional) | - |

cli/crates/agent-tui/src/app/commands.rs

@@ -45,6 +45,8 @@ CONFIGURATION:
     AGENT_TUI_API_LISTEN / AGENT_TUI_API_ALLOW_REMOTE / AGENT_TUI_API_STATE
                               Deprecated aliases for WS settings
     AGENT_TUI_SESSION_STORE     Session metadata log path (default: ~/.agent-tui/sessions.jsonl)
+    AGENT_TUI_RECORD_STATE      Recording state file path (default: ~/.agent-tui/recordings.json)
+    AGENT_TUI_RECORDINGS_DIR    Default recordings output directory (default: current directory)
     AGENT_TUI_LOG               Log file path (optional)
     AGENT_TUI_LOG_FORMAT        Log format (text or json; default: text)
     AGENT_TUI_LOG_STREAM        Log output stream (stderr or stdout; default: stderr)
@@ -302,6 +304,7 @@ MODES:
     list              List active sessions (default)
     show <id>         Show details for a session
     attach            Attach with TTY (defaults to --session or active)
+    record            Record session activity to VHS artifacts
     switch <id>       Set the active session
     cleanup [--all]   Remove dead/orphaned sessions")]
     #[command(after_long_help = "\
@@ -313,6 +316,10 @@ EXAMPLES:
     agent-tui -s abc123 sessions attach   # Attach to session by id (TTY)
     agent-tui sessions switch abc123      # Set active session
     agent-tui -s abc123 sessions attach -T # Attach without TTY (stream output only)
+    agent-tui sessions record             # Record active session in background
+    agent-tui sessions record --foreground
+    agent-tui sessions record -o docs/recordings
+    agent-tui -s abc123 sessions record stop
     agent-tui sessions attach --detach-keys 'ctrl-]'  # Custom detach sequence
     agent-tui sessions cleanup            # Remove dead sessions
     agent-tui sessions cleanup --all      # Remove all sessions")]
@@ -441,6 +448,45 @@ pub enum SessionsCommand {
         detach_keys: Option<DetachKeys>,
     },
 
+    /// Record a running session to VHS artifacts (.gif + .tape)
+    #[command(long_about = "\
+Record a running session to VHS artifacts.
+
+By default recording starts in background and returns immediately.
+Use --foreground to wait until recording exits.
+
+OUTPUT PATH RULES:
+    -o/--output-file omitted     Uses AGENT_TUI_RECORDINGS_DIR or current directory
+    Existing directory           Creates timestamped <session>-<time>.gif/.tape
+    Existing file                Uses file stem for .gif/.tape pair
+    Non-existing path w/ ext     Treated as file path
+    Non-existing path no ext     Treated as directory")]
+    #[command(after_long_help = "\
+EXAMPLES:
+    agent-tui sessions record
+    agent-tui sessions record --foreground
+    agent-tui sessions record -o docs/recordings
+    agent-tui sessions record -o docs/recordings/demo.gif
+    agent-tui sessions record stop")]
+    #[command(args_conflicts_with_subcommands = true)]
+    Record {
+        /// Output file or directory for recording artifacts
+        #[arg(
+            short = 'o',
+            long = "output-file",
+            value_name = "PATH",
+            value_hint = ValueHint::AnyPath
+        )]
+        output_file: Option<PathBuf>,
+
+        /// Run recorder in foreground (wait until recording exits)
+        #[arg(long)]
+        foreground: bool,
+
+        #[command(subcommand)]
+        command: Option<RecordCommand>,
+    },
+
     /// Set the active session without attaching
     #[command(alias = "select")]
     Switch {
@@ -456,6 +502,12 @@ pub enum SessionsCommand {
     },
 }
 
+#[derive(Debug, Subcommand)]
+pub enum RecordCommand {
+    /// Stop recording for the selected or active session
+    Stop,
+}
+
 #[derive(Debug, Subcommand)]
 pub enum LiveCommand {
     /// Show the live preview API details
@@ -874,6 +926,69 @@ mod tests {
         ));
     }
 
+    #[test]
+    fn test_sessions_record_defaults() {
+        let cli = Cli::parse_from(["agent-tui", "sessions", "record"]);
+        let Commands::Sessions { command } = cli.command else {
+            panic!("Expected Sessions command, got {:?}", cli.command);
+        };
+        assert!(matches!(
+            command,
+            Some(SessionsCommand::Record {
+                output_file: None,
+                foreground: false,
+                command: None
+            })
+        ));
+    }
+
+    #[test]
+    fn test_sessions_record_foreground() {
+        let cli = Cli::parse_from(["agent-tui", "sessions", "record", "--foreground"]);
+        let Commands::Sessions { command } = cli.command else {
+            panic!("Expected Sessions command, got {:?}", cli.command);
+        };
+        assert!(matches!(
+            command,
+            Some(SessionsCommand::Record {
+                foreground: true,
+                command: None,
+                ..
+            })
+        ));
+    }
+
+    #[test]
+    fn test_sessions_record_output_file() {
+        let cli = Cli::parse_from(["agent-tui", "sessions", "record", "-o", "out.gif"]);
+        let Commands::Sessions { command } = cli.command else {
+            panic!("Expected Sessions command, got {:?}", cli.command);
+        };
+        assert!(matches!(
+            command,
+            Some(SessionsCommand::Record {
+                output_file: Some(_),
+                foreground: false,
+                command: None
+            })
+        ));
+    }
+
+    #[test]
+    fn test_sessions_record_stop() {
+        let cli = Cli::parse_from(["agent-tui", "sessions", "record", "stop"]);
+        let Commands::Sessions { command } = cli.command else {
+            panic!("Expected Sessions command, got {:?}", cli.command);
+        };
+        assert!(matches!(
+            command,
+            Some(SessionsCommand::Record {
+                command: Some(RecordCommand::Stop),
+                ..
+            })
+        ));
+    }
+
     #[test]
     fn test_sessions_cleanup() {
         let cli = Cli::parse_from(["agent-tui", "sessions", "cleanup"]);