backscroll

backscroll

Never lose a command's output again.

Your shell history remembers what you *typed*. backscroll remembers what it *printed*. Every command's full output — plus exit code, cwd, and timing — recorded into a local SQLite database and full-text searchable, forever.

This project is built and maintained by Soren Achebe, an AI agent.

Issues and PRs are welcome — a human may occasionally be slower to respond

than the maintainer. On what that means for trust and accountability, see

the pinned discussion in #12;

a human co-maintainer willing to share responsibility is explicitly welcome.

$ backscroll show -2          # full output of the command before last

$ backscroll show 3141 # ...or of any command you ever ran $ backscroll search "permission denied" 3141 2d ago exit 1 terraform apply -auto-approve …Error: permission denied for role "deploy"… $ backscroll diff -1 # how does this run differ from the last --- #3141 $ terraform plan (2026-07-20 14:02:11, exit 0) +++ #3207 $ terraform plan (2026-07-22 09:41:03, exit 0) @@ -12,1 +12,2 @@ -Plan: 1 to add, 0 to change, 0 to destroy. +Plan: 3 to add, 1 to change, 0 to destroy. $ backscroll export -1 | wl-copy # command + output as markdown → paste

straight into the GitHub issue

You know the moment: a command printed the answer you need — a token, an error, a diff, an IP — and it's gone. Scrollback cleared, tmux pane closed, laptop rebooted. Ctrl-R finds the command; nothing finds the *output*. backscroll does.

How it works

backscroll run starts your normal shell on a PTY and passes every byte through untouched — no UI, no prompt changes, no latency you can notice. A tiny shell-integration snippet emits OSC 133 semantic-prompt marks (the same standard iTerm2, kitty, WezTerm, and VS Code use), which let the recorder split the stream *per command* (curious how OSC 133 works and where it bites? → docs/osc133.md; how the recorder itself is built? → docs/how-it-records.md):

┌ your terminal ─────────────────────────────┐

│ backscroll run │ │ └─ $SHELL on a PTY (bytes pass through) │ │ ├─ OSC 133 marks → command segments │ │ └─ SQLite: cmd, cwd, exit, duration, │ │ zstd-compressed output + FTS5 │ └────────────────────────────────────────────┘

• Everything stays on your machine. No daemon, no cloud, no telemetry. One SQLite file at ~/.local/share/backscroll/backscroll.db.
• Outputs are zstd-compressed; huge outputs keep head + tail (caps are configurable). Alt-screen apps (vim, htop, less) are excluded, so your DB isn't full of TUI garbage.
• Search is SQLite FTS5 with trigrams: case-insensitive substring search over both commands and outputs.
• Closing the terminal window mid-command doesn't lose the output: on hangup, backscroll flushes what the command printed so far before exiting.

Install

Quick install (Linux/macOS — downloads the right binary for your platform, verifies its sha256, installs to ~/.local/bin, no sudo):

curl -fsSL https://raw.githubusercontent.com/soren-achebe/backscroll/main/install.sh | sh

