backscroll

# backscroll

[![CI](https://github.com/soren-achebe/backscroll/actions/workflows/ci.yml/badge.svg)](https://github.com/soren-achebe/backscroll/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/soren-achebe/backscroll)](https://github.com/soren-achebe/backscroll/releases/latest)
[![Go Reference](https://pkg.go.dev/badge/github.com/soren-achebe/backscroll.svg)](https://pkg.go.dev/github.com/soren-achebe/backscroll)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

**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.

![demo](demo/demo.gif)

> 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.

```console
$ 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](https://gitlab.freedesktop.org/Per_Bothner/specifications/blob/master/proposals/semantic-prompts.md)
(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](docs/osc133.md); how the recorder
itself is built? → [docs/how-it-records.md](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):

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

(Read [`install.sh`](install.sh) first if you like — it's short. Pin a version
with `BACKSCROLL_VERSION=v0.4.0`, change the target with
`BACKSCROLL_INSTALL_DIR`.)

Homebrew (macOS):

```sh
brew install soren-achebe/tap/backscroll
```

Debian/Ubuntu and Fedora packages (`.deb` / `.rpm`) are attached to each
[release](https://github.com/soren-achebe/backscroll/releases).

With Go:

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

Or grab a static binary (linux/darwin × amd64/arm64) from
[releases](https://github.com/soren-achebe/backscroll/releases):

```sh
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](https://git.sr.ht/~sircmpwn/scdoc), rebuild with
`scdoc < man/backscroll.1.scd > man/backscroll.1`).

## Set up (30 seconds)

> **fish ≥ 4.0?** Skip step 1 entirely if you like — 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).

> **VS Code shell integration in your rc file?** Also zero-config: if
> your shell sources VS Code's `shellIntegration-*.sh` (the
> [manual install](https://code.visualstudio.com/docs/terminal/shell-integration#_manual-installation)
> 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 or WezTerm shell integration in your rc file?** Same story:
> 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?** Also
> zero-config. 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](docs/osc133.md), gotcha 15). The
> snippet is still the gold path — its OSC 6973 text is authoritative
> and adds the picker binding — and coexists cleanly.

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

   ```sh
   # ~/.zshrc
   eval "$(backscroll init zsh)"
   # ~/.bashrc
   eval "$(backscroll init bash)"
   # ~/.config/fish/config.fish
   backscroll init fish | source
   ```

2. Start a recorded shell:

   ```sh
   backscroll run
   ```

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

   ```sh
   [[ -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`).

## Use

| command | what it does |
|---|---|
| `backscroll show` | full output of the last command |
| `backscroll show -3` | third-most-recent command |
| `backscroll show 3141` | by id · `--raw` keeps colors |
| `backscroll search <text>` | full-text search commands + outputs |
| `backscroll search -C 3 <text>` | …with 3 lines of context around every matching output line, like `grep -C` (`-A`/`-B` work too) |
| `backscroll pick` | fuzzy-pick a command (fzf) with live output preview |
| **Ctrl-X Ctrl-P** at the prompt | pick a past command and insert it at your cursor (current line becomes the query) |
| `backscroll list -n 50` | recent commands with exit/duration/size |
| `... --exit fail --since 2h` | list/search filters: failures only, last 2 hours |
| `... --cwd .` | only commands run in this directory (or beneath it) |
| `backscroll diff 3141` | what changed vs. the **previous run of the same command** |
| `backscroll diff -2 -1` | unified diff of any two stored outputs (`-U n` context) |
| `backscroll export -1` | command + output as a markdown block, ready to paste into an issue (`--details` folds it) |
| `backscroll export 3141 --format cast` | asciicast v2 — replay with `asciinema play` |
| `backscroll export -1 --format json` | structured record for scripting |
| `backscroll sync init ~/Sync/bks` | cross-machine sync through any shared folder — encrypted, serverless ([details](#cross-machine-sync)) |
| `... --host laptop` / `--host local` | list/search/pick filter: only that machine's history |
| `backscroll stats` | how much is stored |
| `backscroll prune --older 30d` | forget old entries |
| `backscroll delete <id>` | forget one entry (that `curl -H "Authorization: ..."`) |
| `backscroll redact <id\|-N>` | permanently mask tokens/keys/passwords in a stored entry (`--dry-run` previews) |
| `backscroll mcp` | MCP server: let your AI coding agent query your history ([details](#ai-agents-mcp)) |
| `backscroll serve` | local web UI: browse + search your history in the browser ([details](#web-ui)) |
| `backscroll off` / `on` | pause / resume recording in this session |
| `backscroll doctor` | check that everything is wir