phux
A terminal multiplexer whose server you can drive from code.
phux keeps your shells running in a background server and shows them in a
terminal UI, like tmux. Commands expose panes, input, snapshots, and agent
state with JSON output and exit codes. The server tracks which panes run
a coding agent and whether it is waiting on you. Another machine is one
phux host add me@mini away, with no account.
Docs · Help · Releases ·
Install
CLI and terminal UI
curl -fsSL https://phux.sh/install | sh
Or use Homebrew. Run phux after installing.
Desktop app
macOS: download the DMG,
drag Phux.app to Applications, eject the image, and open Phux.
The app includes the CLI/server and is signed and notarized. Or install with
brew install --cask no-phux/tap/phux-desktop (Homebrew setup).
Linux: use the desktop installer.
Windows x64: use the PowerShell desktop installer
after setting up the WSL CLI/server.
Platform support
Other installation options. No Intel Mac or musl builds.
Use
phux # start the server, attach; Ctrl-A is the prefix, Ctrl-A d detaches
phux ls # what is running
From a POSIX shell, with jq installed, create a new shell pane and drive
only that pane. No terminal UI needs to be attached:
(
set -eu
session="phux-demo-$$"
created=$(phux new --json -s "$session" -- sh)
pane="@$(printf '%s\n' "$created" | jq -er .terminal_id)"
phux run --timeout 10 "$pane" 'printf "hello from phux\n"'
phux snapshot "$pane"
printf 'The shell is still running. From a terminal: phux attach %s\n' "$session"
)
run returns the command's output and exit status. Detaching or closing a
client leaves the shell running; attach to the printed session to take over.
Recorded with phux. Reproduce the capture.
Getting started ·
using phux as an agent ·
driving terminals from scripts ·
coding agents ·
build on phux ·
remote machines
Find your workflow
For agents
Install phux and drive a session from code with
Using phux as an agent.
phux knows which pane runs which agent and whether it is working, idle, or
blocked on you. Agents reach phux through plugins for Claude Code, pi, Oh
My Pi, OpenCode, and Grok, through the bundled MCP server (phux mcp), or
through the CLI. To hand the manual to your agent:
Run `phux skill` and follow it to work with my phux terminals.
For an opt-in fleet setup, Crew is the bundled
agent distro, with isolated homes, mission commands and
distro switching. It does not add a multi-host task
coordinator or autonomous delegation authority.
Status
The core product is the persistent server, CLI and terminal UI. Remote
hosts, agent integrations, MCP, plugins and distros are maintained features
you can opt into; none is required for a local shell session.
The desktop app is a maintained, separately versioned client for macOS,
Linux and Windows; it is newer and rougher than the terminal UI. The browser
client is experimental and unshipped. Phone apps are in progress elsewhere,
not available downloads. Clients covers their limits.
The wire protocol is 1.x; any 1.x client works with any 1.x server. See
protocol.
Contributing
CONTRIBUTING.md, then development.
phux is picky about new surface area; ask before building a feature.
Help
License
Apache-2.0. NOTICE ·
third-party notices
