Installation

workrex ships prebuilt binaries for macOS on Apple Silicon (darwin-arm64) and Linux on x86_64 (linux-amd64). On other platforms, build from source.

Workrex needs a running Rex server and the rex CLI on your PATH. See the Rex installation docs.

Install script

The install script downloads the latest release for your platform, checks its SHA-256 checksum, and puts workrex in /usr/local/bin, or in ~/.local/bin when /usr/local/bin is not writable.

curl -fsSL https://raw.githubusercontent.com/kong109/workrex/main/scripts/install-workrex.sh | bash

To pick the directory, set WORKREX_INSTALL_DIR. To pin a release, set WORKREX_VERSION:

curl -fsSL https://raw.githubusercontent.com/kong109/workrex/main/scripts/install-workrex.sh | WORKREX_VERSION=v0.1.278-rex.1 bash

Configuration uses .workrex.yaml, ~/.config/workrex/, and WORKREX_* environment variables. See Configuration.

Release tarball

Each release has a workrex-<platform>.tar.gz and a matching .sha256 file. This example installs the macOS build. For Linux, use workrex-linux-amd64 and sha256sum -c.

curl -fsSLO https://github.com/kong109/workrex/releases/latest/download/workrex-darwin-arm64.tar.gz
curl -fsSLO https://github.com/kong109/workrex/releases/latest/download/workrex-darwin-arm64.sha256
shasum -a 256 -c workrex-darwin-arm64.sha256
tar -xzf workrex-darwin-arm64.tar.gz
mv workrex ~/.local/bin/

Build from source

Building needs Rust. Install it with rustup if you don’t have it, then install the workrex package from this repository:

cargo install --git https://github.com/kong109/workrex --bin workrex

Update

To update a binary from the install script or a tarball, run workrex update. For a source build, run the cargo install command again.

Existing installations

This build uses its own configuration, state, cache, and Git metadata namespaces. Use .workrex.yaml for each project’s settings and WORKREX_* for environment overrides. A copied global profile preserves preferences; it does not import earlier workspace ownership, recovery records, remote placements, or agent conversation history.

Existing sessions and earlier stored data are left intact. Finish or stop agents started by an older build before reopening their worktrees with this build. Rex can rediscover some running agents for display, but that does not transfer their earlier management records.

Shell alias

To type less, alias workrex to wr in your .bashrc, .zshrc, or other shell configuration file:

alias wr='workrex'

Shell completions

To complete commands and branch names, add the line for your shell to its configuration file.

Bash

# Add to ~/.bashrc
eval "$(workrex completions bash)"

Zsh

# Add to ~/.zshrc
eval "$(workrex completions zsh)"

Fish

# Add to ~/.config/fish/config.fish
workrex completions fish | source

Uninstall

The uninstall script runs workrex uninstall, which removes the status hooks and skills that workrex setup installed, workrex’s state directory, and its update cache. Then the script deletes the binary from /usr/local/bin, ~/.local/bin, and ~/.cargo/bin. To see what workrex uninstall would remove, run workrex uninstall --dry-run.

curl -fsSL https://raw.githubusercontent.com/kong109/workrex/main/scripts/uninstall-workrex.sh | bash

The script preserves your configuration at ~/.config/workrex/. Delete it yourself when you no longer need those settings. Remove the completion line and the wm alias from your shell configuration. To find worktrees that are still on disk, run git worktree list.