backscroll

backscroll

コマンドの出力を二度と失わない。

シェルの履歴に残るのは、入力したコマンドです。backscroll は、コマンドが 出力した内容を記録します。各コマンドの全出力に加え、終了コード、作業ディレクトリ、 実行時間をローカルの SQLite データベースに記録し、いつまでも全文検索できます。

このプロジェクトは、AI エージェントである Soren Achebe が開発・保守しています。 Issue や PR を歓迎します。メンテナーよりも人間の返信が遅くなることがあります。 信頼性と説明責任への影響については、#12 の ピン留めされたディスカッションをご覧ください。責任を分担する意思のある人間の共同メンテナーを 明確に歓迎します。

$ 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

こんな経験はありませんか。必要な答え――トークン、エラー、差分、IP アドレスなど――を コマンドが出力したのに、もう見つかりません。スクロールバックは消え、tmux のペインは閉じ、 ノート PC は再起動済み。Ctrl-R でコマンドは見つかりますが、出力を探す方法はありません。 backscroll なら見つかります。

仕組み

backscroll run は PTY 上で通常のシェルを起動し、すべてのバイトをそのまま通過させます。 UI の追加も、プロンプトの変更も、気づくほどの遅延もありません。小さなシェル連携スニペットが OSC 133 のセマンティックプロンプトマーク （iTerm2、kitty、WezTerm、VS Code が使用するものと同じ標準規格）を出力します。これにより、 レコーダーはストリームをコマンドごとに分割できます（OSC 133 の仕組みや問題点については → docs/osc133.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     │
└────────────────────────────────────────────┘

• すべてのデータはお使いのマシン上に残ります。 デーモンもクラウドもテレメトリーもありません。 SQLite ファイルは ~/.local/share/backscroll/backscroll.db に 1 つだけです。
• 出力は zstd で圧縮されます。巨大な出力は先頭と末尾を保持します（上限は設定可能です）。 Alt-screen アプリ（vim、htop、less）は除外されるため、データベースが TUI の不要なデータで 埋まることはありません。
• 検索にはトライグラムを使う SQLite FTS5 を採用しており、コマンドと出力の両方を 大文字・小文字を区別せずに部分一致検索できます。
• コマンドの実行中にターミナルウィンドウを閉じても、出力は失われません。ハングアップ時に backscroll は、終了する前にコマンドがそれまでに出力した内容をフラッシュします。

インストール

クイックインストール（Linux/macOS — お使いのプラットフォームに適したバイナリをダウンロードし、 sha256 を検証して、~/.local/bin にインストールします。sudo は不要です）：

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

（よろしければ、まず install.sh をお読みください。短いスクリプトです。BACKSCROLL_VERSION=v0.11.1 でバージョンを固定し、 BACKSCROLL_INSTALL_DIR でインストール先を変更できます。インストール後は、backscroll upgrade を実行するとバイナリが その場で更新されます。チェックサムを検証し、実行したときだけ更新し、パッケージマネージャーが管理しているインストールは 拒否します。）

Homebrew（macOS）：

brew install soren-achebe/tap/backscroll

Debian/Ubuntu および Fedora のパッケージ（.deb / .rpm）は、各 リリースに添付されています。

Windows（Scoop）：

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

mise を使う場合（ubi バックエンドを使用します。チェックサム付きのリリースバイナリを取得します。mise の minimum_release_age による安全期間のため、設計上、最新リリースの反映に遅れが生じる場合があります）：

mise use -g ubi:soren-achebe/backscroll

Go を使う場合：

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

または、リリースから静的バイナリ（linux/darwin/windows × amd64/arm64）を ダウンロードしてください：

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/

リリースの tarball には man ページ（man/backscroll.1。ソースは scdoc です。scdoc < man/backscroll.1.scd > man/backscroll.1 で再ビルドできます）が含まれています。

セットアップ（30 秒）

1. シェルの rc に連携機能を追加します（記録中のセッション以外では何も行いません）：

   # ~/.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
   

2. 記録するシェルを起動します：

   backscroll run
   

   すべてのターミナルを自動的に記録するには、backscroll run をターミナルの コマンド／プロファイルに設定するか、rc の末尾に追加します：

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

   backscroll run は通常の対話型シェルを起動します。そのため、bash は ~/.bashrc を読み込み、スニペットを有効にします。代わりにログインシェルの セマンティクスを使いたい場合は、backscroll run --login を使用してください（ログイン時の bash は ~/.bashrc ではなく ~/.bash_profile を読み込む点にご注意ください）。

