# phux

phux is a programmable terminal runtime. A background server owns terminals;
clients and automation control them through a public protocol, locally or
across machines.

Start with the task guide below, not the complete architecture or decision archive.
Every documentation page has a direct .md URL, for example
https://docs.phux.sh/agents.md. You can also request any
page with `Accept: text/markdown`. Browsers get HTML by default.
[Every page in one file](https://docs.phux.sh/llms-full.txt): the whole
documentation as Markdown, in sidebar order, each page headed by its URL.

To find a topic, search the docs at
https://docs.phux.sh/search.json?q=your+query, which answers with the ten
best-matching sections as JSON, best first, each with its `url` (deep-linked
to the section's #anchor), the `markdown` of its page, its `page` and
`heading`, and a `text` snippet. Without `q` it answers with every section.
`q` is capped at 200 characters; CORS GET is allowed.

## Operating safely

Skills teach operation; they do not register tools or grant access to a server.
Use native phux_* tools with using-phux-tools when available, the local terminal
MCP adapter with using-phux-mcp, or the CLI with using-phux. Prefer a normal shell
tool for independent commands; use phux for persistent terminal state and
interactive programs. Check the installed version; phux --skill prints the
version-matched guide.

Discover exact pane selectors, read before writing, use finite observation
deadlines, and verify results. Do not type into the agent's own pane. A timeout
stops observation, not the process or already-sent input: inspect before retrying.
Ask before interrupting or destroying existing work.

## Install

```sh
curl -fsSL https://phux.sh/install | sh         # phux CLI
curl -fsSL https://phux.sh/install-desktop | sh # macOS desktop app (+ CLI)
npx skills add no-phux/skills                    # agent skills
```

## Hosted services

- [Docs MCP server](https://phux.sh/mcp): streamable-HTTP, read-only. Tools:
  `search_docs`, `get_page` (any page as markdown), `get_install_command`,
  `latest_release`. It cannot see or control local terminals. Connect it with
  `claude mcp add --transport http phux-docs https://phux.sh/mcp` or
  `codex mcp add phux-docs --url https://phux.sh/mcp`.
  [Server card](https://phux.sh/.well-known/mcp/server-card.json).
- [Agent skills](https://phux.sh/.well-known/agent-skills/index.json):
  `using-phux`, `using-phux-mcp`, `using-phux-tools`.
- Live browser demo: `wss://shell.phux.sh/session` (anonymous edge shell, or
  authenticate with GitHub/Google for a native Linux shell).

## Documentation (docs.phux.sh)

- [Start here](https://docs.phux.sh/overview): guides and reference.
- [Install](https://docs.phux.sh/installation): supported platforms and installation channels.
- [Quickstart](https://docs.phux.sh/getting-started): start, split, detach, and inspect your first terminal.
- [Run coding agents](https://docs.phux.sh/agents): choose an integration and verify it works.
- [ACP-owned sessions](https://docs.phux.sh/acp): provider readiness, typed commands, human permissions, and uncertain outcomes.
- [Terminal MCP adapter](https://docs.phux.sh/agents): connect to your running local phux server, not the hosted docs service.
- [Remote access](https://docs.phux.sh/remote): connect machines and repair connections.
- [Clients](https://docs.phux.sh/clients): TUI, desktop, web, and native consumer paths.
- [Embedding](https://docs.phux.sh/embedding): supported runtime ownership and renderer integration.
- [Troubleshoot](https://docs.phux.sh/troubleshooting): diagnostics, persistence boundaries, and recovery.
- [Concepts](https://docs.phux.sh/concepts): running terminals, sessions, and shared control.
- [Automation reference](https://docs.phux.sh/scripting): selectors, input, waits, and structured results.
- [Command reference](https://docs.phux.sh/reference/cli): generated CLI documentation.
- [Wire protocol](https://docs.phux.sh/protocol): framing, terminal substrate, and metadata.
- [Architecture](https://docs.phux.sh/architecture): implementation and contributor reference.
- [Historical decisions](https://github.com/no-phux/phux/tree/d21db2e345aeaff43a681b3a04dfd43f2cc082ca/docs/adr): immutable rationale archive, not current behavior. Live constraints and lookup commands are in Architecture.

## Project

- Source: https://github.com/no-phux/phux
- Releases: https://github.com/no-phux/phux/releases
- License: Apache-2.0