# Terminal History

NTerminal is tuned for terminal-first work in TUIs such as Codex and Claude, where mouse wheel behavior and long output history matter.

## Mouse Wheel Behavior

Wheel events are captured at the pane level and applied to xterm scrollback. This keeps the wheel focused on terminal output history instead of Codex/Claude prompt history.

If a pane is in the alternate screen, NTerminal exits the alternate buffer before scrolling so the scrollback can be shown.

## Incremental tmux Scrollback

When tmux-backed persistence is available, NTerminal loads older scrollback on demand:

- older lines are requested only when the viewport reaches the top
- each page is capped to avoid large one-shot payloads
- a spinner appears while older history is loading
- the visible position is preserved when lines are prepended

This avoids sending an entire long terminal history to the browser during tab or server switches.

## Scroll Progress And Bottom Controls

Panes can show:

- a faint `current/total` progress indicator before scrolling
- a stronger progress indicator while actively scrolling
- a bottom-right jump-to-bottom button when the operator is away from the tail
- larger mobile drag handles for touch scrolling

Live output follows the tail unless the operator intentionally scrolls away.

## Codex / Claude JSONL History

After tmux scrollback is exhausted, supported Codex and Claude panes can continue into archived JSONL transcript history.

Supported panes show a `JSONL` indicator in the pane header.

Sources:

- Codex: `~/.codex/sessions`
- Claude: `~/.claude/projects`

NTerminal attaches JSONL history only when it can determine the session source unambiguously. It does not guess by fuzzy scoring.

JSONL records are loaded by cursor and rendered into readable user, assistant, and tool blocks. NTerminal does not send the full archive to the browser at once.

## Persistence Boundaries

- Refreshing the browser or temporarily losing the WebSocket should reconnect to active PTYs while the Node process is still running.
- Restarting the NTerminal Node server preserves active shells when `tmux` is installed and `NTERMINAL_PTY_PERSIST` is not disabled.
- Without tmux, Node restarts kill direct PTYs.
- An OS reboot terminates NTerminal, tmux, and all live shells.
- Codex/Claude JSONL transcript files are managed by those tools and are not stored in NTerminal state.