…またはセットアップなしで使う

お使いのシェルまたはターミナルがすでにコマンドマークを出力する場合、backscroll run は 何もインストールせずに記録します。手順 1 は丸ごと省略できます：

使用環境	設定不要	コマンドテキストの取得元
fish ≥ 4.0	✓	ネイティブの OSC 133（cmdline_url）
nushell	✓	ターミナルのエコーから再構成
rc 内の VS Code シェル統合	✓	その OSC 633 マーク
rc 内の kitty / WezTerm シェル統合	✓	cmdline= / WEZTERM_PROG
Ghostty、iTerm2、OSC 133 対応の一般的なターミナル	✓	ターミナルのエコーから再構成
PowerShell（Windows／任意の環境）	スニペットを推奨	init pwsh（VS Code では OSC 633 により設定不要）

スニペットを使う方法が最もおすすめです。コマンドテキストが正確に取得され、 Ctrl-X Ctrl-P の選択機能とタブ補完も追加されます。また、上記の方法とも 問題なく併用できます（重複するマークはまとめられます）。詳細：

fish ≥ 4.0

fish 4 はコマンドラインが付属した OSC 133 マークをネイティブで出力するため、 backscroll run は設定不要で記録します。Ctrl-X Ctrl-P の選択機能のバインドとタブ補完を 利用するには、スニペットを追加する価値があります。両方を有効にしても問題ありません （重複するマークはまとめられます）。

nushell

nu はデフォルトでシェル統合（OSC 133 マーク、実際の終了コード、OSC 7 の cwd）が有効なため、 インストールするものがなくても backscroll run で nu セッションを記録できます。nu はコマンドテキストを 構造化して報告しないため、backscroll はターミナルのエコーからテキストを再構成します（下記の Ghostty に関する説明を参照）。 複数行のパイプライン、折り返された行、Unicode を含むテキストも正確に取得し、CI で reedline の キー入力ごとのプロンプト再描画と照合して検証しています。nu には特有の挙動が 1 つあります。コマンド実行中に Ctrl-C を押すと、nu 自体が終了コード 1 を報告するため、終了コード 1 として記録されます。

VS Code シェル統合

