alforria

Terminal UI

Work in the alforria TUI: sessions, dialogs, diffs, keys, and themes.

Run alforria in a repository to open the terminal UI. It is keyboard-first, renders with ratatui, and keeps every session in the same local store as the CLI and server.

Launch options

alforria                         # full TUI in the current directory
alforria -c                      # continue the latest session
alforria -s <session-id>         # continue a specific session
alforria -s <session-id> --fork  # fork before the next turn
alforria -m provider/model       # start with a specific model
alforria --agent <name>          # start with a specific agent
alforria --auto                  # auto-approve permissions (dangerous)

alforria <path> starts in another directory. Attach to a running server with alforria attach <url>; the TUI then drives the remote session engine.

--mini is not available yet. It prints a warning and starts the full TUI.

Default keys

The leader key is ctrl+x. Press it before a leader binding, for example ctrl+x then n for a new session.

Key Action
ctrl+p Open the command palette
ctrl+x n New session
ctrl+x l List sessions
ctrl+x m List models
ctrl+x a List agents
ctrl+x e Open the prompt in an external editor
ctrl+x c Compact the current session
ctrl+x y Copy the selected message
ctrl+x u Undo the last message
ctrl+x q Quit
ctrl+c, ctrl+d Quit
return Submit the prompt
shift+return, ctrl+j Insert a newline
escape Interrupt the current turn. Press it twice within 5 seconds
pageup, pagedown Scroll the transcript by a page
ctrl+alt+u, ctrl+alt+d Scroll by half a page
ctrl+v Paste from the clipboard

Bindings can be remapped in tui.json. See Configuration.

Sessions and turns

The command palette (ctrl+p) is the main menu. It exposes session creation, model and agent selection, compaction, provider connection, themes, and help.

  • A session belongs to the project directory where it was created.
  • Subagent sessions are shown as children of the parent session.
  • ctrl+x then l searches sessions through the server, not only the locally synced window.
  • ctrl+x then c compacts the conversation when it grows too long.
  • Forking copies a session so you can explore a different direction without losing the original.

Permissions and questions

When a tool call matches an ask rule, alforria pauses and opens a permission dialog. You can allow it once, allow it always, or reject it.

  • Allow always adds an allow rule in memory. It applies to every session in that project directory and is gone after alforria restarts. Nothing is written to your config. For bash, the rule is the command prefix plus *, for example cargo test *. Other pending requests in the same session that the new rule covers are approved too.
  • Reject also rejects every other pending request in that session.

Question dialogs support both multiple-choice and free-text answers.

Dialogs own the keyboard while they are open. The prompt palette can still be opened over a permission dialog. Repeated identical tool calls can trigger the doom_loop permission gate; continuing from that gate is an explicit choice.

Diffs and review

Edits show their diffs inline in the transcript and in permission dialogs. The TUI has no separate diff viewer. For a full session diff, use the Changes tab in the web client.

ctrl+x then u undoes your last message: it reverts the session to before that message and puts the prompt back in the input. ctrl+x then r redoes.

Git-backed snapshots make revert possible. Revert is available when the project is a Git repository and snapshots are not disabled. It operates on the files listed in the snapshot, so review the diff before reverting.

Copy, mouse, and SSH

  • Drag to select text in the transcript. Copy happens on release.
  • ctrl+x then y copies the selected message.
  • Copy uses the terminal clipboard and OSC 52, so it also works over SSH when your terminal supports OSC 52.
  • ctrl+v pastes from the terminal clipboard.

Themes

Use the command palette to list and switch themes. alforria ships bundled themes and can generate a system theme from the terminal's real palette.

Custom themes are JSON files in a themes/ directory:

  • ~/.config/opencode/themes/<name>.json for all projects;
  • .opencode/themes/<name>.json in a project or one of its parent directories.

A custom theme overrides a bundled theme with the same name. See the configuration page for the separate tui.json settings file.

Logs

The TUI does not print logs to the terminal. Warnings, such as a tui.json that was skipped, are written to log/tui.log in the data directory (~/.local/share/opencode/log/tui.log by default). --print-logs has no effect on the TUI; it only applies to alforria serve.