---
title: "Build on phux"
url: "https://docs.phux.sh/building"
source: "https://github.com/no-phux/phux/blob/06139f37fe877c59ea6c10a70f8a79b4b21dc352/docs/building.md"
projectVersion: "0.119.0"
protocolVersion: "1.0.0"
stability: "stable"
---

# Build on phux

One page for a program that drives a phux server, or reports status into a pane. Each entry links the page that specifies it; any promise here is quoted from there.

## Entry points

- [Versioned `--json`](/scripting#json-output-and-errors). Pass `--json`
  on a command whose `--help` lists it. The generated text is the
  [CLI reference](/reference/cli).
- [MCP](/agents#mcp). `phux mcp` serves tools over stdio. The
  [parity table](/reference/parity) is generated from the tool catalog.
- [`phux watch`](/scripting#watching-events). `--json` prints one JSON
  object per line. `--after` resumes from the cursor the previous run
  printed last on stderr.
- [Server protocol](/protocol). Length-prefixed binary frames.
  [Compatibility](/compatibility) is the 1.x rule.
  [`wire-schema.json`](https://github.com/no-phux/phux/blob/06139f37fe877c59ea6c10a70f8a79b4b21dc352/docs/spec/wire-schema.json) is generated from the codec.
- [OSC 7501: report status from any program](/program-protocol).
  [Any program can report status](/any-program-status) is a short
  emitter. A program writes one escape sequence. It needs no phux library
  and no socket.
- [Plugin API](/plugins). A directory with a `phux-plugin.toml` manifest.
- [Agent integrations](/agents#agent-setup). The table there includes
  Claude Code, pi, Oh My Pi, OpenCode, Grok, and any MCP client.
- [Calling phux from a program](/agent-quickstart#call-phux-from-a-program)
  and [Embed phux](/embedding). Read these for what a library would be,
  and for the SDK status below.

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

## Agent state

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

[Coding agents](/agents#agent-states) 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](/program-sequences#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](https://github.com/no-phux/phux/blob/06139f37fe877c59ea6c10a70f8a79b4b21dc352/scripts/agent-verify/README.md). 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](/agent-quickstart#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](/embedding) says none of the embed crates is on crates.io
yet. [Releasing](/releasing#npm-and-cratesio) 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`](https://github.com/no-phux/phux/blob/06139f37fe877c59ea6c10a70f8a79b4b21dc352/integrations/runtime/package.json)).

There is no JSON socket. A client speaks the binary frames in
[Transports](/protocol#transports), or it spawns the `phux` process and
reads `--json` on that process's stdout. The [CLI reference](/reference/cli)
has no `phux api` command.

There is no example application. [examples/agents](https://github.com/no-phux/phux/blob/06139f37fe877c59ea6c10a70f8a79b4b21dc352/examples/agents/README.md)
is scripts that spawn the `phux` binary. [First-party plugins](/plugins#first-party-plugins)
are manifests. The embed example in [Embed phux](/embedding) 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](/plugins#listing-a-plugin)). `phux plugin install`
takes GitHub `owner/repo[/subdir]`, a git URL, a local directory, or a
tarball ([Managing plugins](/plugins#managing-plugins)).

## Version rules

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

[Compatibility](/compatibility):

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

[Making a change compatible](/compatibility#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](/scripting#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](/reference/exit-codes).

`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`](/reference/cli#phux-watch)).

[Versioning](/releasing#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](/scripting#watching-events)
shows a pane (`@7`). The generated help says omitting the target watches
the most-recently-focused session ([`phux watch`](/reference/cli#phux-watch)).
Neither page documents a fleet-wide subscription.

## llms.txt

The builder index checked into this repository is [llms.txt](https://github.com/no-phux/phux/blob/06139f37fe877c59ea6c10a70f8a79b4b21dc352/docs/llms.txt).
[https://docs.phux.sh/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](https://docs.phux.sh/llms-full.txt) is
every hosted page.