# viddy — Modern Watch Command with Diff and Time Travel

> viddy is a modern replacement for the watch command that highlights output differences, supports time-travel playback, and runs in pager mode.

## Install

Save in your project root:

# viddy — Modern Watch Command with Diff and Time Travel

## Quick Use
```bash
# Install
brew install viddy   # or: go install github.com/sachaos/viddy@latest

# Watch a command every 2 seconds with diff highlighting
viddy -d 'kubectl get pods'

# Watch with 500ms interval and time-travel enabled
viddy -n 0.5 -t 'docker ps'
# Press / to search, b to go back in time
```

## Introduction
viddy is a terminal tool that repeatedly executes a command and displays its output, similar to the classic Unix `watch` utility. It adds diff highlighting between runs, a time-travel mode that lets you scroll back through previous outputs, and a built-in pager for inspecting large results — all with a clean TUI.

## What viddy Does
- Runs any shell command at a configurable interval and displays live output
- Highlights additions, deletions, and changes between consecutive runs
- Stores output history and lets you scroll backward through past snapshots
- Supports pager mode for searching and scrolling within a single output frame
- Provides both precise (character-level) and line-level diff modes

## Architecture Overview
viddy is a single Go binary that spawns the target command in a subshell on each tick. It captures stdout and stores each snapshot in an in-memory ring buffer. A diff engine compares the current snapshot to the previous one and annotates changed regions. The TUI layer (built on tcell) renders the annotated output and handles keyboard navigation for paging, searching, and time travel.

## Self-Hosting & Configuration
- Install via Homebrew, apt, Nix, or `go install` — single binary with no dependencies
- Set the refresh interval with `-n` (supports sub-second values like `0.5`)
- Enable diff highlighting with `-d` (line-level) or `--differences=precise` (character-level)
- Activate time-travel mode with `-t` to browse previous output snapshots
- Use shell aliases to replace `watch` globally: `alias watch=viddy`

## Key Features
- Character-level and line-level diff highlighting between command runs
- Time-travel mode stores history and lets you scrub backward and forward
- Sub-second refresh intervals for monitoring fast-changing outputs
- Built-in pager with search (/) and scroll for large outputs
- Single static binary with zero runtime dependencies

## Comparison with Similar Tools
- **watch** — Classic Unix utility, no diff highlighting or history playback
- **entr** — Re-runs commands when files change, not on a timer
- **hwatch** — Rust-based watch alternative with diff mode but no time travel
- **loop** — Minimal command repeater, no TUI or diff features
- **wtfutil** — Dashboard-style terminal monitoring, different use case

## FAQ
**Q: Can viddy replace the standard watch command?**
A: Yes. It is a drop-in replacement that accepts the same `-n` interval flag and adds diff, pager, and time-travel features.

**Q: How far back can time travel go?**
A: viddy keeps output history in memory for the duration of the session. There is no fixed limit beyond available RAM.

**Q: Does viddy support color output from commands?**
A: Yes. It preserves ANSI color codes from the watched command and overlays diff highlights on top.

**Q: How do I search within the output?**
A: Press `/` to enter search mode, type a query, and press Enter. Use `n` and `N` to navigate matches.

## Sources
- https://github.com/sachaos/viddy
- https://github.com/sachaos/viddy#usage

---
Source: https://tokrepo.com/en/workflows/viddy-modern-watch-command-diff-time-travel-a9019ebf
Author: AI Open Source