Ways to use phux
Choose the interface that fits the job: the reference TUI for a person, the CLI, OpenCode, Pi, or MCP adapter for an agent, the browser client for the web,...
Full source summary
Choose the interface that fits the job: the reference TUI for a person, the CLI, OpenCode, Pi, or MCP adapter for an agent, the browser client for the web, or the in-tree Rust client functions when working inside this workspace. They are peer consumers of one wire and one terminal model.
Every interface is a peer over the same terminals. Choose by operator, not by protocol privilege.
Choose an interface
| You want to | Start with |
|---|---|
| Work interactively with persistent sessions and splits | The reference TUI |
| Read and drive terminals from a script or coding agent | Agents and the CLI |
| Give OpenCode terminal tools, lifecycle metadata, and fleet awareness | The OpenCode integration |
| Give Pi target persistence, lifecycle metadata, and fleet awareness | The Pi integration |
| Connect a tool client over MCP | The MCP adapter |
| Run the terminal client in a browser | The web client |
| Study the in-tree Rust free-function API | The internal client library |
The peer principle
No consumer is protocol-privileged. The TUI, web client, and agent surface are peers over one wire. Rendering clients project structured views from a local engine; the CLI and MCP adapter also consume server-derived convenience snapshots. In neither case is structured screen state the canonical wire tier. See ADR-0017 (the TUI gets no protocol-level standing) and ADR-0030 (structured views are projections rather than a second synchronization model).
If a consumer needs behavior the wire does not provide, the answer is to extend the spec with an ADR, not to add a consumer-shaped hook. The reference pattern for a consumer that wants structure is to carry its own engine and project locally, the way the web client does.
Files
| File | Owns |
|---|---|
| tui.md | Reference TUI, the adoption wedge: CLI, keybinds, status bar, layout, hooks, recording. |
| web.md | Reference projection consumer: Rust-to-WASM browser client that carries its own engine over the WebSocket wire codec. |
| ios.md | Native projection consumer: the Swift/UniFFI iOS client, its wss:// + pinned-certificate transport, and the normative phux pair connect-link contract. |
| agents.md | Agent surface: the CLI verb set, public agent state, asks, workspace save/restore, and versioned JSON contracts. (See ../../AGENTS.md for universal agent substrate instructions.) |
| opencode.md | OpenCode package: loading, six tools, cache-preserving fleet context, target precedence, lifecycle metadata, shared adapter boundary, and safety. |
| pi.md | Pi package: local installation, nineteen terminal tools, cache-preserving fleet context, target persistence, lifecycle metadata, human handoff, and safety. |
| mcp.md | MCP adapter: a JSON-RPC stdio tool surface over the agent verbs, phux_ask, and plugin workspace profile discovery. |
| sdk.md | The workspace-internal phux-client free-function surface over the phux-protocol wire codec. |
| recording.md | Session recording: the two capture surfaces, asciicast and the self-contained GIF/APNG renderer, tuning, and the limits. |
Future consumers — a desktop GUI, a tmux-CC adapter — get their
own files here when they materialize. Each file’s frontmatter declares its
own stability; a shipped surface is stable, a forward-looking sketch is
evolving. Today the consumer surfaces are real but still pre-1.0, so most
files remain marked evolving.
Vision
The long arc beyond the current substrate cut: agents as a primary consumer category, federation as the default deployment shape, and lazy state...
Interactive TUI
Use phux interactively: understand the terminal model, navigate the first session, then open focused guides for commands and customization.