Skip to content
workrex

What is workrex?

Copy page

workrex runs AI coding agents in parallel. Each task gets its own git worktree, its own branch, and its own session in Rex, with the agent already started. Agents never share a working directory, so one agent’s edits and builds never get in another agent’s way. When a task is done, workrex merge merges the branch and removes the worktree, the Rex session, and the local branch.

Workrex is a Rex-only application with its own configuration, status hooks, and agent skills. It builds on an MIT-licensed project originally authored by Raine Virta. See NOTICE.md for attribution.

A task from start to finish

Section titled “A task from start to finish”

Run these commands from a Rex pane inside your project’s repository:

Terminal window
# Start an agent in a new worktree and Rex session
workrex add user-auth -p "Add password reset"


# Watch every agent; Enter jumps to its session
workrex dashboard


# Merge, then remove the worktree, session, and branch
workrex merge user-auth

Without workrex, the same task takes a git worktree add, a copy of your .env, a dependency install, a new session with the right panes, and the agent command typed by hand. Cleanup takes several more commands. workrex runs those steps from your configuration.

How workrex uses Rex

Section titled “How workrex uses Rex”

Workrex connects to Rex using REX_SERVER. Rex supplies REX_SESSION and REX_BLOCK in its terminal blocks, so commands can target the caller precisely.

  • One session per task. Each worktree gets its own Rex session. To get one tab per task in the current session instead, set mode: window.
  • Rex.app stays where it is. workrex add can run from a background agent’s pane, so it never switches the app. It prints how to open the new session.
  • Status without hooks. Agents that report Rex program status, such as Claude Code, show whether they are working, waiting, or done.
  • A floating dashboard. With the bundled Lua file loaded, a key opens the dashboard as a layer over the current tab.

The Rex guide covers terminal identity, navigation, and server scope.

What else workrex does

Section titled “What else workrex does”
  • Copies or symlinks files such as .env and node_modules into new worktrees, and runs setup commands after creation. See Configuration.
  • Lets an agent hand tasks to new worktrees with the /worktree skill.
  • Names branches from your prompt with --auto-name.
  • Runs agents in containers or VMs, or on remote servers over SSH.
  • Sends prompts to running agents and waits on them from scripts, with send, capture, and wait. See the command reference.

Why git worktrees

Section titled “Why git worktrees”

A git worktree is a second checkout of the same repository, on its own branch, in its own directory. Switching tasks is a cd, with no stash and no temporary commit. Two worktrees can build, install dependencies, and run tests at the same time without touching each other’s files. That isolation lets several agents work on one repository at once.

Requirements

Section titled “Requirements”
  • macOS on Apple Silicon or Linux on x86_64 for the prebuilt binaries. Other platforms can build from source.
  • Git 2.5 or later.
  • Rex, with a server that speaks API revision 8 or 9.

To get started, install workrex, then follow the quick start.