---
url: https://clusto.app/docs/terminal-history.md
description: How Clusto loads, validates, renders, and fully reloads terminal history.
---

# Terminal History & Full Reload

Opening a session does not download its entire scrollback. The daemon collapses
the session's output into a snapshot. Non-touch desktop and web clients
initially request the **last 3000 rows** (`tail_rows`), while mobile and other
coarse-pointer touch clients initially request the **last 600 rows** so a
long-running session attaches without overwhelming the interface. Older rows
remain available in 1500-row pages as you scroll to the top of the terminal.

The daemon records PTY output throughout the active session's lifetime, so
reconnecting does not join an old beginning to a disconnected recent tail. This
is live-session history, not a permanent archive: cleanup on session
termination, PTY exit, and daemon restart still applies.

That is the right default, but sometimes you want the whole thing at once:

* You need to search (Ctrl+F) across output older than the loaded tail.
* The terminal drifted from the owner's screen (a flaky link dropped frames, a
  stale persisted preview was restored, or a take-over swapped the writer).
* You scrolled up far enough that paging through it one page at a time is slow.

## Switching terminals

A terminal you switch away from keeps running in the background, like a tab in
a native terminal app: it goes on parsing its session's live output and applying
its resize boundaries while it is out of view. Switching back shows exactly the
screen the program drew, with no reload and no snapshot replay. Full-screen
programs that repaint only the cells that changed (Claude Code, vim, htop) stay
aligned no matter how often you switch.

Clusto keeps the 8 most recently viewed background terminals live on desktop
and 3 on phones. A terminal beyond that is released, and opening it again starts
it fresh from the session's buffered output or a daemon snapshot. If a
background terminal falls so far behind that its pending output exceeds the
safety limit, Clusto drops that backlog and rebuilds the terminal from a daemon
snapshot when you return to it.

## Reconnect recovery

After a reconnect, every session stream resumes from the last output it
received. The daemon replays the frames sent while the connection was down, for
visible and background terminals alike, so nothing is reset. Returning from a
minimized or background app state only repaints the terminal display, because
the output kept arriving while the app was away.

When you are reading older output, a refresh preserves the visible text instead
of moving you to the newest rows. The reading position survives snapshot
replacement, width changes, and switching away long enough for the app to
release the off-screen terminal. If that text is no longer available, Clusto
uses the nearest remaining position. A terminal already following live output
continues following it.

Rows loaded by scrolling up, or by **Reload full history**, remain available
after later refreshes. While you are reading above the bottom, recovery requests
the available full history so a bounded tail cannot erase the reading position.
If you have not loaded older pages or requested a full reload, returning to the
bottom restores bounded history requests. The initial 3000-row and 600-row
limits remain unchanged, and the daemon's reconstruction ceiling still applies.

If a missing output range has already left the replay buffer, delivery pauses
until a fresh snapshot is ready. The client then resumes from the snapshot's
sequence boundary. This avoids clearing the terminal and applying an incomplete
fragment of a TUI repaint.

## Stable replay and resize

Clusto opens xterm only after its visible pane exists, rather than initializing
it inside a hidden holding area. New terminals therefore start with measurable
geometry and avoid a synthetic tiny first render. Initial geometry is estimated
from the actual viewport without forcing an 80x24 minimum. On Windows nodes,
the client also enables xterm's ConPTY-aware behavior even when the viewer is
running on another operating system.

Opening or closing the mobile keyboard does not resize the remote PTY, so it
does not enter the ordered resize path. The terminal is translated, scaled, or
left natural-size and scrollable entirely in the client according to the
selected keyboard presentation mode.

For a real pane or window resize, the owner publishes an ordered geometry
boundary. The client parses all older output at the old size, applies the new
rows and columns at that boundary, then parses newer output. It does not
clear and refetch history while the resize is still moving. This keeps the PTY
responsive and lets a live TUI repaint at each intermediate geometry.

A resize never rebuilds the terminal from a snapshot. The program's repaint at
the new size is ordinary output, applied in order like everything else.

A snapshot replaces a terminal only when it has no screen yet (the first open in
this app run, or a terminal released from the background pool) or has provably
lost output (a gap the daemon can no longer replay, or a dropped backlog). A
snapshot response carries the owner's actual geometry at the captured boundary,
and the client restores that geometry before replaying it.

