Scrollback and reading history

You will read the last 100 retained rows as text. Start with a live main-thread terminal.

1. Read rows

history.ts

import type { Terminal } from 'ghostty-webgpu'

export function readHistory(terminal: Terminal) {
  const count = terminal.lineCount()
  const lines = terminal.readLines(Math.max(0, count - 100), count, { trimRight: true })
  return lines.map((line) => line.text).join('\n')
}

lineCount includes retained history and visible rows, including empty visible rows. readLines(start, end) reads a half-open interval. Each row has text and wrapped. wrapped means that row soft-wraps into the next row.

2. Choose retention

appearance.scrollbackLimit budgets physical history rows, excluding the active screen. Ghostty prunes whole pages and permits at least one standard page of rows. Small values, including scrollbackLimit: 0, can therefore retain history. Pages that overlap the active screen stay whole, and page capacity depends on terminal width, styles and graphemes.

appearance.scrollbackByteLimit budgets logical page allocations, including the active area. A positive value is raised to Ghostty’s minimum allocation for the active area plus one extra page. scrollbackByteLimit: 0 erases retained history and disables further scrollback. Both budgets apply independently; the first reached triggers pruning. Read lineCount for the current history plus active rows.

retention.ts

import type { Terminal } from 'ghostty-webgpu'

export async function chooseRetention(terminal: Terminal) {
  await terminal.setAppearance({
    scrollbackLimit: 10000,
    scrollbackByteLimit: 64 * 1024 * 1024,
  })
}

export async function disableHistory(terminal: Terminal) {
  await terminal.setAppearance({ scrollbackByteLimit: 0 })
}

A single readLines call returns at most 1,024 rows. Paginate larger reads by advancing by the number returned. Writes, eviction and reflow between calls can shift row indices. Use a paused producer when you need a stable export.

3. Read the active screen

History reads use current emulator state, even before the terminal paints. While the alternate screen is active, reads cover that screen. Return to the primary screen to read its retained history. visibleLines reads the last submitted viewport frame.

If it doesn’t work

A read returns fewer rows than requested

Check the per-call cap, current count and active screen. Bounds clamp to the retained range.

A reload shows the old frame but the shell state is empty

A captured viewport restores paint. Restore the emulator through replay or a server session protocol. The saved viewport guide describes the visual checkpoint.

Next, read how damage tracking works.