---
slug: "pi-tui-history-replay"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/Molaison/pi-tui-history-replay@main/README.md"
repo: "https://github.com/Molaison/pi-tui-history-replay"
source_file: "README.md"
branch: "main"
---
# pi-tui-history-replay

[![npm version](https://img.shields.io/npm/v/pi-tui-history-replay)](https://www.npmjs.com/package/pi-tui-history-replay)
[![Pi package](https://img.shields.io/badge/Pi-package-6c5ce7)](https://pi.dev/packages/pi-tui-history-replay)
[![license](https://img.shields.io/npm/l/pi-tui-history-replay)](https://github.com/Molaison/pi-tui-history-replay/blob/main/LICENSE)

Keep Pi's visible transcript in chronological order across context compaction.

```text
former turns  →  compaction summary  →  new turns
```

Pi still sends only its compacted context to the model. This extension repairs
the interactive TUI replay path; it does not put old raw turns back into the
LLM context.

Zero configuration. Zero runtime dependencies. TUI only.

## Why

Context compaction and transcript display solve different problems:

- The model needs a smaller, compaction-aware context.
- The person at the terminal needs the conversation in the order it happened.

`pi-tui-history-replay` keeps those paths separate. It renders the full active
session branch with Pi's native message and tool components while leaving
`SessionManager.buildSessionContext()` untouched.

## Install

Install from the Pi package catalog:

```bash
pi install npm:pi-tui-history-replay
```

Then start a new interactive session, or run `/reload` in the current one.
There are no commands or settings to configure.

You can also install the current GitHub version:

```bash
pi install git:github.com/Molaison/pi-tui-history-replay
```

If you previously copied or symlinked `tui-history-replay.ts` into
`~/.pi/agent/extensions/`, remove that old installation before installing the
package. Loading both copies would register the extension twice.

## What changes

| Path | Behavior |
| --- | --- |
| Interactive TUI transcript | Shows the full active branch in order |
| Compaction summary | Stays at its chronological position |
| Model context | Uses Pi's original compaction-aware context |
| Session storage | Adds no replay entries |
| Print, JSON, and RPC modes | Unchanged |
| Entries from older releases | Legacy replay entries are hidden |

## How it works

The extension installs a TUI-only in-memory patch when a session starts:

1. Transcript rebuilds read `SessionManager.getBranch()` instead of the
   compaction-pruned display entries.
2. When Pi emits `session_compact`, the persisted compaction entry is tracked.
3. Pi's live-compaction rebuild already appends a synthetic summary, so the
   persisted copy is omitted from that one rebuild to avoid a duplicate.
4. Later rebuilds use the complete branch, including the persisted summary.

The model-context method is never replaced. If Pi's compaction event and branch
state disagree, the extension throws a visible error instead of silently
rendering an incorrect transcript.

## Compatibility

The extension depends on Pi's interactive transcript rebuild behavior.

| Pi version | Status |
| --- | --- |
| `0.80.6` | Validated |
| `0.81.1` | Validated |

Versions older than `0.80.6` and newer versions not listed above are untested.
When reporting a compatibility issue, include the output of:

```bash
pi --version
```

## Update and remove

Update the package with Pi:

```bash
pi update npm:pi-tui-history-replay
```

Remove it with:

```bash
pi remove npm:pi-tui-history-replay
```

Run `/reload` after updating or removing it from an active session.

## Development

Requirements:

- Node.js `22.19.0` or newer
- Pi `0.80.6` or newer from the compatibility table

Install development dependencies and run the checks:

```bash
npm install
npm run check
npm pack --dry-run
```

Try the local extension without installing it:

```bash
pi --no-extensions -e ./tui-history-replay.ts
```

The regression tests cover:

- chronological active-branch replay;
- the one-rebuild live-compaction summary rule;
- non-TUI isolation;
- visible failure when the pending compaction entry is missing; and
- hiding legacy replay entries.

## Security and scope

Pi extensions execute with the same system access as Pi. Review extension code
before installing third-party packages.

This extension does not access the network, read or write project files, inject
prompt text, or register model-callable tools. Its runtime work is limited to
Pi session events and the in-memory TUI transcript builder.

## License

[MIT](https://github.com/Molaison/pi-tui-history-replay/tree/HEAD/LICENSE) © Molaison