History replacement remains ordered when output is still arriving. Clusto
writes the collapsed snapshot first, restores the TUI's captured terminal state
at the snapshot boundary, and only then appends live frames newer than the
snapshot. The restored state covers application cursor keys and keypad, origin,
line wrap, cursor visibility, insert/newline, focus reporting, mouse reporting,
and bracketed paste. Snapshots also restore the current and saved cursor
positions, their text styling, the scrolling region, and a pending line wrap.
This keeps subsequent cursor restores and partial-screen scrolling aligned with
the restored prompt. A newer live frame that changes any restored mode wins.
Live output is held while the snapshot is applied, so replacement cannot splice
or roll back a busy terminal.

When a full-screen program is running, the snapshot restores both screens: the
shell's output stays in the normal buffer and the program's screen is restored
on the alternate buffer, so the program keeps the screen it expects and exiting
it returns to the shell as usual. A synchronized repaint that was still in
progress at the snapshot boundary is included up to that point, and an escape
sequence split by the boundary is completed by the live output that follows, so
the rest of the repaint lands where the program drew it. Synchronized-output
mode itself is not restored because it is transient framing.

Each history response belongs to one request, including every chunk of a large
response. Overlapping requests cannot mix their chunks, and a late response or
persisted preview cannot replace a newer authoritative history. The daemon
captures the live boundary and durable recording position together, avoiding
duplicated output when more text arrives while history is read. If output
outpaces a response and leaves a gap, the client retries recovery.

Repeated recovery triggers share the pending history request while it is still
making progress. A slow response can finish without being repeatedly restarted;
an inactive request can still time out and be retried.

The daemon resets ANSI styling before each serialized row break. This keeps a
TUI's background color from bleeding into blank rows created when restored
history scrolls, which would otherwise appear as full-width color bars after a
reload.

The instant terminal preview persisted on the device is a cache, not the source
of truth. If the current app run does not already have a continuously subscribed
live buffer, Clusto loads that preview while requesting fresh daemon history in
parallel. A current live buffer appears immediately without waiting for the
device cache. Fresh history replaces stale previews containing duplicated TUI
frames left by an older app build. If no complete preview is available, Clusto
waits for the snapshot before displaying buffered live updates, so partial TUI
repaints do not appear as a broken initial screen.

A centered indicator accompanies the initial history fetch. Refreshes of a
current live buffer use a small corner indicator.

## Rendering and replay performance

Clusto uses WebGL terminal rendering on Linux, macOS, mobile, and browser clients.
If WebGL cannot start, its graphics context is lost, or 14 terminals
already hold a WebGL context, the terminal falls back to the DOM renderer
without interrupting the session. The native Windows desktop
app stays on the DOM renderer because that is the reliable path in WebView2.

Bare HTTP(S) URLs remain one complete link when the terminal soft-wraps them
across rows. Every visible segment is tappable, including on narrow mobile
screens, and opens the full URL rather than only the text on that row.

Terminals share a bounded render scheduler instead of each terminal draining
output independently. The foreground terminal is prioritized, while background
and off-screen terminals share a per-frame budget in round-robin order. Recent user
input temporarily reduces background work to a small trickle so echo, cursor
movement, and prompt interaction remain responsive during noisy builds. Writes
are split into bounded blocks and serialized on xterm's completion callback, so
the next block is not submitted until the parser finishes the current one.

If a terminal's pending render queue exceeds its safety limit, Clusto discards
that incomplete local queue and requests an authoritative snapshot, right away
for a visible terminal and on reopen for an off-screen one. This is safer than
continuing to parse a partial or unbounded escape sequence stream.

PTY input has a separate bounded queue in the daemon. Keystroke delivery never
blocks the daemon's async control path: if a session process stops consuming
input and the queue fills, Clusto reports backpressure rather than allowing an
unbounded queue to consume memory or stall unrelated sessions.

On Windows, the desktop app also pins the upstream Tao fix for a lock held
across `PeekMessageW`. This removes an event-loop deadlock that could freeze the
whole native app during terminal activity.

