Quickstart

1. Install phux

On a Homebrew-supported macOS or Linux machine:

brew install phall1/tap/phux

This installs both phux and the bundled phux-mcp adapter. The INSTALL.md guide covers the verified curl installer, release tarballs, supported platforms, and source builds.

Check that the binary is available:

phux --version

2. Start a terminal

phux

With no arguments, phux starts a per-user server if needed, creates a shell-backed session, and attaches the interactive client. Work in it like a normal terminal.

The default prefix is Ctrl-A. Four continuations are enough for a first run:

After detaching, run phux again. You return to the same live session.

3. See it from the outside

Leave the interactive session running and open a second terminal. The control commands below address the focused pane with .:

phux ls
phux snapshot .

ls shows the sessions the server owns. snapshot reads the current terminal without attaching to it or changing its size.

Now type into the same pane and wait for output that is not present in the command itself:

phux send-keys . "printf '%s\n' phux-ready | tr a-z A-Z" Enter
phux wait --until "PHUX-READY" --timeout 10 .
phux snapshot --json --scrollback 50 .

That is the core automation loop:

read state -> act -> wait for a condition -> read again

A script, coding agent, or MCP client uses this loop against the same terminal a person can see and take over. Add --json to read commands when the caller needs a versioned machine-readable result. Use phux run when you want phux to execute a one-shot command and return its output and exit code directly.

4. Connect an agent

The release includes two agent-facing surfaces:

• The phux CLI for direct shell calls and scripts.
• phux mcp, which launches the bundled JSON-RPC stdio adapter for MCP clients.

Start with the CLI guide for selectors, safe input, events, and result shapes: consumers/agents.md. Use consumers/mcp.md when the client speaks MCP.

Useful first commands:

phux --skill=quick
phux --capabilities --json
phux mcp --skill
phux mcp --schema
phux ls --json
phux snapshot --json .
phux watch --json .
phux agent explain .

watch streams terminal events until interrupted. agent explain reports the public state phux can infer for a coding agent in the pane, including its confidence and evidence. The two --skill endpoints are compiled into their respective installed binaries; --schema is the same MCP catalog returned by live tools/list.

Know the edges

phux is pre-alpha. Local persistent sessions, attach and detach, splits, multiple clients, modern terminal passthrough, the headless CLI, and the MCP adapter work today. Interfaces can still change before 1.0.

Hub-and-spoke federation now routes Terminal-scoped operations to configured satellites; aggregate inventory exposes direct host/@N selectors, without federated session/window joins. Predictive local echo is implemented as an opt-in [experimental] setting and remains off by default. The exact line between shipped behavior and design intent lives in CONCEPTS.md; suitability by workflow lives in when-to-use.md.

When something misbehaves

Three commands are the starting point for any debugging session:

phux status
phux doctor
phux logs

phux status answers the first question — is the server running — in one glance: its pid, how long it has been up, the protocol version it speaks, attached clients, one line per session, and where its logs live. With no server running it says so and names the commands that start one. phux doctor checks the install end to end — config validity, socket path, server reachability, plugin manifests, and where the logs live — and prints one verdict per line, with a hint for anything that is not a pass. phux logs names every log file phux writes (the canonical server log and the per-client logs), says whether each exists yet, and tails them: phux logs --server -f follows the server log, phux logs --client shows the newest client log.

Next steps