Documentation

Commands

record

Start recording a new terminal session.

./build/rewindtty record [--interactive] [file]

Options:

  • --interactive: Enable interactive mode for real-time shell interaction
  • file: Output file path (default: data/session.json)

replay

Replay a previously recorded session with original timing.

./build/rewindtty replay [file]

analyze

Analyze a recorded session and generate comprehensive statistics.

./build/rewindtty analyze [file]

Analysis includes:

  • Total commands executed and session duration
  • Average time per command
  • Most frequently used commands
  • Slowest commands
  • Commands that generated errors or warnings
  • Optimization suggestions

Recording Modes

Interactive Mode

Best for: Full session recording and replay

  • Real-time shell interaction capture
  • Live terminal emulation during replay
  • Compatible with browser player
  • Higher memory usage
  • No session analysis available

Legacy Mode

Best for: Command analysis and optimization

  • Command-by-command capture
  • Step-by-step replay
  • Full analysis with statistics
  • Lightweight and efficient
  • Structured JSON format

Session File Format

Sessions are stored in JSON format with timing information and terminal data to enable accurate replay.

{ "version": "1.0", "timestamp": "2025-01-01T12:00:00Z", "mode": "interactive", "commands": [ { "command": "ls -la", "timestamp": 1640995200, "duration": 0.234, "output": "total 64\ndrwxr-xr-x...", "exit_code": 0 } ], "metadata": { "shell": "/bin/bash", "terminal": "xterm-256color", "user": "username" } }

Browser Player

The browser player provides enhanced features for session playback:

Dependencies

  • @xterm/xterm: Terminal emulation
  • @xterm/addon-fit: Terminal fitting addon
  • TypeScript: Type safety
  • Vite: Build tool

Building from Source

Compiler Flags

The project uses these GCC flags for optimal performance and debugging:

  • -Wall -Wextra: Enable comprehensive warnings
  • -std=gnu99: Use GNU C99 standard
  • -g: Include debugging symbols

Dependencies

  • cJSON: JSON parsing (included as submodule)
  • POSIX: System calls for terminal interaction

Clean Build

make clean && make

⚠️ Experimental Features

Interactive mode is currently experimental and may have limitations or bugs. Please report any issues on the GitHub repository.