Initial local replay is bounded before it reaches the terminal parser. Desktop
clients accept at most 3000 rows or 768 KiB, while mobile clients accept at most
600 rows or 384 KiB. If a raw replay or cached preview exceeds those limits,
Clusto requests the daemon's VT-collapsed snapshot instead of replaying a long
sequence of obsolete TUI redraws. Older collapsed rows remain available through
normal history paging.

These startup limits do not trim an authoritative full reload or a page of
older history. Paging advances only after the older rows have been rendered.
If a redraw overlaps a page request, obsolete pages are ignored without
skipping those rows in the new history.

## Provider-specific TUI stability

Clusto starts Claude Code PTY sessions with
`CLAUDE_CODE_NO_FLICKER=1` unless the session environment explicitly provides
another value. This asks Claude Code to use its steadier rendering path without
overriding a user's deliberate setting.

Clusto also enables `CLAUDE_CODE_FORCE_SYNC_OUTPUT=1` so Claude Code wraps
repaints in synchronized-output boundaries that xterm applies atomically. On
Windows nodes, it additionally sets `CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT=1`.
The full-frame alternate-screen repaint prevents ConPTY from leaving stale or
misplaced prompt cells when positioned writes are combined during fullscreen
input. Each value is only a default: an explicit session environment value,
including an empty or disabled value, takes precedence.

Clusto passes Codex's terminal control sequences through unchanged. Rewriting
its partial-screen scrolling as full-screen line scrolling can shift the saved
cursor and make later typing appear beside a status line instead of the prompt.
Preserving the original output avoids that source of cursor drift.

Some Codex transcript rows moved out of its scrolling region may not appear in
the live client's scrollback. The daemon retains those rows when reconstructing
history from the session recording; use **Reload full history** to bring them
into the client.

## Reload full history

**Ctrl+Shift+H** (or right-click -> **Reload full history**) throws away what the
terminal currently shows and re-renders it from a fresh, complete daemon
snapshot - no tail limit and no scroll-up paging left to do.

The client grows its scrollback to hold the rows returned by the daemon rather
than passing the response through the startup tail limit.

On mobile there is no right-click (long-press opens
[touch selection](/terminal-touch-selection) instead), so the same action sits
behind the chevron in the terminal's key bar as the **Reload full history**
button.

The shortcut only fires for the terminal that has focus, so it never refetches
every pane in a split workspace. While the snapshot is in flight the usual
"Fetching session history…" indicator is shown, and the action is disabled so a
repeated chord cannot stack requests.

The indicator only appears on a blank terminal or for this action. Background
refreshes of a terminal that already shows content (a reconnect, a take-over) are
silent.

On desktop, the app keeps up to 32 terminal sessions (newest first, on online
nodes) streaming in the background and fetches their screen snapshots one at a
time, so opening one shows it from memory instead of waiting for history. A
session that loses its in-memory copy (resized from another device, or a busy
stream that overflowed the buffer) is re-warmed quietly, at most once per 30
seconds. Phones keep fewer streams to protect the WebView main thread.

## How output is recorded

The daemon records each terminal's output so history can be rebuilt after a
restart. It stores the output in flushes of up to 30 seconds or 64 KiB, whichever
comes first, instead of one database write per chunk, which writes about ten
times less to disk. A normal daemon stop or restart commits everything first, so
nothing is lost. A hard crash (power loss, `kill -9`) can lose up to the last 30
seconds of recorded scrollback of a busy terminal; the live screen and sessions
that keep running are not affected.

## Limits

The daemon reconstructs terminal history with a safety ceiling of **200000
scrollback rows**, plus the visible screen. Its row budget accounts for line
advances and wrapped text, rather than treating each output chunk as one row.
Recordings can contain many lines in a single chunk. History beyond this
reconstruction ceiling is not available through full reload or paging, even
when the raw recording still exists.

A collapsed snapshot reconstructs the display and selected terminal state; it
does not preserve every parser detail. Character-set selections active at the
snapshot boundary can still differ from uninterrupted live output. Terminals
that stay open keep their exact screen and never depend on a snapshot.

Reload is read-only: it re-reads the daemon's snapshot, it does not touch the
session, the PTY, or its output on disk. Read-only viewers of a claimed session
can reload just like the owner.

See [Transport & Resume](/transport) for stream ordering and reconnect
recovery.