シェルで VS Code の `shellIntegration-*.sh` を読み込んでいる場合（tmux/SSH 環境で推奨される [手動インストール](https://code.visualstudio.com/docs/terminal/shell-integration#_manual-installation) を利用している場合）、backscroll は OSC 633 のマーク（コマンドテキスト、終了コード、cwd）を読み取ります。スニペットをインストールする必要はありません。633 のメタデータは利用されますが、記録された出力には保存されません。

kitty / WezTerm シェル統合

kitty の kitty.bash / zsh の kitty-integration は、コマンドラインを OSC 133;C マーク（cmdline=、シェル形式で引用）に付加します。また、wezterm.sh はそれを WEZTERM_PROG ユーザー変数として報告します。backscroll はどちらもデコードします（57 バイトを超えるコマンドでは分割されて届く WezTerm の base64 の再構成も含みます）。さらに、終了コードと OSC 7 の cwd も取得できます。スニペットをインストールする必要はありません。

Ghostty、iTerm2、または OSC 133 のみを出力するターミナル

これらのエミッターはプロンプトとコマンドの境界を示しますが、コマンドテキストは報告しません。そのため backscroll はターミナルのエコーからコマンドを再構成します。プロンプト終了マークと実行前マークの間にシェルがエコーしたバイト列（キー入力、バックスペース、カーソル移動、ZLE の再描画、fzf のポップアップも含む）を小さなターミナル行モデルで再生し、最終的に表示される行を保存します。スニペットのインストールなしで、実際のコマンドテキスト、出力、終了コードを取得できます。iTerm2 のシェル統合スクリプト（tmux/SSH 内で有効なもの）にも完全に対応しています。複数行コマンド（A;k=s の継続プロンプト）、OSC 1337;CurrentDir による cwd、両シェルでの正確な終了コードに対応し、状態を持つ RemoteHost / CurrentDir メタデータは利用されますが、保存されません。Ghostty の bash の終了ステータスは、上流のスクリプトのバグにより現在は常に 0 です（docs/osc133.md の注意点 15 を参照）。

Windows

backscroll run は ConPTY 疑似コンソールを通じて PowerShell を記録します。パススルー方式もローカルの SQLite DB も同じです。$PROFILE に init pwsh スニペットを追加すると（pwsh 7 以降と Windows PowerShell 5.1 で動作します）、正確なコマンドテキスト、終了コード、cwd に加え、タブ補完と Ctrl-X Ctrl-P ピッカーも利用できます。VS Code のシェル統合がすでに有効なシェルでは、OSC 633 マークにより設定不要です。（backscroll run は pwsh > powershell > cmd の順に選択します。BACKSCROLL_SHELL で上書きできます。cmd.exe にはマークを出力する統合機能がないため、セッションは問題なく動作しますが、区切り情報は取得されません。Clink ユーザーはプロンプトフィルターから OSC 133 を出力できます。）

既存の履歴を取り込む

新しいデータベースはピッカーが空の状態です。すでにある履歴からデータを投入できます（backscroll doctor を実行すると、見つかった履歴とエントリー数が表示されます）。

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

atuin のインポートが最も充実しています（タイムスタンプ、終了コード、cwd、ホスト名に対応しており、同期機能があるため、1 回のインポートですべてのマシンをカバーできます）。nushell の SQLite 履歴バックエンドを使用していた場合は、nu も同様に充実しています（デフォルトのプレーンテキスト形式もインポートできます。内容を判別するため、どちらのファイルも使用できます）。zsh は EXTENDED_HISTORY を設定していた場合にタイムスタンプと実行時間を取得し、bash は HISTTIMEFORMAT を設定していた場合にタイムスタンプを取得します。fish は常にタイムスタンプを持ち、pwsh は PSReadLine の ConsoleHost_history.txt を読み込みます（バッククォートによる複数行の継続にも対応します）。インポートしたエントリーには保存済みの出力はありません。当時は記録されていなかったためです。ただし、初日から list、search、pick（および Ctrl-X Ctrl-P ピッカー）、stats を使って履歴を参照でき、すべての履歴を連続したタイムラインとして表示できます。インポートを再実行すると差分のみが追加され、未確認のエントリーだけが取り込まれます。

（ファイルが実際にディスク上でどのように保存されるか気になりますか？ zsh のメタ化バイト列、PSReadLine のバッククォートによる継続、atuin のナノ秒単位の時刻など。フィールドノート：docs/history-files.md。）

使い方

コマンド	内容
backscroll show	直前のコマンドの出力全体
backscroll show -3	3つ前のコマンド
backscroll show 3141	IDで指定 · --raw で色を保持
backscroll search <text>	コマンドと出力を全文検索
backscroll search -C 3 <text>	…一致した出力行の前後3行も表示します。grep -C と同様に、-A／-B も使用できます
backscroll pick	出力をライブプレビューしながら、コマンドをあいまい検索して選択（fzf）
プロンプトで Ctrl-X Ctrl-P	過去のコマンドを選び、カーソル位置に挿入します（現在の行が検索クエリになります）
backscroll list -n 50	終了コード／所要時間／サイズ付きの最近のコマンド
... --exit fail --since 2h	共通フィルター（list/search/pick/export）：失敗のみ、直近2時間
... --since 2026-07-20 --until 2026-07-21	--until で期間の上限を指定します（上限は含みません）—その日だけが対象です
... --cwd .	このディレクトリ（またはその配下）で実行したコマンドのみ
backscroll note "this one fixed it"	直前のコマンドにメモを添付します。メモはlist/show/searchに表示され、検索もできます（note -3 "…" で過去のコマンドを指定し、--rm で削除）
backscroll diff 3141	同じコマンドの前回実行時と比べた変更点
backscroll diff -2 -1	保存された任意の2つの出力の統合差分（-U n でコンテキストを指定）
backscroll export -1	コマンドと出力を、課題に貼り付けられるMarkdownブロックとして出力（--details で折りたたみます）
backscroll export --exit fail --since 1d	今日の失敗をすべて1つのMarkdownレポートとして出力します。ここでもフィルターを使用できます
backscroll export 3141 --format cast	asciicast v2形式 — asciinema play で再生
backscroll export -1 --format json	スクリプトで利用できる構造化レコード
backscroll export -1 --format html -o out.html	ANSIカラーを完全に保持した自己完結型HTMLページ — チケットに添付したり、そのまま共有したりできます
backscroll exec make test	記録中のセッション外でコマンドを1つ実行し、その出力／終了コード／実行時間を保存します — cronジョブ、CIのステップ、ビルド向け（詳細）
backscroll import atuin	atuinの履歴からデータベースに初期データを取り込みます — タイムスタンプ、終了コード、作業ディレクトリ、ホストも引き継がれます（詳細）
backscroll import zsh / bash / fish	…または通常の履歴ファイルから取り込みます
backscroll sync init ~/Sync/bks	任意の共有フォルダーを使ってマシン間で同期します — 暗号化され、サーバーレスです（詳細）
... --host laptop / --host local	list/search/pick用のフィルター：指定したマシンの履歴のみ
backscroll stats	保存されているデータ量
backscroll stats --by cmd --exit fail --since 1w	今週もっとも失敗したコマンド — コマンドごとの回数、失敗率、合計実時間、アクティビティのスパークライン（--by cwd|exit|host|session|day も使用できます）
backscroll prune --older 30d	古いエントリーを削除
backscroll delete <id>	1つのエントリーを削除（この curl -H "Authorization: ..."）
backscroll redact <id|-N>	保存済みエントリー内のトークン／キー／パスワードを完全にマスキングします（--dry-run でプレビュー）
backscroll mcp	MCP サーバー：AI コーディングエージェントが履歴を検索できるようにします（詳細）
backscroll serve	ローカルWeb UI：ブラウザーで履歴を閲覧・検索できます（詳細）
backscroll off / on	このセッションでの記録を一時停止／再開
backscroll doctor	すべてが正しく設定されているか確認
Ctrl-X Ctrl-P バインドは、`backscroll init
<bash	zsh

単発コマンド（cron、CI、ビルド）

すべてが対話型セッション内で行われるわけではありません。backscroll exec は単一のコマンドをラップし、シェルも PTY もセットアップも不要で、他の記録済みコマンドと同様に、標準出力と標準エラーをまとめた出力、終了コード、作業ディレクトリ、実行時間を保存します。

backscroll exec make -j4 test          # flags after the command belong to it
backscroll exec sh -c 'pg_dump app | gzip > backup.gz'   # shell features? bring a shell

コマンドに tee をつないだように動作します。出力はそのまま通過し（--quiet を指定すると出力せずに記録します）、パイプラインが動作するよう標準入力も接続され、Ctrl-C は通常どおり子プロセスに届きます。また、終了コードはそのまま引き継がれます。シグナルによる終了時の 128+n も含まれるため、動作を変えずに crontab、Makefile、CI スクリプトに組み込めます。記録に問題があっても（DB がない、ディスクがいっぱいなど）、コマンド自体が停止したり失敗したりすることはありません。標準エラーに警告が表示され、コマンドはそのまま実行されます。

特に便利なのが cron です。MAILTO の調査に時間をかけたり、誰もローテーションしない >> /var/log/backup.log 2>&1 ファイルを使ったりする必要はありません。

17 3 * * * backscroll exec /usr/local/bin/nightly-backup

そして翌週、火曜日のバックアップがなぜ遅かったのか気になったときには、次のようにできます。

$ backscroll list --since 1w --exit fail
$ backscroll search "No space left" --since 1w
$ backscroll diff -1        # what changed vs. the previous run?

起動時の失敗も記録されます（exit 127。エラーテキストも検索可能です）。cron でおなじみの、何も知らせずに起きる「コマンドが見つからない」問題の痕跡が、ついに残ります。--quiet を指定したときの失敗も確認できます。backscroll stats --by cmd --exit fail --since 1w を実行すると、他のすべてと同じように集計されます。

GitHub Actions

setup-backscroll を使うと、任意のランナー（Linux/macOS/Windows、チェックサム検証済み）に backscroll をインストールできます。

- uses: soren-achebe/setup-backscroll@v1
- run: backscroll exec -- make test

README には、ぜひ取り入れたい 2 つのレシピがあります。失敗したステップの出力を、最後に成功した実行の出力と比較する方法（actions/cache で DB を永続化してから、backscroll diff -1 を実行します）と、ビルド成果物としてアップロードできる、単独で完結した HTML 形式の失敗レポートです。

tmux / zellij / screen / SSH

backscroll はシェルをラップするため、マルチプレクサーと自然に組み合わせられます。tmux の内側と外側のどちらで使うかを決めてください。

• 各ペインの内側（推奨）： 上記の exec backscroll run の rc スニペットを使うか、tmux の default-command "backscroll run" を設定します。各ペインがそれぞれ記録されるセッションになり、ペイン A で backscroll show -1 を実行すると、ペイン B でスクロールして見えなくなった出力も表示できます。DB は共有されます。$BACKSCROLL_ACTIVE ガードにより、ネストした場合も二重記録を防ぎます。
• tmux の外側（backscroll run の後にその内側で tmux を実行）： 役に立ちません。tmux は画面全体を再描画するため、コマンドごとの区切りが失われます。backscroll は代替画面を通じて全画面アプリを検出し、記録をスキップするため、代わりにペインの内側で実行してください。
• ポップアップ検索（tmux ≥ 3.2 + fzf）： backscroll init tmux >> ~/.tmux.conf を実行すると、prefix + B に、記録済みのすべてのコマンドを保存済みの出力をリアルタイムでプレビューしながらあいまい検索するポップアップが割り当てられます（prefix + F は失敗のみ）。どのペインからでも、いつでも使えます。Enter で出力全体をページ送りし、q で作業に戻ります。
• zellij： 同様に、各ペインの内側で記録します。backscroll init zellij は、同じあいまい検索を Alt b でフローティングペインに表示するキーバインドスニペットを出力します（Alt Shift b は失敗のみ）。さらに Alt r で過去のコマンドを選び、プロンプトに入力できます。実行されるのではなく、編集できる状態で挿入されます（複数行コマンドはブラケットペーストで入力されるため、埋め込み改行で Enter が押されることはありません）。どのシェルでも動作し、rc スニペットは不要です。keybinds ブロックがまだない場合は、スニペットを ~/.config/zellij/config.kdl に追記してください。すでにある場合は、3 行の bind を既存のブロックにコピーしてください（zellij は 2 つ目の keybinds ブロックを無視します）。
• GNU screen： 各ウィンドウの内側で記録します。backscroll init screen >> ~/.screenrc を実行すると、使い捨てウィンドウで同じあいまい検索を行う C-a B が割り当てられます（C-a F は失敗のみ）。ピッカーを終了すると、そのウィンドウは自動的に閉じます。注意：screen のデフォルトの C-a B（pow_break）／C-a F（fit）を上書きします。これらを使う場合は、別のキーに割り当て直してください。
• SSH 経由： backscroll はシェルが実行されているマシンで記録します。リモートホストにインストールして、そちらで rc スニペットを追加してください。履歴を統合する場合は、sync を使います。

マシン間の同期

backscroll search "connection refused" — ノート PC、デスクトップ、SSH で接続するビルドマシンを横断して検索できます。

laptop$ backscroll sync init ~/Sync/backscroll   # any shared folder:
                                                 # Syncthing, Dropbox, rsync…
laptop$ backscroll sync export
desktop$ # copy ~/.config/backscroll/sync.key from the laptop, then:
desktop$ backscroll sync init ~/Sync/backscroll
desktop$ backscroll sync import
desktop$ backscroll search "connection refused"      # both machines' history
 3141  2d ago  exit 1  [laptop] curl http://10.0.0.7:8080/health
       …connection refused…
desktop$ backscroll list --host laptop               # or filter by machine

サーバーもアカウントも不要です。各マシンがそれぞれのエンドツーエンド暗号化されたログ（XChaCha20-Poly1305、共有鍵ファイルは一度コピーするだけ）をフォルダーに追記し、ほかのマシンのログをインポートします。マシンごとに追記専用のログを使うため、競合は発生しません。同期を複数回行った場合も、一部だけ同期した場合も、順序が前後した場合も、データが壊れることはありません。すでに実行しているファイル同期ツールはどれも転送手段として使えます。

プライバシーは、データがマシンから外に出る前に確保されます。コマンドと出力のすべてに、エクスポート時に伏字化パターン（組み込みのものと独自のもの）が適用され、無視パターンに一致するエントリーは完全に除外されます。送信されるのは検索可能なプレーンテキストのみで、記録したマシンから生のターミナルバイト（show --raw の再生）が外に出ることはありません。backscroll sync status で、マシンごとの進行状況と鍵のフィンガープリントを確認できます。設計に関する説明は、docs/sync-design.md を参照してください。

AI エージェント（MCP）

backscroll mcp は組み込みのModel Context Protocol サーバー（stdio、依存関係なし）です。AI コーディングエージェントは推測したり、 コストのかかる処理や破壊的な処理を再実行したりせずに、記録された履歴から *「あのコマンドは何を出力した？」*と確認できます。

• search_output — 「ビルドで最初に undefined symbol と表示された箇所を探す」（context_lines を指定すると、各ヒットの前後に grep -C 形式のコンテキストが表示されます）
• get_output — 任意のコマンドの全出力（-1 = 直近のコマンド）
• list_commands — 最近の履歴（例：失敗したコマンドのみ）
• diff_output — 同じコマンドの前回実行時と比べて何が変わったか

クライアントに登録します。

# Claude Code
claude mcp add backscroll -- backscroll mcp

// Cursor / Windsurf / VS Code-style mcpServers config
{ "mcpServers": { "backscroll": { "command": "backscroll", "args": ["mcp"] } } }

クライアントごとの設定方法（Claude Code/Desktop、Codex、Cursor、Windsurf、VS Code、 Zed、Gemini CLI）については、ドキュメントサイトをご覧ください。 AI エージェントガイド。

公式 MCP Registryにも io.github.soren-achebe/backscrollとして登録されています。また、各リリースには backscroll-<version>.mcpbバンドル（macOS/Linux）が含まれます。ファイルから MCP サーバーをインストールするクライアント向けで、個別のインストールは不要です。ただし、検索対象となる履歴を記録するため、上記のセットアップも必要です。コンテナ化された MCP 環境向けには、マルチアーキテクチャ対応のビルド済みイメージも用意されています。

docker run -i --rm \
  -v ~/.local/share/backscroll:/data/.local/share/backscroll:ro \
  ghcr.io/soren-achebe/backscroll

（データベースは読み取り専用でマウントしてください。記録には、実際のシェルを囲むネイティブバイナリが引き続き必要です。）

シークレットはデフォルトでマスキングされます：クライアントに渡されるすべての情報には、backscroll redactと同じ秘匿化パターン（一般的なトークン形式に対応する組み込みパターンと、~/.config/backscroll/redactの設定）が適用されます。これに加えて、一致するコマンドをデータベースに一切記録しない既存の除外パターンも適用されます。本当に必要な場合は、backscroll mcp --no-redactでマスキングを無効にできます。サーバーが読み取るのはローカルのデータベースだけです。記録はシェル内で引き続き行われ、エージェントが要求した内容以外はマシンの外に送信されません。

逆方向の使い方もできます。backscrollをエージェントに向けると、エージェントがマシンまたは開発用VMで実行したすべてのコマンドが、コマンド単位で検索可能な監査証跡になります。エージェントの実行内容を監査するをご覧ください。

Web UI

backscroll serve は、記録した履歴を表示する ローカルの読み取り専用 Web UI を起動します（--open を指定するとブラウザーで開きます）。

• 入力と同時に検索できます。コマンド と その出力を対象に検索します（内部では FTS5 を使用するため、数万件のコマンドがあっても瞬時に検索できます）。一致箇所のスニペットに加え、CLI と同じフィルター（失敗のみ、時間範囲）も利用できます。コンテキストセレクターを使うと、一致した出力行の前後 ±2 行または ±5 行を grep のように表示します（search -C と同等です）。結果を展開すると、完全な出力内の一致箇所すべてがハイライトされ、↑ 3/17 ↓ のジャンパーで順に移動できます。ANSI カラーによって単語が分割されていても機能します。
• 統計ビュー — 履歴から、コマンド別／ディレクトリ別／終了コード別／ホスト別／日別 の内訳（件数、失敗率、合計実時間）に切り替えられます。内訳は有効なフィルターの適用対象です。ディレクトリ、終了コード、ホストの行はクリックできます。「exit 127」をクリックすると、該当するコマンドだけを表示した履歴に戻ります（「同じように失敗したコマンドと、その出力は？」）。
• カラーを保持 — 保存された ANSI 出力を HTML に変換して表示するため、ls、テストランナー、ビルドログをターミナルと同じ見た目で確認できます。進捗バーの連続出力（\r による上書き）は、最終状態にまとめられます。
• ワンクリックで差分を表示 — 同じコマンドを前回実行したときとの差分を確認できます。「昨日のヘルスチェックから何が変わった？」ボタンです。
• パーマリンク — 各コマンドには #42 のディープリンクがあり、コマンドを全ページ表示で開けます（出力の省略なし、絶対時刻、リンクのコピーボタン）。ビルドログをピン留めしたタブで開いたままにしたり、不安定なテストの出力をブックマークしたり、メモにリンクを貼って翌日にもう一度確認したりできます。
• HTML としてダウンロード — ワンクリックで、任意のコマンドを export --format html と同じ自己完結型ページとして保存できます（フルカラー、外部アセットなし、JS なし）。チケットに添付したり、同僚に渡したりできます。ブラウザーは不要です。
• ローカルのみで動作する設計：127.0.0.1:4133 にバインドし、GET リクエストのみを受け付けます。また、Host ヘッダーが localhost ではないリクエストを拒否するため、悪意のある Web サイトが DNS リバインディングを使って履歴を読み取ることはできません。--addr をループバックアドレス以外に変更すると、大きく警告します。--redact は backscroll redact と同じパターンで、配信するすべての内容のシークレットをマスクします。

ビルド手順も node_modules も不要です。UI は埋め込み済みの単一 HTML ファイルで、全体が同じ静的バイナリに含まれています。

他のツールとの比較

	コマンドを記録	出力を記録	検索可能	コマンド単位の構造
シェル履歴 / atuin / hishtory	✓	✗	✓	✓
script / asciinema	✓	✓	✗（生データ）	✗
ターミナルのスクロールバック	✓	そうでなくなるまで	✗	✗
backscroll	✓	✓	✓（FTS5）	✓

ほかのツールと併用できます

backscroll はプロンプトや履歴管理ツールではなく、記録ツールです。お使いのシェルと並行して動作するように設計されています。CI では、人気のツールを実際の固定バージョンで使ったセッションを実行し、コマンド、出力、終了コードがすべて正しく記録されること、そしてほかのツールも引き続き動作することを検証します （shell/test_compat_matrix.py）。

テスト対象	bash	zsh	fish
atuin（Ctrl-R の TUI を含む）	✓	✓	✓
starship（読み込み順の両方）	✓	✓	✓
zoxide	✓	—	✓
direnv	✓	—	—
oh-my-zsh		✓
powerlevel10k（instant prompt を含む）		✓
bash-preexec（読み込み順の両方）	✓
bind -x / zle ウィジェット（fzf 形式。上記の atuin の実際の Ctrl-R を含む）	✓	✓	✓

backscroll を使わない場合でも知っておく価値のある点があります。bash で starship ≤ 1.26 を使っていると、starship がラップした PROMPT_COMMAND から $? を読み取るものは、実際の終了ステータスではなく 0 を取得します。starship 独自の _starship_set_return は、その直後に続く [[ -n ... ]] テストによって無効化されるためです。backscroll は、プロンプトフレームワークが実行される前に DEBUG トラップで実際の終了ステータスを取得することで、この問題を回避します（starship が公開している PR #7606 はラップ方法を再構成し、一般的なケースを修正するものです）。

オーバーヘッド

控えめな 2-vCPU VM（AMD EPYC）で計測した、複数回実行時の中央値です。go test ./internal/record -bench . と PTY ハーネスを使って、ご自身でも実行できます。

• キー入力の遅延： 素のシェルと比べて、エコー遅延の中央値が +0.05 ms（0.22 ms 対 0.16 ms、p95 は +0.1 ms）です。60 Hz のフレームは 1 回あたり 16.7 ms なので、体感できません。
• 大量の出力： 27 MB のファイルをレコーダー経由で cat すると、処理速度は約 31 MB/s です。素の PTY では約 56 MB/s です。端末エミュレーターの描画はどちらよりもはるかに遅いため、レコーダーが待ち時間の原因になることはありません。
• 解析： OSC 133 セグメンターは 1 コアで約 680 MB/s の速度でスキャンします。head/tail キャプチャバッファーは memcpy の速度（約 44 GB/s）で書き込みます。
• ディスク： 出力は zstd で圧縮され、コマンドごとに上限が設定されます（デフォルトでは先頭 256 KiB ＋ 末尾 1 MiB、設定可能）。検索インデックスは独自のプレーンテキストコピーを保持せず、圧縮ストアを読み取ります（fts5 external content）。素朴な構成と比べてデータベースのサイズはおよそ半分になり、出力の多い同一の 1,000 コマンドのワークロードで 28.2 → 14.9 MB でした。対話型の作業を通常どおり 1 日行うと、1 つの SQLite ファイルに数 MB が追加されます。backscroll prune --older 30d は直近の期間のデータを維持し、backscroll prune --max-size 500M は古い項目を削除してデータベース全体のサイズに上限を設けます。どちらもファイルを完全に圧縮します。

プライバシーに関する注意事項

ターミナルの出力をすべて記録することが目的であり、責任でもあります。backscroll は設計上、ローカルのみで動作します。それでも、次の点にご注意ください。

• 無視パターン：~/.config/backscroll/ignore に Go の正規表現を1行に1つずつ記述すると、一致するコマンドは保存されません。

  ^vault
  ^op\b
  password|token|secret
  

• backscroll off を実行するとセッション中の記録が一時停止し（backscroll on で再開）、認証情報をすばやく入力できます。

• backscroll delete <id> を実行すると、エントリー（およびその FTS インデックス）が削除されます。シークレットが出力されてしまった場合に使用してください。

• マスキング：backscroll redact <id> を実行すると、エントリーに含まれてしまったシークレット（AWS／GitHub／Slack／Stripe／OpenAI／Google／npm／PyPI／GitLab のトークン、JWT、password=／api_key: の値、URL 内の認証情報、Authorization: ヘッダー、秘密鍵ブロック）が、コマンドライン、出力、検索インデックスで恒久的にマスキングされます。show --redact と export --redact も同様の処理を非破壊的に行うため、保存済みのコピーがそのままでも、課題に貼り付ける内容からシークレットを除去できます。独自のパターンを追加するには、~/.config/backscroll/redact に Go の正規表現を1行に1つずつ記述してください。パターンベースのマスキングは完全ではありません。共有する前に目視で確認してください。

• backscroll prune --older 30d は一定期間のデータを保持します。--max-size 500M を指定すると、データベースの合計サイズに上限を設定できます（古いエントリーから削除されます）。

• データベースはホームディレクトリ内にあり、所有者のみがアクセスできます（ディレクトリは 0700、ファイルは 0600。v0.11.1 以降、開くたびに適用されます）。同じ種類のデータが含まれるシェル履歴ファイルと同様に扱ってください。保存時に暗号化されません。Unix アカウント（または root）にアクセスできる人は、~/.bash_history、~/.ssh、ブラウザープロファイルと同じように読み取れます。脅威モデルにディスクが管理下から持ち出される可能性が含まれる場合は、ディスク全体を暗号化してください。同期を使う場合は ~/.config/backscroll/sync.key も同様です。これを持つ人は同期された履歴を読み取れるため、同期フォルダー自体には置かないでください。

• 共有アカウントでは実行しないでください。

• ダウンロードしたファイルを検証してください（v0.12.1 以降）：各リリース成果物には署名付きのビルド来歴アテステーションが付属しており、誰かのノート PC 上ではなく、このリポジトリの公開リリースワークフローによってタグ付けされたコミットからビルドされたことを証明します。tarball、パッケージ、チェックサムファイルは、次の方法で確認できます。

  gh attestation verify backscroll_linux_amd64.tar.gz -R soren-achebe/backscroll
  

• ネットワーク：ネットワークに接続するコマンドは backscroll upgrade だけです。実行した場合に限り、GitHub からリリースを取得します。バックグラウンドでの更新確認やテレメトリーはなく、記録、検索、サーブ、同期によって接続が行われることもありません。

これらの制御を回避する方法を見つけた場合は、脆弱性に該当します。非公開での報告方法と脅威モデルの全容については、SECURITY.md をご覧ください。

ステータス

初期段階ですが、Linux と macOS では bash、zsh、fish、nushell に、Windows では PowerShell（ConPTY）に対応しています。さらに、履歴のインポート（atuin／zsh／bash／fish）、無視パターン、セッションの一時停止（off／on）、出力の差分表示、fzf ピッカー（pick、Ctrl-X Ctrl-P、tmux ポップアップ）、マシン間の暗号化同期、AI エージェント向けの MCP サーバー、ローカル Web UI（serve）、doctor コマンドも利用できます。Issue と PR を歓迎します。CONTRIBUTING.md をご覧ください。 バージョンごとの詳細は変更履歴をご覧ください。

ライセンス

MIT