Appearance
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 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 for stream ordering and reconnect recovery.