Interactive TUI

0. What this is, what this isn’t

This document is the reference TUI consumer’s product surface: the things a tmux-shaped phux user sees and configures — how a user invokes the TUI, configures it, binds keys, reads its status output, and extends it. Where this document conflicts with the normative wire spec under ../spec/, the spec wins; file an issue.

0.1 The TUI is the wedge, not a second local multiplexer

The reference TUI is worth heavy product investment because it is the adoption surface that bootstraps a population of terminals-on-the-wire (ADR-0030 §6). What distinguishes it from a local multiplexer is not local splits — those are table stakes — but the wire underneath: a phux session lives on the server, so a client can attach and detach without killing it, remote over a transport, and let a human and their agents share the same live terminals (agents.md drives those terminals side-effect-free while a human watches). The local-tiling features in this doc are the familiar shape that gets a tmux user in the door; the wire is why they stay.

Investing in the TUI as a product and holding it as a pure consumer are not in tension. The constraint that keeps the wedge from corrupting the platform is ADR-0017: the TUI gets no protocol-level standing, and its needs land as L3 conventions and client logic, never as new wire surface. Other consumers — the agent CLI, the MCP adapter, the browser client, a future native GUI — are peers, each its own file under docs/consumers/.

For the long arc, read ../vision.md. For the wire protocol, see ../spec/. For internal structure, see ../architecture/. This document is everything between.

0.2 TUI vocabulary maps to the substrate

The user-facing vocabulary is tmux’s. Under the hood, each TUI concept maps to substrate concepts. Following ADR-0030, there is no L2 collection tier: a session is L3 grouping metadata plus client logic, not a wire-level lifecycle entity.

A consumer that doesn’t want this vocabulary doesn’t have to learn it; the substrate doesn’t carry it. GroupId survives only as a documented opaque grouping key, not a lifecycle tier — settled, not a remnant awaiting removal (bead phux-0bmc closed as resolved-by-rename).

2. The user model

Three nouns. Same as tmux. Don’t reinvent vocabulary that users already know.

• Session — top-level container. Named. Persists across client disconnects. Lives until explicitly killed or until the server exits.
• Window — tab within a session. Numbered from 0 within its session; optionally named.
• Pane — leaf in a window’s layout. One PTY, one terminal grid, one shell or command.

A client is an attached frontend (TUI or GUI). Clients are transient; they are not part of the session model. The protocol exposes ClientId only for the duration of a connection.

13. First-time use

A new user, fresh install, no config file:

$ phux
# spawns server, creates session "default" with one window/one pane
# running $SHELL in $PWD
# attaches the client and renders
# status bar shows "0:shell | C-a ? help | C-a : palette | C-a [ copy | default 21:14"
$ C-a c           # new window
$ C-a d           # detach
$ phux            # re-attach to "default"; full state replayed

Discoverability: the default status bar keeps the highest-value prefix affordances visible without consuming pane space. If the prefix is rebound, the help-hints widget renders the configured prefix.

Beyond that, two client-rendered discovery behaviors teach the bindings themselves (the TUI owns its chrome — nothing here is server-rendered):

• C-a ? and C-a : open the same commands & help finder described in §5.5. Type any part of an action or its live chord, move through ranked matches with the standard list controls, and press Enter to run it through the normal dispatcher. Esc dismisses it.
• Press C-a and hesitate, and the which-key popup appears after which-key-delay-ms (default 600 ms), listing the available prefix continuations. Any key dismisses it and executes normally; Esc cancels the prefix. See §5.7.