When to use phux (and when not to)

evolving Get started

When to use phux (and when not to)

TL;DR. phux is a terminal multiplexer whose differentiator is the wire, not the splits: a terminal is an object other programs can attach to, inspect, and drive. The headline case is a human and their agents sharing the same live terminal with CLI/MCP control, public agent state, and external integration packages. If you want that, phux is for you today. If you want a battle-hardened local multiplexer with a decade of muscle memory, you mostly do not need it yet. Find your row below.

Find yourself

You arephux?Why
A human who wants their agent to see and drive the same terminal they doYes — this is the pointOne server, many consumers; the agent attaches to your live pane, reads its grid, and types into it.
An agent author who wants structured, scriptable terminal controlYesls/snapshot/send-keys/run/wait/watch/ask/agent with --json, plus phux-mcp. The CLI + JSON schema is the contract.
A team composing terminal-native coding agentsYesPublic Codex/Claude integration fixtures, plugin workspace profiles, and MCP tools give you a phux-shaped agent bench without an in-process plugin host.
A tmux user who wants a modern, protocol-honest multiplexerYes, with eyes openAttach/detach, splits, status bar, keybindings, visible help hints, and copy/navigation affordances work. Expect pre-1.0 edges.
Someone on one SSH session who just wants splits and persistenceProbably not yettmux already does this well and phux adds no wire advantage for a single local user. Revisit when you want remoting or agents.
A fleet operator who wants to drive terminals across machinesYes, with a hub-and-spoke limitA configured hub aggregates and routes satellite Terminals addressed as host/@N; it does not merge remote session/window models or chain satellite routes.

The honest gaps

phux is pre-1.0. The wire, the reference TUI’s attach/detach/multi-pane, and modern-protocol passthrough are real and tested, but remain pre-1.0. The headless verbs, phux agent, phux-mcp, plugin actions, workspace save/restore, and hub-to-satellite Terminal routing are real and tested, but JSON/API details may still wiggle before 1.0. Federated session/window joins, a native GUI consumer, and a typed public SDK crate remain intentionally absent. Predictive local echo is implemented behind the opt-in [experimental] config and remains off by default. If a capability is not in the README status list, treat it as a promise, not a feature.

Go deeper