Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions docs/user/tui-and-sessions.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,29 +80,29 @@ Press `F3` to open the read-only transcript navigator, even while a response is
| `Ctrl+Up` / `Ctrl+Down` | Select the previous / next User prompt, switching to the User filter while retaining the query |
| `Enter` | Reveal and highlight the selected rendered block in the transcript |
| `Esc` / `F3` | Close without changing transcript scroll position, editor text, or attachments |
| Type `/branch`, then `Enter` | While idle, open the backend-approved text prompt checkout chooser |
| Type `/branch`, then `Enter` | While idle, open the backend-approved conversation checkpoint chooser |

Navigator queries are limited to 4,096 UTF-8 bytes. Oversized pastes keep a bounded whole-grapheme prefix; pasted newlines and tabs are ignored rather than activating navigator controls.

Revealing a Thought block temporarily shows it even when reasoning is hidden. Browsing and closing alone do not move the transcript; `Enter` explicitly reveals the selected block. While the navigator is open, `Esc` closes it rather than interrupting the turn.

The navigator searches only the currently displayed or replayed history, not a compacted archive or undelivered messages in the pending queue. Tool searches include display text such as the title, script, and output; media labels are searchable, but binary media payloads are not. Block identities are local and ephemeral, not durable addresses for forking. This is navigation only: it does not fork a session, write history, cancel a turn, or send a prompt.

### Edit a previous prompt in a new session
### Branch from a text checkpoint in a new session

While idle, type the exact local command `/branch`, or open `/transcript` (`F3`), type `/branch` in its search field, and press Enter. The separate checkout chooser lists only text prompts approved by the backend. Archived prompts are labeled `[archived]`; this list is authoritative, not inferred from the visible transcript. Use Up/Down to select a prompt and Enter to prepare an edit. Unsupported agents or ineligible prompts produce an error without changing the source session.
While idle, type the exact local command `/branch`, or open `/transcript` (`F3`), type `/branch` in its search field, and press Enter. The separate checkout chooser lists only conversation checkpoints approved by the backend, labeled `[user]`, `[assistant]`, or `[tool]`. Archived checkpoints also show `[archived]`; this list is authoritative, not inferred from the visible transcript. Press `0` for All, `1` for User, `2` for Assistant, or `3` for Tool. Changing the filter selects its first match. Use Up/Down to select a checkpoint and Enter to prepare a draft; an empty filter has nothing to prepare. Filtering never changes the backend address used for checkout. Unsupported agents or ineligible checkpoints produce an error without changing the source session. `/transcript` remains a display-only navigator: its local block positions are not checkout addresses.

> Only conversation context changes. Filesystem changes, running processes, and external effects are not rolled back.

The TUI displays the backend's conversation prefix and puts the original prompt text in a **provisional prompt checkout** editor. Your source transcript, unsent editor draft, attachments, and model/configuration state are parked, not discarded. Edit the text, use Shift+Enter for a newline, then Enter to create and activate a new persisted session. No branch is created by merely browsing or preparing an edit. The edited prompt is persisted by branch submission itself; the TUI does not send it a second time as an ordinary prompt.
The TUI displays the backend's safe conversation prefix in a **provisional prompt checkout**. Selecting a user prompt starts **before** that prompt and prefills the editor with its unchanged text for replacement. Selecting an assistant message or tool result starts **after** its safe backend-approved boundary and opens an empty editor for a new user continuation; the chooser preview is not inserted as user text. Your source transcript, unsent editor draft, attachments, and model/configuration state are parked, not discarded. Edit or enter text, use Shift+Enter for a newline, then Enter to create and activate a new persisted session. Empty or whitespace-only drafts cannot be submitted. No branch is created by merely browsing or preparing an edit. The edited prompt is persisted by branch submission itself; the TUI does not send it a second time as an ordinary prompt.

Press Esc before submission to abandon the checkout and restore the parked source view, draft, attachments, and configuration. Esc also cancels a pending list or prepare request; late responses cannot replace a newer view. Once submission is in progress, wait for its result: Esc cannot undo a committed branch. A failed submit keeps the provisional draft available. Retry with the same text to recover a child if the response was lost. Once a submission reaches the backend, its checkout token is bound to that exact text; to submit a different edit, abandon and prepare a new checkout.

Checkout edits are text-only. Adding image or audio attachments is rejected; attachments already in the parked source draft remain intact. While the checkout chooser or provisional editor is active, model/configuration changes, session switching, ordinary sends, and steering are disabled. Slash-command text in the provisional editor is edited prompt text, not a local command.

The child retains the conversation strictly before the selected prompt, including its original bootstrap context. Archived prompts use validated pre-compaction history, never a later summary as a substitute for missing context. Prompts with unsupported content, unresolved tool calls in their prefix, or unreconstructable legacy context are not eligible.
The child retains the safe prefix before the selected user prompt or after the selected assistant/tool checkpoint, including its original bootstrap context. Committed assistant text can be selected whether it is an intermediate or final answer; reasoning-only summaries are not checkpoints. A tool-result checkpoint must close every pending call in its batch, including parallel calls. Selecting a partial result never advances past it to collect later answers, and an assistant item containing text plus tool calls is never split. Archived checkpoints use validated pre-compaction history, never a later summary as a substitute for missing context. Checkpoints with unsupported content, unresolved tool calls in their prefix, or unreconstructable legacy context are not eligible.

An unsubmitted checkout becomes stale when its source conversation or configuration changes, including compaction, or when the backend restarts. Abandon it and list prompts again. Committed submissions survive restart: retrying the same checkout and text finds the same child without generating a second response. Errors after a durable commit identify the child so it remains discoverable even if activation or response delivery failed.
An unsubmitted checkout becomes stale when its source conversation or configuration changes, including compaction, or when the backend restarts. Abandon it and list checkpoints again. Committed submissions survive restart: retrying the same checkout and text finds the same child without generating a second response. Errors after a durable commit identify the child so it remains discoverable even if activation or response delivery failed.

After successful submission, the source remains loaded and unchanged. Use `/sessions` to return to it. If the child is cancelled before execution starts, its committed history remains available but its connection can close to prevent the cancelled prompt from running later. Select the source, then the child in `/sessions` to reload it without rerunning that prompt. Checkout does not restore files, stop processes, reverse tool calls, or undo any other external effect.

Expand Down
Loading
Loading