Session Replay

The suv replay command shows a chronological timeline of your commands, giving you a linear playback of what happened in your terminal. Combined with suv session, you can browse and inspect individual sessions interactively.

Basic Usage

Replay the most recent commands in chronological order:

suv replay

Each entry shows the timestamp, command, working directory, exit code, and duration. The output is plain text, designed to be readable both in the terminal and when piped to other tools.

Command-Line Flags

Filter the replay to focus on specific time ranges, directories, or executors:

Flag	Description	Example
`--session`	Replay a specific session by ID	`suv replay --session a1b2c3d4`
`--after`	Show commands after a date or relative time	`suv replay --after today`
`--before`	Show commands before a date or relative time	`suv replay --before yesterday`
`--tag`	Filter by session tag	`suv replay --tag deploy`
`--exit-code`	Filter by exit code	`suv replay --exit-code 1`
`--executor`	Filter by executor (e.g., `claude-code`, `user`)	`suv replay --executor claude-code`
`--here`	Only show commands run in the current directory	`suv replay --here`
`--cwd`	Filter by a specific working directory path	`suv replay --cwd ~/projects/myapp`

Examples

Replay today's commands

suv replay --after today

Shows every command you ran today in chronological order, across all sessions and directories.

Replay commands in the current directory

suv replay --here

Shows the timeline of commands that were run in your current working directory, regardless of when they happened. Useful for understanding the history of a specific project.

Find yesterday's failures

suv replay --after yesterday --exit-code 1

Shows all commands from yesterday onward that exited with a non-zero exit code. Helps you retrace debugging sessions.

Replay what an AI agent did

suv replay --executor claude-code --after "1 hour ago"

Shows commands executed by Claude Code in the last hour. Essential for auditing AI agent behavior.

Replay a specific session

suv replay --session a1b2c3d4

Replays all commands from a single terminal session identified by its session ID. You can find session IDs using suv session or suv status.

Piping and Redirection

The output of suv replay is pipeable plain text. You can combine it with standard Unix tools:

# Search replay output for a specific pattern
suv replay --after today | grep "docker"

# Save a session replay to a file
suv replay --session a1b2c3d4 > session-log.txt

# Count how many commands were run today
suv replay --after today | wc -l

This makes suv replay useful for scripting, auditing, and generating reports.

Session Browser

The suv session command launches an interactive TUI for browsing your terminal sessions:

suv session

The session browser shows a list of sessions with their start time, duration, command count, and tags. Select a session to see its full command timeline.

Session Command-Line Flags

Flag	Description	Example
`[SESSION_ID]`	Jump directly to a specific session	`suv session a1b2c3d4`
`--list`	List sessions as plain text (non-interactive)	`suv session --list`
`--after`	Show sessions after a date or relative time	`suv session --after "1 week ago"`
`--tag`	Filter sessions by tag	`suv session --tag deploy`
`-n` / `--limit`	Limit the number of sessions shown	`suv session -n 10`

Session Examples

# Browse sessions from the last week
suv session --after "1 week ago"

# List the 5 most recent sessions (non-interactive)
suv session --list -n 5

# Open a specific session directly
suv session a1b2c3d4

# Find sessions tagged "deploy"
suv session --tag deploy

Tip: Each terminal tab, window, or tmux pane gets its own session ID. Sessions are created automatically when Suvadu's shell hooks detect a new shell process. You can tag sessions with suv tag <name> to make them easier to find later.