phux — phux documentation

Start with the quickstart if you want a persistent terminal you and an agent can share.

Start here

You do not need to understand the protocol before using phux.

Your goal	Best first page
Run a persistent terminal and reattach to it	Quickstart
Let an agent inspect and drive that same terminal	Agent CLI guide
Connect OpenCode to shared phux terminals	OpenCode integration
Connect Pi to shared phux terminals	Pi integration
Install through Homebrew, a release, or source	Install guide
Set up to contribute to one part of the repo	Contributor setup: native or Nix
Decide whether phux fits your workflow today	When to use phux
Change the prefix, keys, status bar, or hooks	Configuration
Record a pane or a session as a cast, GIF, or APNG	Recording
Reach your server from another network	Remote access

The shortest path is the quickstart. It gets a real session running first, then shows the read, act, wait, read loop that makes the same terminal useful to an agent.

Two speeds

Use phux

These pages are for people trying to get work done:

Quickstart gets the first shared terminal running.
Install covers every supported installation path.
Configuration owns keybindings, status, and hooks.
Remote access reaches a server across networks over an overlay.
The reference TUI is the interactive terminal guide.
Recording captures a pane or a whole session as a cast, GIF, or APNG.
Agents and the CLI is the headless CLI and JSON guide.
The OpenCode integration adds OpenCode tools, target selection, and lifecycle metadata.
The Pi integration adds Pi tools, target selection, and lifecycle metadata.
The MCP adapter connects the same controls to MCP clients.

Understand or extend phux

These are reference material. Read them when you are building against phux, operating it, or checking why the system has a particular shape:

How phux works explains the terminal, wire, and peer-consumer model.
Protocol reference is the normative, versioned wire protocol.
Consumer interfaces documents each interface built on the wire.
Architecture explains the process, transport, rendering, and state-sync internals.
Operations owns errors, logging, telemetry, and security boundaries.
Decision records explain why consequential decisions were made.

The distinction is deliberate. A user should be able to install and operate phux without reading an ADR. A protocol implementer should be able to find the normative answer without pulling behavior from a tutorial.

What phux is

phux treats a terminal as an addressable object that can outlive any one view. A person in the reference TUI, an agent using the CLI, and a browser client can observe or drive the same terminal through peer interfaces. The terminal stream stays a terminal stream; structured views are projected by consumers.

phux is pre-alpha. The local TUI, persistent sessions, multi-client attach, headless commands, and MCP adapter are real. Interfaces may still move, and some of the longer-range protocol design is intentionally documented before it ships. CONCEPTS.md owns the exact maturity boundary.

The site

The marketing + docs site lives at site/ — the Astro app imported from phall1/phux-site. Its docs pages are generated from this very tree at build time by site/scripts/sync-docs.ts (glob-driven; a new spec page, consumer doc, or ADR flows through with zero script edits). Deploy pipeline: .github/workflows/site-deploy.yml builds and publishes on every push that touches docs/** or ADR/**, serving https://phux.sh. Site-specific conventions live in site/FUMADOCS.md; the doc-system contract above deliberately does not apply to site content.

Working on the project

Contributors should read ../CONTRIBUTING.md. Documentation structure and review rules live in CONVENTIONS.md; release procedure lives in RELEASING.md. Code-level API docs are generated from Rust source with cargo doc --workspace --all-features.

phux documentation