Installation#

#Install

Via npm (recommended) — the wrapper resolves and downloads the correct platform binary on first run:

npm install -g @lbdremy/phax
# or without installing:
npx @lbdremy/phax

Direct binary download — grab the binary and checksum for your platform from GitHub Releases:

# Example: macOS Apple Silicon
curl -LO https://github.com/lbdremy/phax/releases/latest/download/phax-darwin-arm64
curl -LO https://github.com/lbdremy/phax/releases/latest/download/phax-darwin-arm64.sha256
sha256sum --check phax-darwin-arm64.sha256
chmod +x phax-darwin-arm64
sudo mv phax-darwin-arm64 /usr/local/bin/phax
# macOS: remove the quarantine attribute added by the browser/curl
xattr -dr com.apple.quarantine /usr/local/bin/phax

macOS Gatekeeper note: binaries are not yet code-signed or notarized. Without the xattr step above, macOS will block the binary on first run. Go to System Settings → Privacy & Security to allow it, or run the xattr command.

Available targets: phax-darwin-arm64, phax-darwin-x64, phax-linux-x64, phax-linux-arm64.

Binary size note: the compiled binary is ~74 MB. The release build bundles the CLI with esbuild first (tree-shaken to ~1.5 MB of actually-used code) and then runs deno compile --include to embed the three runtime-read data files (package.json, phax.usage.kdl, .claude/skills). This avoids the un-bundled path which would embed ~274 MB of node_modules files (~360 MB total). The npm wrapper downloads the binary once and caches it per version at ~/.phax/bin/<version>/, so the cost is a one-time download per upgrade.

#Runtime permission posture

The distributed phax binary is compiled with an explicit Deno permission set:

Important: Deno's permissions sandbox phax, not the provider CLIs it launches. Once phax spawns claude, codex, or vibe, those processes run with their own provider-native permissions and are not constrained by phax's Deno permission set. Provider-level security (filesystem jail, network restrictions, tool allowlists) comes from the provider's own sandbox — see Security modes and the Security notes section.

phax open uses the OS opener (open on macOS, xdg-open on Linux) so no editor binary needs to be installed or configured. The meaningful security boundaries are the provider-native jail (filesystem, network, tool restrictions) and phax's structured argv invocation — phax never interpolates user input into shell strings.

Requirements: at least one provider CLI on $PATH:

• claude — Claude Code (default, and the terminal fallback provider)
• vibe — Mistral Vibe (optional)
• codex — OpenAI Codex (optional)

Most setups want claude installed even when routing prefers another provider, because phax falls back to Claude Code when the preferred provider is unavailable or cannot satisfy the active security posture.

#Shell completions

phax ships a generated shell completion script via phax completions <shell>. Supported shells: zsh, bash, fish, nu, powershell.

Prerequisite: the usage CLI must be installed — it is needed both to generate the script and at Tab-time (the generated script calls back into usage complete-word):

brew install usage

Per-shell install:

# zsh (default shell on macOS) — write a _phax completion onto your $fpath.
# If you already have a completions dir on $fpath, just drop the file in:
phax completions zsh > "${fpath[1]}/_phax"

# bash
source <(phax completions bash)
# or add to ~/.bashrc:
echo 'source <(phax completions bash)' >> ~/.bashrc

# fish
phax completions fish > ~/.config/fish/completions/phax.fish

# nushell — add to your nu config
phax completions nu | save --force ~/.config/nushell/completions/phax.nu
# source it in env.nu or config.nu

# powershell
phax completions powershell >> $PROFILE

zsh on macOS, from scratch — if you don't already have a completions directory on $fpath, set one up once:

# 1. Create a directory for personal completions and put the _phax file in it.
mkdir -p ~/.zsh/completions
phax completions zsh > ~/.zsh/completions/_phax

# 2. Make zsh load it (add to ~/.zshrc). Skip the compinit line if your setup
#    already runs it — frameworks like oh-my-zsh do.
cat >> ~/.zshrc <<'RC'
fpath=(~/.zsh/completions $fpath)
autoload -Uz compinit && compinit
RC

# 3. Reload your shell, then Tab-complete:
exec zsh
phax <Tab>

After this, phax <Tab> lists subcommands and phax enter <Tab> completes run short-names live from your registry.

phax --usage and phax completions work from the release binary as well as from source. Both commands read phax.usage.kdl, which is embedded in the binary at build time via deno compile --include.

Once the completion script is installed, Tab also completes run short-names for commands that take one (phax enter, phax resume, phax archive, and others). Candidates are fetched live from phax ls --complete, so they reflect the actual runs in your registry at Tab-time.