Entry points

Versioned --json. Pass --json on a command whose --help lists it. The generated text is the CLI reference.
MCP. phux mcp serves tools over stdio. The parity table is generated from the tool catalog.
phux watch. --json prints one JSON object per line. --after resumes from the cursor the previous run printed last on stderr.
Server protocol. Length-prefixed binary frames. Compatibility is the 1.x rule. wire-schema.json is generated from the codec.
OSC 7501: report status from any program. Any program can report status is a short emitter. A program writes one escape sequence. It needs no phux library and no socket.
Plugin API. A directory with a phux-plugin.toml manifest.
Agent integrations. The table there includes Claude Code, pi, Oh My Pi, OpenCode, Grok, and any MCP client.
Calling phux from a program and Embed phux. Read these for what a library would be, and for the SDK status below.

phux watch --json --after "$cursor" @7
phux mcp --schema

Agent state

Agent state is evidence-ranked; screen is the floor.

Coding agents names the order the server keeps: what the agent declares through its integration or phux agent set, the events its integration reports, an OSC 7501 report, hooks, the program in the foreground, and finally the screen matched against built-in rules. Screen rules ship for Claude Code, Codex, OpenCode, pi, Oh My Pi, Grok, Amp, Cursor, Gemini CLI, Goose, and Aider. A screen that matches no rule reads as idle, never blocked. phux agent explain prints the evidence for one pane.

Precedence writes that order as a numbered list, and says that while a pane has an OSC 7501 record and no live session, phux ignores hooks, the foreground program, and the screen.

It has not been measured on a live Claude Code, Codex, OpenCode, or pi session, with or without an integration installed. The command that records that measurement is scripts/agent-verify. A manual run of that command makes billable model calls on the operator’s own agent logins. CI runs that harness against a stub only. A table of real Mac numbers is not checked in.

Not shipped

There is no public SDK. Call phux from a program says this repository ships no Python or JavaScript package for driving phux. phux-client-core and phux-client-runtime set publish = false. Embedding says none of the embed crates is on crates.io yet. Releasing says phux-protocol is the crate published to crates.io, and every other crate is publish = false. The npm packages in that table (@phux/pi, @phux/opencode, @phux/omp) are agent integrations. @phux/integration-runtime is "private": true (integrations/runtime/package.json).

There is no JSON socket. A client speaks the binary frames in Transports, or it spawns the phux process and reads --json on that process’s stdout. The CLI reference has no phux api command.

There is no example application. examples/agents is scripts that spawn the phux binary. First-party plugins are manifests. The embed example in Embed phux draws a terminal.

Plugin index

The static plugin index is built from the GitHub topic phux-plugin and from the plugins in this repository (Listing a plugin). phux plugin install takes GitHub owner/repo[/subdir], a git URL, a local directory, or a tarball (Managing plugins).

Version rules

The wire protocol and --json output each have a written compatibility rule. The product version follows its own.

Compatibility:

The wire protocol is 1.0. Any 1.x client works with any 1.x server, older or newer.

Making a change compatible:

Do not bump the major for an additive change; a shipped bit is never withdrawn or repointed.

JSON output and errors:

--json output is versioned. Each document has a schema_version that changes only when a key is removed, renamed, or retyped. New keys appear without a bump, so ignore keys you don’t know.

On failure, stdout is empty and stderr is one JSON object. Branch on error.code. phux --capabilities --json prints the code list. Exit codes are the exit-code reference.

phux watch --json is outside that per-document rule. Its generated help says each line is one JSON object and that there is no per-line schema_version (phux watch).

Versioning covers the product version:

Pre-1.0: fix: bumps the patch, feat: bumps the minor, and a breaking change also bumps the minor.

There is no SDK compatibility promise, because there is no public SDK.

Watch scope

phux watch takes one target. Watching events shows a pane (@7). The generated help says omitting the target watches the most-recently-focused session (phux watch). Neither page documents a fleet-wide subscription.

llms.txt

The builder index checked into this repository is llms.txt. https://docs.phux.sh/llms.txt is a different file, kept in no-phux/website at public/llms.txt. Nothing in this repository generates that hosted file. https://docs.phux.sh/llms-full.txt is every hosted page.