Metadata-Version: 2.4
Name: scrollback
Version: 0.2.0
Summary: Navigate, search, copy, and export your AI coding-agent sessions (opencode, Claude Code, ...) from one local, read-only tool.
Project-URL: Homepage, https://github.com/a-attia/scrollback
Project-URL: Repository, https://github.com/a-attia/scrollback
Project-URL: Issues, https://github.com/a-attia/scrollback/issues
Author: Ahmed Attia
License: MIT
License-File: LICENSE
Keywords: ai-agent,claude-code,cli,local-first,opencode,session-history,transcript
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Provides-Extra: all
Requires-Dist: fastapi>=0.110; extra == 'all'
Requires-Dist: jinja2>=3.1; extra == 'all'
Requires-Dist: pywebview>=5.0; extra == 'all'
Requires-Dist: rich>=13.0; extra == 'all'
Requires-Dist: uvicorn>=0.29; extra == 'all'
Provides-Extra: app
Requires-Dist: fastapi>=0.110; extra == 'app'
Requires-Dist: jinja2>=3.1; extra == 'app'
Requires-Dist: pywebview>=5.0; extra == 'app'
Requires-Dist: uvicorn>=0.29; extra == 'app'
Provides-Extra: dev
Requires-Dist: fastapi>=0.110; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: rich>=13.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: uvicorn>=0.29; extra == 'dev'
Provides-Extra: rich
Requires-Dist: rich>=13.0; extra == 'rich'
Provides-Extra: screenshots
Requires-Dist: fastapi>=0.110; extra == 'screenshots'
Requires-Dist: jinja2>=3.1; extra == 'screenshots'
Requires-Dist: playwright>=1.40; extra == 'screenshots'
Requires-Dist: pywebview>=5.0; extra == 'screenshots'
Requires-Dist: rich>=13.0; extra == 'screenshots'
Requires-Dist: uvicorn>=0.29; extra == 'screenshots'
Provides-Extra: web
Requires-Dist: fastapi>=0.110; extra == 'web'
Requires-Dist: jinja2>=3.1; extra == 'web'
Requires-Dist: pywebview>=5.0; extra == 'web'
Requires-Dist: uvicorn>=0.29; extra == 'web'
Description-Content-Type: text/markdown

# scrollback

