The server, CLI and terminal UI are the core product. Remote hosts, agent integrations, MCP, plugins and distributions are optional maintained features; you do not need them to use local terminals. The separately released desktop is a newer maintained client. The browser client is an unshipped experiment, and phone apps are not available yet. See Clients for platform requirements and limitations.

Get started

Install: the install script, Homebrew, the desktop app, updating, and removing phux.
Getting started: install, a first agent, the keys that matter, detaching, and coming from tmux.
Concepts: the server, sessions, tabs, panes, clients, hosts, targets, and what survives a restart.
phux vs tmux, Herdr, and cmux: which one fits the job.

Customize

Configuration file: where the file lives, how it layers over the defaults, and when a change takes effect.
Key bindings: change the prefix, rebind or unbind keys, and see what’s in effect.
Themes: install, pick, and write colour themes.
Status bar and sidebar: what the bar and the sidebar show, and how to change it.
Hooks: run a command when something happens.
Plugins: add actions, panes, and sidebar sections.
Maintained plugin packages: the shipped plugins and where they are installed.
Distributions: switch curated defaults without replacing your config; run the Crew agent distro.
Omarchy: one command to fit phux into an Omarchy desktop, with its keys, theme, and launcher.
Projects: open a project’s session from a recipe in its repository.

Automate

Public terminal workflow: create, place and start a terminal with durable identity, receipts and connected-server schemas.
Using phux as an agent: install phux and drive sessions, panes, input, and scrollback from code.
Driving terminals from scripts: snapshot, send keys, run, wait, with JSON output and exit codes.
Runnable examples: small programs for learning the CLI and integrations.
Coding agents: see which agent needs you, connect your agent’s host, and use the MCP server.
ACP sessions: run an agent through the Agent Client Protocol, and answer its permission requests yourself.

Build on phux

Build on phux: the versioned --json CLI, the MCP server, phux watch, the 1.x server protocol, OSC 7501, the plugin API, and the surfaces this repository does not ship.

Build for phux

OSC 7501: report status from any program: the Program Status Protocol sequence phux reads, and what a pane shows from it.
Any program can report status: a short OSC 7501 emitter, a demo with no hooks, and how phux ranks that report.
Program sequences and agent reports: titles, phux-ask questions, OSC 133, OSC 52, and the other sequences phux reads, plus the agent record.

Machines and clients

Remote machines: reach another machine’s server with phux host add, and link machines together.
Clients: the terminal UI, the desktop app, the browser client, and phones.
Desktop Quick Capture: start an agent from a thought without leaving what you’re doing.
Desktop Changes panel: review, stage, and commit the focused checkout.
Desktop Reviews: review, comment on, and merge your open GitHub pull requests.
Desktop agent panes: how the desktop app shows agent panes.

Help

Troubleshooting: what to run first, and the failures people hit.
Supported platforms and desktop installation: choose the right download.
Desktop first launch and recovery: bundled runtime, retry, and startup failures.
Report a bug: gather diagnostics and remove private information before sharing.
Discord: questions and setup help.
GitHub issues: reproducible bugs and feature proposals.

Reference

Generated from the phux binary, so they match the code these docs describe.

All reference pages: what each generated page covers.
CLI: the --help text of every command.
Configuration settings: every key in the config file, with its default.
Default key bindings: every key phux binds out of the box.
Actions: everything a key binding can run.
Status bar widgets: the pieces the status bar is built from, and their options.
Hook events: every event a hook can run on.
Environment variables: what phux reads and sets.
Exit codes: what each exit status means, for scripts.
File locations: the socket, config, state, and logs.
Resource kinds, MCP tools and the commands they mirror, and deprecations.

Work on phux

Architecture: the process model, crates, and clients.
libghostty in phux: the libghostty-vt terminal engine in the server and in a rendering client, and what it does not do.
Decisions: the constraints the code keeps, and why.
Organization: how the server owns sessions and their contents.
Substrate: how people, hosts, and agents fit together.
Resource kinds beyond terminals: the design for accessibility-tree, pixel and browser resources, and the order it lands in.
Server protocol: framing, handshake, capabilities, and changing the wire.
File transfer and checkout: the commands that move files and inspect a checkout.
Host services: HTTP to a host service (OpenCode) over the phux connection.
Compatibility: what an older or newer peer sees.
Embed phux: put a phux terminal in your own app with phux-gpui, phux-client-runtime, or phux-client-ffi.
Development: set up, build, and run the checks.
Releasing: what ships, and how.

These docs track main. phux --help describes the version you have installed.