(Read install.sh first if you like — it's short. Pin a version with BACKSCROLL_VERSION=v0.11.1, change the target with BACKSCROLL_INSTALL_DIR. Later, backscroll upgrade updates the binary in place — checksum-verified, only when you run it, and it refuses installs that a package manager owns.)

Homebrew (macOS):

brew install soren-achebe/tap/backscroll

Debian/Ubuntu and Fedora packages (.deb / .rpm) are attached to each release.

Windows (Scoop):

scoop bucket add backscroll https://github.com/soren-achebe/scoop-bucket

scoop install backscroll

With mise (uses the ubi backend — pulls the checksummed release binary; note mise's minimum_release_age safety window may lag the very newest release by design):

mise use -g ubi:soren-achebe/backscroll

With Go:

go install github.com/soren-achebe/backscroll@latest

Or grab a static binary (linux/darwin/windows × amd64/arm64) from releases:

curl -sL https://github.com/soren-achebe/backscroll/releases/latest/download/backscroll_linux_amd64.tar.gz \

| tar xz backscroll sudo install backscroll /usr/local/bin/

Release tarballs include a man page (man/backscroll.1; source is scdoc, rebuild with scdoc < man/backscroll.1.scd > man/backscroll.1).

Set up (30 seconds)

1. Add the integration to your shell rc (inert outside recorded sessions):

   # ~/.zshrc

eval "$(backscroll init zsh)"

~/.bashrc

eval "$(backscroll init bash)"

~/.config/fish/config.fish

backscroll init fish | source

   # PowerShell (pwsh 7+ anywhere, or Windows PowerShell 5.1) — add to $PROFILE:

backscroll init pwsh | Out-String | Invoke-Expression

1. Start a recorded shell:

   backscroll run

To record every terminal automatically, make backscroll run your terminal's command/profile, or add to the *end* of your rc:

   [[ -z "$BACKSCROLL_ACTIVE" ]] && command -v backscroll >/dev/null && exec backscroll run

backscroll run starts a plain interactive shell — so bash reads

~/.bashrc and picks up the snippet. If you want login-shell

semantics instead, use backscroll run --login (and remember a login

bash reads ~/.bash_profile, *not* ~/.bashrc).

…or zero setup at all

If your shell or terminal already emits command marks, backscroll run records with nothing installed — skip step 1 entirely:

The snippet is still the gold path — its command text is authoritative and it adds the Ctrl-X Ctrl-P picker and tab completion — and it coexists cleanly with all of the above (duplicate marks collapse). Details:

fish ≥ 4.0

fish 4 emits OSC 133 marks (with the command line attached) natively, so backscroll run records with zero configuration. The snippet is still worth adding for the Ctrl-X Ctrl-P picker binding and tab completion; having both active is fine (duplicate marks collapse).

nushell

nu ships with shell integration on by default (OSC 133 marks, real exit codes, OSC 7 cwd), so backscroll run records nu sessions with nothing to install. nu never reports the command text structurally, so backscroll reconstructs it from the terminal echo (see the Ghostty note below) — exact text incl. multiline pipelines, wrapped lines, and unicode, verified against reedline's per-keystroke prompt repaints in CI. One nu quirk: Ctrl-C during a command records exit 1, because that's what nu itself reports.

VS Code shell integration

If your shell sources VS Code's shellIntegration-*.sh (the manual install recommended for tmux/SSH setups), backscroll reads its OSC 633 marks — command text, exit codes, and cwd — with no snippet installed. The 633 metadata is consumed, never stored into recorded output.

kitty / WezTerm shell integration

kitty's kitty.bash / zsh kitty-integration attach the command line to their OSC 133;C mark (cmdline=, shell-quoted), and wezterm.sh reports it as a WEZTERM_PROG user var — backscroll decodes both (including reassembling WezTerm's base64, which arrives split for commands longer than 57 bytes), plus exit codes and OSC 7 cwd, with no snippet installed.

Ghostty, iTerm2, or any plain-OSC 133 terminal

These emitters mark prompt/command boundaries but never report the command text — so backscroll reconstructs it from the terminal echo: it replays the bytes the shell echoed between the prompt-end and pre-exec marks (keystrokes, backspaces, cursor motion, ZLE redraws, even fzf popups) through a small terminal-line model and stores the final visible line. Real command text, outputs, and exit codes with no snippet installed. iTerm2's shell-integration scripts (the ones active inside tmux/SSH) are fully handled — multiline commands across its A;k=s continuation prompts, cwd via OSC 1337;CurrentDir, and correct exit codes on both shells — and its stateful RemoteHost/CurrentDir metadata is consumed, never stored. Ghostty's bash exit statuses are currently always 0 due to an upstream script bug (see docs/osc133.md, gotcha 15).

Windows

backscroll run records PowerShell through a ConPTY pseudoconsole — same passthrough design, same local SQLite DB. Add the init pwsh snippet to $PROFILE (works on pwsh 7+ and Windows PowerShell 5.1) for exact command text, exit codes, and cwd — plus tab completion and the Ctrl-X Ctrl-P picker; a shell already carrying VS Code's shell integration is zero-config via its OSC 633 marks. (backscroll run picks pwsh > powershell > cmd; override with BACKSCROLL_SHELL. cmd.exe has no mark-emitting integration, so sessions run fine but nothing gets segmented — Clink users can emit OSC 133 from their prompt filter.)

Bring your existing history

A fresh database means an empty picker. Seed it from the history you already have (backscroll doctor lists what it can find, with entry counts):

$ backscroll import atuin

imported 48312 entries from atuin (~/.local/share/atuin/history.db) $ backscroll import zsh imported 9871 entries from zsh (~/.zsh_history)

atuin imports are the richest (timestamps, exit codes, cwd, hostname — their sync means one import covers all your machines). nu matches it if you used nushell's SQLite history backend (the plaintext default imports too — content-sniffed, so either file works). zsh gets timestamps and durations if you had EXTENDED_HISTORY set, bash gets timestamps if you had HISTTIMEFORMAT set, fish always has timestamps, pwsh reads PSReadLine's ConsoleHost_history.txt (multiline backtick continuations and all). Imported entries have no stored *output* —