[![CI](https://github.com/a-attia/scrollback/actions/workflows/ci.yml/badge.svg)](https://github.com/a-attia/scrollback/actions/workflows/ci.yml)

Browse, search, copy, and export your AI coding-agent sessions from one
local, read-only tool. scrollback reads the conversation history that
agents like **opencode** and **Claude Code** already keep on disk and gives
you a single, consistent view across them — from a scriptable command line
or a local web app.

Everything is local-first and strictly **read-only**: scrollback never
modifies, locks for writing, or uploads your data.

You can use it two ways. From the **command line**, list, search, and export
your sessions in a single scriptable tool:

![scrollback listing recent sessions in the terminal.](https://raw.githubusercontent.com/a-attia/scrollback/v0.2.0/assets/screenshots/cli.png)

Or open the **local web app** to read a transcript in full — with rendered
Markdown, syntax-highlighted code, and typeset LaTeX math:

![The scrollback web app showing a session list beside a transcript with
rendered Markdown, highlighted code, and typeset equations.](https://raw.githubusercontent.com/a-attia/scrollback/v0.2.0/assets/screenshots/web.png)

Both views read the same on-disk session stores, so you can jump between
them freely. (The screenshots above use synthetic demo data.)

> **For AI agents:** read [`CONTRIBUTING.md`](CONTRIBUTING.md) for the
> project conventions. This README is for human readers.

## Contents

- [Why scrollback](#why-scrollback)
- [Install](#install)
- [Quick start](#quick-start)
- [The command line](#the-command-line)
- [The web app](#the-web-app)
- [Running it as an app](#running-it-as-an-app)
- [Fast search (optional index)](#fast-search-optional-index)
- [Supported sources](#supported-sources)
- [Configuration](#configuration)
- [Safety](#safety)
- [Development](#development)
- [License](#license)

## Why scrollback

AI coding agents persist rich session data locally, but each in its own
format and with no convenient way to browse that history or take it with
you. scrollback fills that gap with four things:

- **See** any past conversation as a readable transcript.
- **Search** across every session by keyword (title or full text).
- **Export** a session to Markdown, JSON, HTML, or plain text.
- **Copy** a message or a whole session straight to your clipboard.

Its niche among similar tools: pure Python, works equally from the
**CLI and a web UI**, reads **multiple agents** directly from their live
on-disk stores (no sync step, no plugins, no upload), and treats
**export and copy** as first-class.

## Install

```bash
pip install "scrollback[all]"      # CLI + web app + native window + colour
```

Requires Python 3.10+. The bare CLI has **no runtime dependencies**
(standard library only); optional features come from extras:

- `"scrollback[web]"` — the local web app (FastAPI, uvicorn) and the native
  app window (pywebview).
- `"scrollback[rich]"` — coloured terminal output.
- `"scrollback[all]"` — everything a user might want at runtime (`web` + `rich`).

If you'd rather keep it isolated from your system Python (recommended, but
optional), [`pipx`](https://pipx.pypa.io) installs it in its own environment
and still puts the `scrollback` command on your PATH:

```bash
pipx install "scrollback[all]"
```

Either way, plain `pip` works the same; `pipx` is just a convenience.

From a local clone (for development), use an editable install with the dev
extra:

```bash
pip install -e ".[web,dev]"
```

## Quick start

```bash
scrollback doctor          # what was detected on this machine?
scrollback list            # recent sessions, newest first
scrollback show latest     # print the most recent transcript
scrollback web             # open the browser UI
```

`scrollback doctor` is the best first command: it reports which agents
were found, how many sessions each has, and which optional features are
available.

## The command line

The CLI is organised around a few verbs. Commands that operate on a single
session accept a **selector**: a full id, a unique prefix, a
source-qualified id (`opencode:ses_0eae9810`), or the keyword `latest`.

### Listing and viewing

```bash
scrollback list --source opencode -n 10   # one source, 10 rows
scrollback list --dir myproject           # filter by directory substring
scrollback list -q "refactor"             # filter by title substring
scrollback list --since 2026-06-01 --until 2026-06-30   # date range
scrollback list --usage                   # add cost + token (in/out) columns
scrollback list -n 20 --page 2            # pagination (page size = --limit)

scrollback show latest --reasoning        # include the model's thinking
scrollback show <selector> --no-tools     # hide tool calls and output
```

By default, subagent sessions (for example opencode `@explore` subagents)
are **folded** under their parent; pass `--no-fold` to list them flat.
Output is coloured when the `rich` extra is installed and the output is a
terminal; piping, or `--plain`, falls back to plain text.

### Searching

```bash
scrollback search "merge conflict"        # full-text across all sessions
scrollback search "ssh" --source opencode --json
```

Search scans message text across sessions. On a large history you can make
it near-instant with an [optional index](#fast-search-optional-index).

### Exporting and copying

```bash
scrollback export latest -f markdown -o session.md
scrollback export <selector> -f html -o session.html
scrollback export <selector> -f html --math rendered -o session.html
scrollback export <selector> -f json      # to stdout
scrollback copy latest -f markdown        # render and copy to the clipboard
```

The formats are `markdown` (`md`), `json`, `html`, and `text` (`txt`).
Markdown, HTML, and text honour `--reasoning` (include the model's
thinking) and `--no-tools` (omit tool calls and their output); JSON is a
faithful structured dump with bulky raw blobs stripped for readability.
Exported HTML and Markdown render the assistant's Markdown with syntax-
highlighted code, and the HTML is a self-contained file that prints well.

Mathematical notation in delimited LaTeX (`$...$`, `$$...$$`, `\(...\)`,
`\[...\]`) is preserved verbatim in every format, never mangled by the
Markdown pass. `--math` controls how the HTML export treats it: `raw`
(verbatim source, the default), `latex` (verbatim, marked never-to-typeset
— best for pasting into a paper), or `rendered` (typeset with KaTeX, which
is embedded into the file with its fonts so the equations render offline).
In the web app the same choice is a `math:` toggle in the transcript header.

### Stats and resume

```bash
scrollback stats                          # totals, by-source + top projects
scrollback resume latest                  # print the native resume command
scrollback resume <selector> --copy       # ...and copy it to the clipboard
```

`stats` aggregates session counts, message/token/cost totals, and your
busiest projects. `resume` prints the command to continue a session in its
own agent (for example `opencode --session <id>` or `claude --resume <id>`),
with a `cd` into the session's project directory.

**A note on token figures.** Where the source records it, scrollback reports
tokens in four buckets — *input*, *output*, *cache read*, and *cache write* —
because they mean different things and are priced very differently. In
agentic sessions the conversation context is re-sent every turn but served
from the prompt cache, so **cache reads usually dominate total volume** while
costing a fraction of fresh input. "Total tokens" is therefore not one
number; the cost figure (when available) is the most faithful summary of
consumption. Sources that don't record a given figure show it as blank
rather than a misleading zero.

## The web app

`scrollback web` starts a local, read-only browser UI — FastAPI plus a
small vanilla-JavaScript frontend with no build step — bound to
`127.0.0.1`. Open it with `scrollback web` (a browser tab),
`scrollback web --window` (a standalone browser window), or
`scrollback web --app` (a native desktop window; see
[Running it as an app](#running-it-as-an-app)).

What it offers:

- A **session list** with source-filter chips, date filters, and a
  **home** button to reset everything; it loads incrementally as you
  scroll.
- An explicit **search scope** toggle — search session **titles**, message
  **contents**, or both at once (combined results are grouped).
- **Subagents** collapsed under their parent, expandable on demand
  (including Claude Code's nested sidechain transcripts).
- A **transcript reader** with a **collapsible** frozen header (auto-
  collapses as you scroll; toggle with `h`) over a scrolling message body,
  **Markdown rendering with syntax highlighting**, **LaTeX math** (source /
  paste-ready / typeset), in-transcript find, show-reasoning / show-tools
  toggles, and per-message and per-session copy.
- **Export** (Markdown / HTML / JSON), **print**, a **light/dark theme**,
  and **keyboard navigation** (`/` search, `j`/`k` move, `Enter` open,
  `f` find, `h` collapse header, `Esc` blur).

Large transcripts open instantly because the app loads a session's header
first and then pages messages in as you scroll, rather than transferring an
entire multi-megabyte transcript at once. Deep links work too: the open
session is reflected in the URL hash (`#opencode/<id>`), and `?q=<text>`
pre-fills a content search.

## Running it as an app

You don't have to type a command every time. After `pip install ".[web]"`:

- **Short commands** are on your `PATH`: `scrollback-web` (a browser tab)
  and `scrollback-app` (a native window).
- **A double-clickable launcher** is one command away:

  ```bash
  scrollback install-launcher               # both: Desktop launcher + .app (macOS)
  scrollback install-launcher --desktop     # only the Desktop launcher
  scrollback install-launcher --app-bundle  # only the ~/Applications/.app (macOS)
  ```

  With no flags it installs everything for your OS; the two flags let you
  pick just one. The Desktop launcher is `scrollback.command` on macOS,
  `scrollback.bat` on Windows, and an application-menu entry plus
  `scrollback.sh` on Linux. `--app-bundle` builds an
  `~/Applications/scrollback.app` on macOS and falls back to the Desktop
  launcher on other platforms (where there is no `.app`). Use `--dest <dir>`
  to place artifacts elsewhere.

The launchers open a **native window** via pywebview when it is available:
no browser tab, no terminal, and **closing the window stops the server and
frees the port**. On a system where pywebview cannot run (for example a
headless Linux box without a GTK/Qt WebKit backend), scrollback falls back
to a standalone browser window that auto-stops the server shortly after the
window closes. All of this behaviour is decided in Python, so the launcher
scripts stay free of OS-specific assumptions and ship inside the package
for `pip install` users.

To clean up, `scrollback uninstall` removes the artifacts scrollback
created — the launchers, the macOS `.app`, the optional search index, and the
launcher log — after a confirmation (`--yes` to skip it, `--dry-run` to
preview). It never touches your agent data, and it does not remove the Python
package itself: it prints the right `pip`/`pipx uninstall` command to finish
the job (a program can't reliably uninstall the package it is running from).

## Fast search (optional index)

By default, search is a lexical scan over your live data: zero setup,
always correct, but its cost grows with the size of your history. For a
large corpus, build an optional full-text index:

```bash
scrollback index            # one-time build; re-run to update (incremental)
scrollback index --stats    # show what's indexed
scrollback index --clear    # delete the index
```

The index is a separate SQLite FTS5 database at
`~/.cache/scrollback/index.db` (override with `SCROLLBACK_INDEX`). It is
derived and disposable: your source data is never modified, and deleting
the index simply reverts to the lexical scan. Re-running `index` only
re-processes new or changed sessions and prunes deleted ones; the web app
also refreshes it in the background on startup when it is stale.

Once built, both the CLI and the web app use it automatically, turning a
multi-second query into a few milliseconds. If your Python's SQLite was
built without FTS5, `index` says so and search keeps working without it.

## Supported sources

| Source       | Reads                                                       | Default location                       |
|:-------------|:-----------------------------------------------------------|:---------------------------------------|
| `opencode`   | SQLite (`session` / `message` / `part`), read-only         | `~/.local/share/opencode/opencode.db`  |
| `claudecode` | per-project JSONL transcripts + nested subagent sidechains  | `~/.claude/projects/`                   |
| `codex`      | per-session `rollout-*.jsonl` rollouts                      | `~/.codex/sessions/`                    |
| `aider`      | per-project `.aider.chat.history.md` Markdown logs          | set `SCROLLBACK_AIDER_DIRS` to opt in  |

More agents (Gemini CLI, Zed, VS Code Copilot Chat, GitHub Copilot CLI) are
researched and queued — see [`ROADMAP.md`](ROADMAP.md).

Adding another agent is a small, self-contained change: implement the
`Source` interface in `src/scrollback/sources/base.py` and register it in
`src/scrollback/sources/registry.py`. The CLI, search, export, web app,
and index all work against the common model automatically — see the
opencode (SQLite) and Claude Code (JSONL) adapters as references, and
[`CONTRIBUTING.md`](CONTRIBUTING.md) for the conventions.

## Configuration

scrollback reads each agent's data from its default location, but you can
point it elsewhere, and you can control how the web server binds:

| Variable                  | Purpose                                                      |
|:--------------------------|:------------------------------------------------------------|
| `SCROLLBACK_OPENCODE_DB` | path to `opencode.db`                                       |
| `SCROLLBACK_CLAUDE_DIR`  | path to `~/.claude` or `~/.claude/projects`                |
| `SCROLLBACK_CODEX_DIR`   | path to `~/.codex` or `~/.codex/sessions`                  |
| `SCROLLBACK_AIDER_DIRS`  | colon-separated dirs to scan for Aider history (opt-in)     |
| `SCROLLBACK_PORT`        | web server port (default `8765`; or use `--port`)           |
| `SCROLLBACK_HOST`        | web server bind host (default `127.0.0.1`; or use `--host`) |
| `SCROLLBACK_INDEX`       | path to the search index database                          |

The web server defaults to `127.0.0.1`. If the chosen port is busy,
scrollback automatically picks the next free one (`--strict-port` fails
instead). Binding to a non-loopback host prints a warning, since the
read-only API is unauthenticated.

## Safety

scrollback is read-only by design, and the design is enforced:

- The opencode SQLite database is opened with `mode=ro` — it is never
  created or written, and reads are safe against a live write-ahead log.
- Claude Code JSONL files are read as read-only.
- A test asserts the opencode database's modification time is unchanged
  across reads (`tests/test_sources_live.py`).
- The web app binds to localhost, rejects unexpected `Host` headers (a
  DNS-rebinding guard), and sanitizes rendered transcript content.

## Development

```bash
pip install -e ".[web,dev]"
pytest -q             # tests
ruff check src tests  # lint
```

See [`CONTRIBUTING.md`](CONTRIBUTING.md) for project conventions (the
read-only invariant, stdlib-first dependencies, platform-agnostic code,
and how to add a new agent source) and [`CHANGELOG.md`](CHANGELOG.md) for
what has landed so far.

## License

MIT — see [`LICENSE`](LICENSE).
