Quick start

In this tutorial, we start an agent on a task in its own worktree and Rex session, check on it from the dashboard, and merge its branch back.

Before you start, you need:

• workrex on your PATH. See Installation.
• Rex running, with a pane open in a git repository.
• An agent CLI, such as Claude Code.

1. Create the project configuration

In the repository’s root, run:

workrex init

Workrex writes a commented .workrex.yaml with project defaults. See Configuration for its options.

2. Choose the agent

workrex starts an agent only when the project has a CLAUDE.md or the configuration names an agent. Open .workrex.yaml and uncomment this line:

agent: claude

New worktrees now open with the agent in one pane and a shell in the other.

3. Start a task

Create a worktree for the task, and give the agent its prompt:

workrex add user-auth -p "Add password reset to the login page"

workrex creates the user-auth branch and its worktree, opens a Rex session for it, and starts the agent with your prompt. You should see output like this:

✓ Successfully created worktree and Rex session for 'user-auth'
  Base: main
  Worktree: /Users/you/projects/my-project__worktrees/user-auth
Rex.app stays put: to see user-auth, press Enter on its row in workrex dashboard.

The worktree is a sibling of your project directory:

~/projects/
├── my-project/                 your main checkout
│   └── .workrex.yaml
└── my-project__worktrees/
    └── user-auth/              the agent's checkout, on branch user-auth

To put worktrees somewhere else, set worktree_dir.

4. Check on the agent

Open the dashboard:

workrex dashboard

The dashboard lists each agent with its status. Select user-auth and press Enter. Rex.app switches to the task’s session. To open the dashboard with a key, see Dashboard in the Rex guide.

5. Merge the work

When the agent is done, run:

workrex merge user-auth

workrex merges user-auth into main, then removes the worktree, the Rex session, and the branch. workrex list now shows only main.

If you open a pull request instead, run workrex remove user-auth after it merges.

Next steps

• Run several tasks at once. Each workrex add gets its own worktree and session.
• Let an agent start tasks for you with the /worktree skill.
• Set up panes, file copies, and setup commands in Configuration.
• See Workflows and AI agents for longer patterns.