backscroll — Claude Code MCP server: what it does, how to install
Records full terminal output into a local SQLite database so you can search logs, inspect errors, and compare runs. Useful when scrollback is lost after a terminal restart.
Open on GitHubWhat backscroll does
Standard shell history saves the commands you ran, leaving out the console response. backscroll wraps your terminal shell via a pseudo-terminal PTY, segmenting every stream using OSC 133 prompt markers. Command output and exit codes land in a local SQLite file at ~/.local/share/backscroll/backscroll.db. The tool runs without background daemons or remote tracking.
Stored outputs are compressed with zstd. Substring lookups rely on SQLite FTS5 trigram indexes, matching text regardless of character case. Full-screen interactive tools like vim or htop bypass the recorder so the database avoids terminal escape noise. For large outputs, head and tail chunks are retained.
Terminal captures do not happen invisibly: you must start them using backscroll run or integrate the hook into ~/.zshrc, ~/.bashrc, or fish config. When a terminal tab exits abruptly, the recorder flushes whatever output accumulated before closing.
What it helps with
- search past terminal outputs for lost tokens, errors, or IP addresses
- compare output differences between two runs using
backscroll diff - recover output text from closed terminal windows or tmux panes
- export past commands and output into markdown for bug reports
Example prompts for the agent
- Find the permission denied error in past terminal output and show the details
- Diff the outputs of the last two terraform plan executions recorded by backscroll
- Show me the full console output from the command before last
How to install backscroll
Install
The MCP registry has no launch command for it: see the repository README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about backscroll
How do I install backscroll?
On Linux and macOS, install it using the automated script: curl -fsSL https://raw.githubusercontent.com/soren-achebe/backscroll/main/install.sh | sh.
What does the backscroll MCP server do?
It gives AI assistants read access to the local database of recorded terminal runs. The agent can search past console logs by keywords, pull full outputs, and compare differences across runs.
Where does backscroll store captured output?
Everything stays on your local machine inside ~/.local/share/backscroll/backscroll.db. The tool sends no telemetry to the cloud and operates without background server daemons.
