soren-achebe/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.
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):
- **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):
(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):
Debian/Ubuntu and Fedora packages (.deb / .rpm) are attached to each
release.
Windows (Scoop):
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):
With Go:
Or grab a static binary (linux/darwin/windows × amd64/arm64) from
releases:
Release tarballs include a man page (man/backscroll.1; source is
scdoc, rebuild with
scdoc man/backscroll.1).
Set up (30 seconds)
1. Add the integration to your shell rc (inert outside recorded sessions):
2. Start a recorded shell:
To record every terminal automatically, make backscroll run your
terminal's command/profile, or add to the *end* of your rc:
> 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:
| you're running | zero-config | command text comes from |
|---|---|---|
| fish ≥ 4.0 | ✓ | native OSC 133 (cmdline_url) |
| nushell | ✓ | reconstructed from the terminal echo |
| VS Code shell integration in your rc | ✓ | its OSC 633 marks |
| kitty / WezTerm shell integration in your rc | ✓ | cmdline= / WEZTERM_PROG |
| Ghostty, iTerm2, any plain-OSC 133 terminal | ✓ | reconstructed from the terminal echo |
| PowerShell (Windows/anywhere) | snippet recommended | init pwsh (OSC 633 zero-config under VS Code) |
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