Point durable-lens at the SQLite file or JSONL directory of a pi-durable harness, running or not. It shows the transcript, the task graph, the documents, and what every turn cost and how long it took, on one timeline. It never runs your harness and never writes to your store, so you can point it at one a live process owns.
Quick start
durable-lens needs Node.js 22.13 or later. It has no runtime dependencies. To try it on a store that a real pi-durable 1.4.0 wrote, which the repository includes:
git clone --depth 1 https://github.com/dggc/durable-lens.git
npx durable-lens durable-lens/fixtures/stores/1.4.0/sqlite/session.sqlite --restart-limit 3 --open
--restart-limit 3 is the limit its scenario used, so that its parked task shows as parked. durable-lens prints a local address with a random token and keeps running until you press Ctrl-C:
durable-lens: pi-durable 1.4 or later, 3 conversations, 27 tasks
http://127.0.0.1:38135/lT-dAgpmrBe1XrmFtxZUHHz6/
read-only; Ctrl-C to stop
Open that address in a browser if --open did not. Then point it at your own store:
npx durable-lens ./session.sqlite # or a JSONL storage directory
The store is the path your harness passes to openNodeSqliteStorage(path) or openNodeJsonlStorage(path). A SQLite store is a file. A JSONL store is a directory that contains main.jsonl.
To keep it installed instead, run npm install --global durable-lens, then durable-lens ./session.sqlite.
What it shows
- Timeline. Every entry in order, with its time and the gap since the one before. Assistant turns show model, latency, tokens and cost; thinking is collapsed. Tool calls link to their results, their tasks and the subagent conversations they started. A strip above shows each generation and tool call as a bar on the same clock.
- Task graph. Every task with its owner edges:
waiting on which tasks and with which policy, sleeping until when, pending after a crash, parked after crashing restartLimit times in a row, and the outcome and error of finished ones. Input, checkpoint and outcome are one click away.
- Documents. pi-durable's own (
pi.agent, pi.usage, pi.inbox, ...) and yours, materialized from their stored bases and deltas. Rewindable documents get a slider that steps back through their revisions.
- Usage. Cost and tokens by model, by tool and by conversation, from each conversation's
pi.usage, which also counts failed and aborted attempts.
- Forks side by side. A fork shows where it branched and what it inherited; compare branches puts the parent's continuation and the fork's next to each other.
The page follows the store: when the files change, it rereads them.
| Timeline | Transcript |
|---|
| |
| Task graph | Documents |
| |
| Fork comparison | Usage |
| |
Safe on a live store
durable-lens opens nothing of yours for writing. That takes more care than a read-only flag:
| Way to open | Writes beside the store? | Sees the latest commits? |
|---|
SQLite, readOnly: true or mode=ro | yes: creates -wal and -shm on an idle database, rewrites -shm on a live one | yes |
SQLite, immutable=1 | no | no: skips the WAL, so a crashed or running store looks stale |
pi-durable's storage with HarnessOptions.readOnly (main) | yes: migrates a schema v1 database to v2, checkpoints the WAL into the database file, truncates a torn JSONL line | yes |
| durable-lens | no | yes |
For SQLite, durable-lens copies the database and its WAL into a private temporary directory (a reflink where the filesystem has them) and opens the copy. The copy is accepted when the WAL header is the same before and after it, since a WAL reset in between could tear the copy, and, if there is no WAL with frames, the database's size and mtime are the same too; otherwise it copies again. For JSONL it reads the files, skips a last line still being appended, and reads again if the owner reclaimed a sidecar in between. It takes no locks, so it never slows the owner's checkpoints. The copy is a full copy of your transcripts: it lives in a directory only you can read, is deleted after each read, on exit and on Ctrl-C, and a later run deletes copies a killed process left behind.
The tests hash every file of every fixture before and after reading it, also while a pi-durable process holds the store open, and read 25 times while an owner commits every few milliseconds. See Reading pi-durable storage for the measurements.
This matters most for an older store. A pi-durable 1.2.0 database (schema v1) opened once by 1.4.0 code is migrated to v2 for good, and 1.3.0 or earlier can no longer open it.
Supported versions
| pi-durable | SQLite | JSONL |
|---|
| 1.2.0 | schema v1 | format 1 |
| 1.3.0 | schema v1 | format 1 |
| 1.4.0 | schema v2 (sleeping tasks, restart counts) | format 1 |
| main (36be9c6, 2026-10-23) | schema v2 | format 1 |
This is the beginning of the README. Read the rest at the original. Read the full README ↗
