backscroll

Purpose

backscroll solves a common pain point in terminal use: a command once printed the answer you needed (a token, an error message, a diff, an IP), but it has disappeared—the scrollback was cleared, the tmux pane was closed, or the laptop was restarted. Ctrl-R can find the command you originally typed, but no tool can find what it output. backscroll does exactly that.

As the project introduction says: your shell history remembers what you typed, backscroll remembers what it printed.

Main capabilities

• Per-command recording: Records the complete output of each command, along with the exit code, current working directory (cwd), and time information, into a local SQLite database with full-text search support.
• Transparent passthrough:backscroll run starts your original shell on a PTY, passing every byte through unchanged, with no UI, no prompt modification, and no noticeable latency.
• Semantic marker segmentation: Emits OSC 133 semantic prompt markers through a small shell integration snippet (the same standard used by iTerm2, kitty, WezTerm, and VS Code), using them to split the output stream by command.
• Fully local: Everything is on your machine, with no daemon, no cloud, and no telemetry; the database is ~/.local/share/backscroll/backscroll.db a single file.
• Compression and truncation: Output is compressed with zstd; oversized output keeps the head plus the tail (the limit is configurable). Alternate-screen applications (vim, htop, less) are excluded to avoid filling the database with TUI junk.
• Search: Uses SQLite FTS5 with trigram to perform case-insensitive substring searches on both commands and output.
• No loss on disconnect: Closing the terminal window while a command is running does not lose the output; on hangup, it flushes what the command has already printed before exiting.
• Redaction by default: Redaction rules (built-in plus custom) are applied to every command and output on export, ignore rules can skip an entire entry, and only searchable plain text is sent.

Usage

Installation (Linux/macOS) provides a quick install script that downloads the binary for the corresponding platform, verifies the sha256, and installs it to ~/.local/bin, with no sudo required. It is also available via Homebrew (macOS), the .deb/.rpm packages for Debian/Ubuntu and Fedora, Scoop for Windows, mise (using the ubi backend), or static binaries from releases (linux/darwin/windows × amd64/arm64). Release archives include a man page.

The install script supports pinning the version with BACKSCROLL_VERSION=v0.11.1 and changing the target directory with BACKSCROLL_INSTALL_DIR . Later you can update in place with backscroll upgrade (checksum verification, runs only when you run it, and refuses to install versions managed by a package manager).

Configuration: Add the integration snippet to your shell rc (it is inert outside a recording session), for example eval "$(backscroll init zsh)"for zsh, eval "$(backscroll init bash)"for bash, backscroll init fish | sourcefor fish, and add $PROFILEfor PowerShell.

Start recording: Run backscroll run to start a recorded shell. To have every terminal record automatically, set backscroll run as the terminal's command/profile, or add [[ -z "$BACKSCROLL_ACTIVE" ]] && command -v backscroll > /dev/null && exec backscroll run。backscroll run starts a normal interactive shell; if you need login-shell semantics, use backscroll run --login.

Zero-config recording: If your shell or terminal already emits command markers,backscroll run Record without installing anything. fish 4 natively emits OSC 133 marks; nushell ships shell integration by default (OSC 133 marks, real exit codes, OSC 7 cwd); VS Code's shellIntegration script, kitty's integration, and wezterm's script are also read. For emitters that only mark prompt/command boundaries but do not report command text, backscroll reconstructs the command text from the terminal echo.

Import existing history: a new database means an empty picker; use the import feature to seed from existing history (backscroll doctor lists what it can find and the entry counts). Supports importing atuin (most informative: timestamps, exit codes, cwd, hostname), nu (requires nushell's SQLite history backend; plain text works by default too, content-sniffed), zsh (timestamps and durations require EXTENDED_HISTORY), bash (timestamps require HISTTIMEFORMAT), fish (always has timestamps), pwsh (reads PSReadLine's ConsoleHost_history.txt). Imported entries do not contain stored output, but list, search, pick, and stats all work from day one. Repeated imports are incremental.

Hotkey picker:backscroll init <bash|zsh|fish|pwsh> snippets come with a Ctrl-X Ctrl-P binding (requires fzf). It opens a picker over everything you have recorded—what you have already typed becomes the initial query—and inserts the selected command back at the prompt, like Ctrl-R, but you pick by what the command prints, not just by what you typed. Set BACKSCROLL_NO_BIND=1 before the snippet to opt out of that binding.

One-off commands:backscroll exec wraps a single command—no shell, no PTY, no configuration needed—and stores its merged stdout+stderr, exit code, cwd, and duration like any other command. It behaves like a tee stuck to your command: output passes through directly (silently recorded when--quiet ), stdin stays connected so pipes work, Ctrl-C is passed normally to the child process, and the exit code is mirrored (including 128+n for signal deaths), so it can go into crontab, Makefiles, and CI scripts without changing their behavior. Recording problems (missing database, full disk) never block or fail the command, only warn on stderr.

tmux / zellij / screen / SSH: backscroll wraps the shell, so it composes naturally with multiplexers—the key decision is which side of tmux it runs on. Recommended to use inside each pane (set backscroll run as the default command or add it to rc), each pane becomes an independent recording session, sharing the database,backscroll show -1 can pull up output that scrolled away in pane B from pane A. Not recommended to run backscroll run outside tmux and then enter tmux, because tmux redrawing the entire screen loses per-command segmentation. tmux ≥ 3.2 + fzf can bind prefix+B to open a popup fuzzy search (prefix+F for failures only). zellij and GNU screen have corresponding key snippets too. Over SSH, backscroll records on the machine where the shell runs; install it on the remote host and add the rc snippet, and use sync if you want to merge history.

Cross-machine sync: no server, no account, each machine appends its own end-to-end encrypted log (XChaCha20-Poly1305, shared key file copied once), append-only per-machine logs are naturally conflict-free, and any file sync tool you already use can serve as transport.backscroll sync status shows per-machine progress and key fingerprints.

AI agents (MCP):backscroll mcp is a built-in Model Context Protocol server (stdio, zero dependencies) that lets AI coding agents answer "what did that command print" from your recording history, without having to guess or re-run expensive or destructive operations. It provides search_output and other capabilities (material is truncated here).

Use cases

• Recover output that was once printed but has scrolled away (tokens, errors, diffs, IPs).
• Keep a record of output from one-off commands such as cron / CI / builds, replacing logs that no one rotates, >> /var/log/backup.log 2>&1, and also capture startup failures (such as "command not found" with exit 127).
• Search command output uniformly across multiple machines (laptop, desktop, the build machine you SSH into).
• Hand historical command output over to AI coding agents for querying.

Limitations

• Alternate-screen applications (vim, htop, less) are excluded and not recorded.
• Imported existing history entries do not include stored output.
• On Windows,cmd.exe has no integration for emitting markers; sessions run normally but are not split.
• Some environments have known quirks: in nushell, pressing Ctrl-C while a command is executing records exit 1 (because nu itself reports it that way); Ghostty's bash exit status is currently always 0 due to an upstream script bug.
• Running backscroll run outside tmux and then running tmux inside it is not available, because per-command splitting is lost.
• GNU screen's bindings shadow the default C-a B (pow_break) / C-a F (fit); if you use them, you need to rebind.
• This project is built and maintained by AI agent Soren Achebe; regarding questions of trust and responsibility, the project has a dedicated pinned discussion and explicitly welcomes human co-maintainers willing to share responsibility.

Information not yet provided

Facts such as specific pricing, billing model, performance metrics, and the maximum number of supported commands are not provided in the material.