sachaos/viddy: a modern watch command with a time machine mode

The gap between watch and what you actually do with it

The classic watch command does one thing: run a command every N seconds and repaint the terminal. That is fine for a clock or a disk-free counter. It falls apart the moment the interesting part is the change between two runs. You stare at the screen, look away, look back, and the line you needed has already scrolled off. Viddy is aimed at exactly that moment. The README describes it as a "Modern `watch` command" with diff highlight, a pager, and a time machine mode that lets you "Rewind like video." The intended user is someone sitting at a terminal watching something that changes: a build, a queue depth, a log tail, a test run. It is not a monitoring agent and it does not run in the background. It is a viewer.

How viddy stores and replays output

The mechanism visible in the repository is a Rust TUI built on ratatui and crossterm, with an async runtime underneath. Cargo.toml lists tokio with the full feature set, tokio-util, futures, and signal-hook, which is the shape you expect from a program that runs a child process on a timer and needs to react to Ctrl-C and terminal resize events. Output handling is where the design gets specific: the dependency list includes ansi-parser, ansi-to-tui, anstyle and anstyle-parse, plus strip-ansi-escapes, so escape sequences from the watched command are parsed rather than dumped raw. Diffing uses the similar and dissimilar crates, which is why diff highlight can be a toggle rather than a separate mode. History is persisted with rusqlite, compiled with the bundled feature, so the saved runs go into a local SQLite database rather than a flat file. That is the piece that makes the time machine mode coherent: rewind is a query against stored output, not a re-execution of the command. The README also lists a pager, vim-like keymaps, text search, suspend and restart, shell alias support and customizable colors and keymaps.

Installing viddy and watching something for the first time

The README gives several install routes. If you have a Rust toolchain, cargo is the shortest path. The README shows:

cargo install viddy

On macOS, Homebrew is the other first-class option the README lists:

brew install viddy

If you prefer a prebuilt binary, the README points at the release page, and gives a Linux example that downloads a tarball, extracts it, and moves the binary into /usr/local/bin:

wget -O viddy.tar.gz https://github.com/sachaos/viddy/releases/download/v1.3.0/viddy-v1.3.0-linux-x86_64.tar.gz && tar xvf viddy.tar.gz && mv viddy /usr/local/bin

Community-maintained packages exist too. The README documents pkg.haus for Debian, MacPorts, Scoop on Windows, AUR on Arch, apk on Alpine, and asdf. For Scoop specifically, the README notes that the git package is required before adding buckets:

scoop install git
scoop bucket add extras
scoop install extras/viddy

Once it is on your PATH, run it the way you would run watch. The README does not spell out the argument syntax in the excerpt available, so treat the basic invocation as the same shape you already know and confirm flags with the binary's own help output. What you should see is a full-screen TUI that repaints on an interval, with a header showing the command and timing, and a body showing the captured output. Press d to toggle diff highlighting, ? to open the help view, and SPACE to enter time machine mode. In time machine mode the README lists Shift-J and Shift-K to move to the past and back to the future, Shift-F and Shift-B for larger jumps, Shift-O for the oldest position and Shift-N for the current one. Press s to suspend execution and b to toggle the terminal bell.

Configuring keymaps and shell behavior in viddy.toml

Viddy runs with no configuration at all, which is the right default for a tool like this. When you do want to change something, the README places the config at $XDG_CONFIG_HOME/viddy.toml, or on macOS at ~/Library/Application Support/viddy.toml. The documented structure has three tables: general, keymap and color. The general table is where shell behavior lives, with keys for no_shell, shell, shell_options, skip_empty_diffs and disable_mouse. The keymap table overrides individual bindings, and the README's example rebinds the time machine movement keys to arrow keys and changes the pager scroll keys. The color table has a background key, and the README notes the default is inherited from the terminal color. A trimmed example from the README:

[general]
no_shell = false
shell = "zsh"
skip_empty_diffs = false

[keymap]
timemachine_go_to_past = "Down"
timemachine_go_to_more_past = "Shift-Down"
timemachine_go_to_future = "Up"
timemachine_go_to_now = "Ctrl-Shift-Up"

One thing worth flagging: the README links to a GitHub issue comment for shell alias support rather than documenting it inline. If your workflow depends on aliases, that link is the actual reference, and it is a thinner footing than the rest of the configuration documentation.

Where viddy is the wrong tool

The clearest limitation is structural: viddy is an interactive terminal UI. It needs a terminal, it needs a person, and it draws a full-screen interface. That makes it a poor fit for anything headless. If you want a command's output appended to a file and rotated, a shell loop with redirection or a logging daemon does that better, because there is no TUI to render. If you want alerting when a value crosses a threshold, viddy has no mechanism for that in the README; it displays, it does not notify. The suspend and restart keys imply a human deciding when to pause, not a scheduler. There is also a real cost to the history feature. Saved runs go into SQLite via rusqlite, which means disk usage grows with the volume and size of the output you watch. A command that prints thousands of lines every second is going to produce a database that grows quickly, and the README does not document a retention policy or a size cap. Finally, the README does not document rollback or any migration path for the stored history, so upgrading across versions is a case where you should assume the data format is the developer's concern and not yours. Treat the history as disposable.

viddy against the original watch and against terminal recorders

The obvious alternative is the watch command itself, from procps on Linux or the BSD equivalent on macOS. The difference in approach is fundamental. watch holds no state. It runs the command, paints the screen, sleeps, and repeats. There is no history, no pager, no search, and no diff. Viddy keeps state: it parses ANSI output, computes diffs between runs, stores runs in SQLite, and lets you move through that stored sequence. That is more machinery, and more machinery means more that can go wrong, but it is the machinery that makes the rewind possible. A second alternative is a terminal session recorder such as asciinema or script, which captures everything you did in a session rather than the output of one repeating command. Those tools answer a different question. They are for replaying a session for someone else; viddy is for you, right now, looking backwards through one command's output. If what you actually want is a permanent, shareable record of a session, a recorder is the correct choice and viddy is not.

Maintenance, licence and the cost of upgrading

The repository is not archived, and the last push was on 2026-08-16, so the project is being touched. The release cadence is uneven rather than steady: v1.2.1 landed on 2024-11-16, v1.3.0 on 2024-11-28, and v1.3.1 on 2026-06-14. That gap between v1.3.0 and v1.3.1 is long enough that you should not expect frequent releases. Viddy is MIT licensed, which is permissive and places few obligations on you beyond retaining the copyright notice and licence text; this is a description of the licence, not legal advice, and if you redistribute it in a product you should read the LICENSE file in the repository yourself. Upgrade cost is mostly the Cargo dependency surface. Cargo.toml pins a fairly wide set of crates, including rusqlite with the bundled SQLite feature, which means builds compile SQLite from source and take longer than a thin wrapper would. The bundled feature also means the SQLite version is whatever the crate ships, not whatever is on your system, which is a trade-off between build time and reproducibility. For a tool you install once and run interactively, that is acceptable. For a tool you build in CI on every commit, it is a real time cost.

Editorial conclusion

Adopt viddy if you already live in a terminal and want to scrub backwards through the output of a repeating command without rerunning it. Do not adopt it if you need unattended, headless monitoring: it is an interactive TUI, so it wants a terminal and a person in front of it. Before you commit, verify three things on your own machine: that your config path is $XDG_CONFIG_HOME/viddy.toml or ~/Library/Application Support/viddy.toml, that your shell alias resolves the way the linked issue describes, and that the keymap you want is listed in the README table. Nothing here is a substitute for running it once against the command you actually care about.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. sachaos/viddy on GitHub