Ways to use phux
Pick the interface that matches the job: the TUI or Cockpit for a person, the CLI and MCP for a script or agent, OpenCode, Pi, or Claude when those hosts...
Full source summary
Pick the interface that matches the job: the TUI or Cockpit for a person, the CLI and MCP for a script or agent, OpenCode, Pi, or Claude when those hosts already run the work, the browser or iOS client when the glass is not a tty, and recording when you want a cast. They are peers of one server 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 in a terminal | The reference TUI |
| Read and drive terminals from a script or coding agent | Agents and the CLI |
| Connect a tool client over MCP | The MCP adapter |
| Give OpenCode terminal tools and fleet awareness | The OpenCode integration |
| Give Pi target persistence and fleet awareness | The Pi integration |
| Run Claude Code against the same terminals | The Claude Code plugin |
| Run the terminal client in a browser | The web client |
| Use the native macOS app | Cockpit |
| Record a pane or an attached session | Recording |
Pair a phone over wss:// (contract) | The iOS client |
Every interface here is a peer of the others; the TUI has no protocol-level standing (ADR-0017).
Gaps: ../CONCEPTS.md.
Files
| File | Owns |
|---|---|
| tui.md | Reference TUI: prefix keys, layout, chrome, copy-mode, fleet overlay. |
| cockpit.md | Native macOS client over phux-client-ffi. |
| web.md | Browser client that carries its own engine over the WebSocket wire codec. |
| ios.md | Swift/UniFFI iOS client and the phux pair connect-link contract. |
| agents.md | Agent surface: CLI verbs, JSON contracts, asks, workspace save/restore. |
| opencode.md | OpenCode package: tools, fleet context, target precedence, safety. |
| pi.md | Pi package: tools, fleet context, target persistence, safety. |
| claude.md | Claude Code plugin: MCP tools plus lifecycle identity. |
| mcp.md | MCP adapter over the agent verbs. |
| sdk.md | Workspace-internal phux-client free-function surface. |
| recording.md | Session recording: observer capture, interactive tee, playback as a pane. |
Each file’s frontmatter declares its own stability. A shipped surface is
stable; a surface still settling is evolving.
Vision
The long arc: lazy state synchronization as the wire's destination, a durable work coordinator that does not ship today, and federation as the default...
The phux reference TUI
The reference TUI is the human attach client: split panes, switch windows, detach, and return to the same live terminals.