Skip to content

The TUI

The af terminal UI is the home base for running agents. It's built to keep you in one screen: a list of everything running on the left, a live look at any agent on the right, and a keystroke to dive into any of them full-screen.

Launch it from inside a git repository to open scoped to that project, or from anywhere to open on your project registry and pick one:

cd your-project   # opens scoped to this project
af

Run outside a git repository and af still opens — on the project registry, so you can select a known project or add one.

Layout

  • Sidebar. Every session, with a live status indicator (waiting on you, hit a usage limit, dead-and-being-recovered). Sessions are grouped and navigable with the arrow keys or j/k.
  • Agent tab. A snapshot of the selected agent's terminal, updated as it works — so you can follow progress across several agents without attaching to any of them. Toggle it with s (open) and x (hide).

Interacting with a session

There are two ways in, split deliberately:

  • ↵ (Enter) — interact in-pane. Type to the selected agent directly inside the layout, without a full-screen takeover. Ctrl-] returns you to navigation mode.
  • o — attach full-screen. Hand the whole terminal to the session's tmux. The tmux detach key returns you to the sidebar. The agent keeps running either way.

Tabs

A session isn't limited to its agent. Each one can hold as many tabs as you make, all running in the same worktree (there used to be a nine-tab cap matching the 1-9 jump keys; it was removed in #3023):

  • t opens a new-tab picker. Choose Terminal for a shell in the worktree, or VS Code for a browser editor on that worktree (the TUI shows its placeholder; open the web client to use the editor).
  • w closes the focused tab (the agent's own tab can't be closed — kill the session instead).
  • 1–9 jump straight to a tab by number.

Tabs persist across restarts, and each is a real process the daemon tracks. (Remote sessions are more limited — see Remote hooks.)

For a named long-running command or a web preview with a URL/port, use af sessions tab-create; those kinds need input beyond this two-item picker.

Working with results

  • p opens the session's pull request; y copies its URL.
  • e runs the repo's worktree hooks.
  • / searches; ? shows the full, live help overlay.

Sessions, tasks, and other surfaces

  • n creates a new local session; N creates a remote one.
  • a archives the selected session as the default done action (or restores an archived, Lost, or Dead one). D permanently kills it, including any uncommitted or unmerged work.
  • m opens the tasks view to manage scheduled and event-driven automations.
  • c retries a session that's parked on a usage limit.
  • s opens the selected tab as a workspace pane; S commits an active preview as another pane.
  • Left / Right move focus between open workspace panes when a pane has focus.
  • Ctrl-u / Ctrl-d preview-scroll the current tab. In a full-screen attach the child program owns input and scrolling; these only work in AF's navigation mode.
  • Ctrl-p switches the active project without restarting the TUI. It works from navigation only — while you're attached to a pane, Ctrl-p is forwarded to the running program, so detach (Ctrl-]) first.

Key bindings are yours

Every binding above is the default. You can rebind almost all of them in the [keys] table of your config — a handful of structural keys (Enter, Tab, Ctrl-], the 1–9 tab jumps) are reserved. Run:

af keys

to print every action with its effective binding (default or your rebind). See Configuration → key bindings for how to set them, including how to restore pre-#1027 keys, and the CLI reference for the command.