phux

the tmux job, done - a terminal is an object on a wire

Install | Keys | Config | Headless | Agent Workbench | Troubleshooting | Status | Docs

Recorded and rendered by the binary it demonstrates -- phux rec, no asciinema, no ffmpeg. (Recording)

phux is a terminal multiplexer, like tmux or screen: your shells live in a background server, you split them into panes, you detach, and everything is still running when you come back.

The twist is what a "terminal" is. In phux, each pane is a real terminal emulator living inside the server, and anything can attach to it -- the bundled TUI, a shell script, an AI agent. They all hold the same live terminal at the same time, with the same authority. No screen-scraping, no "agent mode": to a program, a phux terminal is just an object it can type into, read from, and wait on.

Quick start

brew install phall1/tap/phux
phux

You're in a shell. Ctrl-A d detaches, phux brings you back, Ctrl-A ? shows every key. Prebuilt binaries cover macOS arm64, Linux x86_64, and Linux arm64; Windows is not supported. Other channels and source builds: INSTALL.

The same terminals work without a TTY, from scripts, CI, or an agent:

phux send-keys . 'cargo test' Enter   # type into the focused pane
phux wait --until "0 failed" .        # block until output appears
phux snapshot .                       # read the screen
phux agent explain .                  # what is the agent in this pane doing?

There's an MCP server too (phux-mcp), so agent hosts get the same verbs as tools. Start at Agents.

How it works

      your programs: zsh, vim, htop, an agent's shell
                          │
                          │  PTY
                          ▼
 ┌─────────────────────────────────────────────────┐
 │ phux server -- keeps running when you leave     │
 │                                                 │
 │ libghostty terminal: the real one. Screen,      │
 │ scrollback, and modes live here, so they        │
 │ survive detach and feed headless reads.         │
 └───────────────┬──────────────────▲──────────────┘
                 │                  │
     output goes │                  │ input comes back
     down as raw │                  │ up as structured
     VT bytes,   │                  │ key, mouse, and
     verbatim    ▼                  │ paste events
 ┌──────────────────────────────────┴──────────────┐
 │ phux client -- attach, detach, reattach;        │
 │ several clients can share one terminal          │
 │                                                 │
 │ libghostty terminal: the same engine, fed       │
 │ the same bytes, drawing them on your screen     │
 └─────────────────────────────────────────────────┘

tmux-style multiplexers sit in the middle of the byte stream: they parse your program's output into their own screen model, then re-encode it for whatever terminal you attached from. Anything the middleman doesn't understand -- an inline image, a new underline style, next year's protocol -- gets mangled or dropped in translation.

phux doesn't translate. The same emulator (libghostty, the engine from Ghostty) runs on both ends with two different jobs. The server's copy is the source of truth: it's what survives detach and what scripts read. The client's copy just renders, fed the exact bytes your program wrote. Down the wire go raw VT bytes; back up go structured key, mouse, and paste events. Nobody in the middle rewrites anything, so this works:

Truecolor, curly underlines, and an inline image surviving detach and reattach -- then the same session driven headlessly.

Troubleshooting

When something misbehaves, three commands answer most questions:

phux status   # is the server up: pid, uptime, protocol, clients, sessions, logs
phux doctor   # checks config, socket, server, plugins, and log paths
phux logs     # names every log file phux writes; tails any of them

phux status reports the server behind the socket in one glance -- and with no server running says so, naming the command that starts one. phux doctor runs the checks a debugging session would otherwise discover one by one and prints one verdict per line. phux logs knows where every log lives, so you never have to.

Status

The TUI multiplexer and modern-protocol passthrough are stable enough to try. The headless verbs, the MCP server, workspace save/restore, and satellite federation are real and tested, still pre-1.0. A native GUI is designed but not wired. Anything else you've heard is a direction, not a feature.

phux also deliberately has no scripting language, no in-process plugin host, and no homegrown crypto. The reasoning is in CONTRIBUTING.

Learn more

Decide if phux fits	When to use phux
The mental model	Concepts
Keys and config	Configuration
Drive it from an agent	Agents · MCP
Record and replay sessions	Recording
Reach it over the network	Remote access
The wire protocol	Spec · Architecture
Where it's going	Vision · ADRs
Build it with us	Contributing

License

Dual-licensed under MIT or Apache-2.0.