# What is workrex?

workrex runs AI coding agents in parallel. Each task gets its own
[git worktree](https://git-scm.com/docs/git-worktree), its own branch, and its
own session in [Rex](https://www.superlogical.com/rex/docs/), 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](https://github.com/raine). See
[NOTICE.md](https://github.com/kong109/workrex/blob/main/NOTICE.md) for attribution.

## A task from start to finish

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

```bash
# 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](https://kong109.github.io/workrex/guide/configuration/).

## 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](https://kong109.github.io/workrex/guide/dashboard/) as a layer over the current tab.

The [Rex guide](https://kong109.github.io/workrex/guide/rex/) covers terminal identity, navigation, and server scope.

## 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](https://kong109.github.io/workrex/guide/configuration/).
- Lets an agent hand tasks to new worktrees with the
  [`/worktree` skill](https://kong109.github.io/workrex/guide/skills/#worktree).
- Names branches from your prompt with
  [`--auto-name`](https://kong109.github.io/workrex/reference/commands/add/#automatic-branch-name-generation).
- Runs agents in [containers or VMs](https://kong109.github.io/workrex/guide/sandbox/), or on
  [remote servers](https://kong109.github.io/workrex/guide/remote/) over SSH.
- Sends prompts to running agents and waits on them from scripts, with `send`,
  `capture`, and `wait`. See the [command reference](https://kong109.github.io/workrex/reference/commands/).

## 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

- macOS on Apple Silicon or Linux on x86_64 for the prebuilt binaries. Other
  platforms can [build from source](https://kong109.github.io/workrex/guide/installation/#build-from-source).
- Git 2.5 or later.
- Rex, with a server that speaks API revision 8 or 9.

To get started, [install workrex](https://kong109.github.io/workrex/guide/installation/), then follow the
[quick start](https://kong109.github.io/workrex/guide/quick-start/).