rewind is a per-project command history tool for your shell. It records the commands you run, where you ran them, their Git repository and branch context, exit status, duration, and timestamp, then lets you search that history from the terminal.

Install

Run the installer:

curl -fsSL https://raw.githubusercontent.com/oscarmuya/rewind/main/install.sh | sh

Then enable shell recording:

rw init --install

Restart your shell, or source your shell startup file, and you are ready to go.

Quick Start

Once installed, your commands are recorded automatically. Open the picker to replay any recent command:

rw

Search your history:

rw search cargo

Replay the most recent command directly:

rw -1

Save a command you run often as a shortcut:

rw shortcut add test cargo test
rw test

Replaying Recent Commands

Run rw to open the recent-command picker:

rw

Replay the Nth most recent command directly (after applying any filters):

rw -1
rw -2 --repo --ok
rw -3 --plain

The command is printed before it runs. With --plain, it is only printed.

Print recent history without opening the TUI:

rw --plain
rw --plain --limit 20

Filter recent history by Git context or exit status:

rw --repo       # limit to the current Git repository
rw --cwd        # limit to the current directory
rw --branch     # limit to the current Git branch
rw --ok         # only successful commands
rw --fail       # only failed commands
rw --deleted    # show soft-deleted commands

Filters can be combined:

rw --repo --branch --fail --limit 10

TUI controls:

• Up/Down or k/j to move between commands
• / to enter search mode and type to filter
• in search mode, Up/Down to navigate, Esc to clear and return to the list
• Enter or click to open a command in the replay editor
• edit the command, then Enter to run it
• Alt+Enter in the editor to insert a newline for multiline commands
• Esc in the editor to cancel and return to the list
• Esc or Ctrl-C in the list to exit without running anything
• dd to soft-delete a command; x to show deleted commands, dd to restore one

Searching History

Open the TUI directly in search mode:

rw search

Start with an initial query:

rw search cargo

Print plain matches to stdout instead of opening the TUI:

rw search cargo --plain
rw search cargo --plain --limit 20

Shortcuts

Save frequently used commands as short aliases scoped to the current project:

rw shortcut add test cargo test
rw shortcut add lint cargo clippy --workspace --all-targets

Run a saved shortcut by passing its alias to rw:

rw test
rw lint

Rewind prints the expanded command to stderr before running it.

Create a shortcut available from any project with --global:

rw shortcut add --global gs git status --short
rw gs

Open the shortcut manager TUI for the current project:

rw shortcut

Use Enter to edit, dd to delete, and q or Esc to close.

Other shortcut commands:

rw shortcut list                              # list shortcuts for this project
rw shortcut list --global                     # list only global shortcuts
rw shortcut edit test cargo test --workspace  # edit a shortcut
rw shortcut edit --global gs git status --branch
rw shortcut remove test                       # remove a shortcut
rw shortcut remove gs --global

Project shortcuts take precedence over global ones with the same alias. Reserved subcommand names (search, status, shortcut, etc.) cannot be used as shortcut aliases.

Manual Recording

Record a single command without shell hooks:

rw run cargo test
rw run git status --short

rw run executes the command, records it, and exits with the same exit code. It does not run through a shell, so use sh -c for pipes, redirects, variables, or glob expansion:

rw run sh -c 'rg TODO | wc -l'

Checking Status

Run rw status to verify that automatic recording is set up and healthy:

rw status

It checks:

• shell integration installation for your detected shell
• whether the integration is active in the current session
• required tools (python3 and socat)
• whether rw-daemon is accepting connections
• whether the SQLite history database opens and passes an integrity check

You can also check a specific shell:

rw status bash
rw status zsh
rw status fish

If the hook is installed but the runtime check warns it is not visible, restart your shell or source your startup file. If the daemon check fails, opening a new hooked shell usually starts rw-daemon; you can also run rw-daemon directly to debug.

What Gets Recorded

Each history entry stores:

• command line
• current working directory
• Git repository root (when available)
• Git branch (when available)
• exit code
• duration in milliseconds
• start timestamp

Rewind stores metadata about commands, not command output. Command lines can still contain sensitive values, so avoid putting secrets directly in commands if you do not want them saved in local history.

Data Storage

On Linux, history is stored under:

${XDG_DATA_HOME:-$HOME/.local/share}/rewind/

The main files are:

• history.db: SQLite database containing command history and shortcuts
• rewind.sock: Unix socket used by rw-daemon

The database uses SQLite WAL mode. Removing history.db deletes all recorded history.

Shell Integration Details

The shell integration starts rw-daemon when needed, sends command metadata after each command finishes, and skips rw and rw-daemon commands to avoid recording rewind's own activity.

Install for your current shell:

rw init --install

Or choose a shell explicitly:

rw init bash --install
rw init zsh --install
rw init fish --install

The installer writes a managed block to:

• bash: ~/.bashrc
• zsh: ~/.zshrc
• fish: $XDG_CONFIG_HOME/fish/config.fish or ~/.config/fish/config.fish

To inspect the snippet without installing:

rw init zsh

To remove the managed block:

rw init --uninstall

Requirements

• Unix-like system with Unix domain sockets
• curl and tar for the release installer
• python3 and socat for shell integrations
• one of bash, zsh, or fish for automatic recording

Current Limitations

• Shell integrations require python3 and socat.
• The daemon communicates over a Unix domain socket, so Windows is not currently supported.

---

Installing From Source

Requires a Rust toolchain with Cargo.

Clone the repository, then install both binaries:

cargo install --path rewind-cli
cargo install --path rewind-daemon

Make sure Cargo's binary directory is on your PATH:

export PATH="$HOME/.cargo/bin:$PATH"

You can also run the tools from the repository without installing:

cargo run --bin rw -- --help
cargo run --bin rw-daemon

CLI Reference

Short flags: -l (limit), -p (plain), -c (cwd), -r (repo), -b (branch), -o (ok), -f (fail), -d (deleted). Init supports -i (install) and -u (uninstall). Shortcut commands support -g (global).

Development

This is a Cargo workspace with three crates:

• rewind-core: shared database, query, entry, Git, and socket logic
• rewind-cli: rw CLI and TUI
• rewind-daemon: background Unix socket daemon

Useful commands:

cargo fmt --all
cargo test --workspace
cargo clippy --workspace --all-targets
cargo run --bin rw -- --help

Shell integration smoke-test helpers are in tests/shell/:

tests/shell/bash.sh
tests/shell/zsh.sh
tests/shell/fish.sh