> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reliantlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Run parallel coding agents in separate git worktrees

> Run two AI coding agents at once, each in its own git worktree and branch, wait for both with a join, and have a reviewer agent pick the change to keep.

By the end of this guide you have a workflow that gives two coding agents the same task at the same time, each in its own git worktree on its own branch. A `join` waits for both, and a reviewer agent reads both checkouts and picks one.

Two agents in one checkout overwrite each other's files. In two workspaces they edit, test and commit without touching each other or your main checkout.

## Before you begin

* The `reliant` CLI, v1.21 or later (`reliant version`). Validating, linting and scenario runs need no account.
* A git repository with a test you can run. This guide uses a Python repo with a `text.py` and a unittest.
* For the live run: a signed-in CLI ([Sign in and tokens](https://docs.reliantlabs.io/cli/sign-in.md)) and a connected machine that holds the repository ([Run a machine from the terminal](https://docs.reliantlabs.io/cli/run-a-machine.md)).
* The basics of workflow files, from [Write your first multi-agent workflow](https://docs.reliantlabs.io/guides/workflows/first-multi-agent-workflow.md).

**1. Create the workflow file**

Save this as `.reliant/workflows/two-approaches.yaml`:

```yaml .reliant/workflows/two-approaches.yaml theme={null}
name: two-approaches
title: Two approaches, one reviewer
description: Two agents implement the same task in separate workspaces, at the same time. A reviewer reads both and picks one.

entry: [workspace_a, workspace_b]   # both start at once

nodes:
  # One workspace per agent: its own directory and its own branch,
  # started from the commit the chat's checkout is on now.
  - id: workspace_a
    type: create_worktree
    args:
      name: approach-a-{{workflow.id}}
      base_branch: "{{has(workflow.branch) ? workflow.branch : 'HEAD'}}"

  - id: workspace_b
    type: create_worktree
    args:
      name: approach-b-{{workflow.id}}
      base_branch: "{{has(workflow.branch) ? workflow.branch : 'HEAD'}}"

  # project.path makes the workspace the agent's working directory, so its
  # file and shell tools edit that checkout and nothing else.
  - id: implement_a
    type: workflow
    ref: builtin://agent
    project:
      path: "{{nodes.workspace_a.path}}"
    args:
      mode: auto
    thread:
      mode: fork
      inject:
        role: user
        content: |
          You are candidate A. Do the task above in your working directory.
          Use the standard library's re module. Run the tests before you finish.
    save_message:
      role: assistant
      content: "Candidate A:\n{{output.response_text}}"

  - id: implement_b
    type: workflow
    ref: builtin://agent
    project:
      path: "{{nodes.workspace_b.path}}"
    args:
      mode: auto
    thread:
      mode: fork
      inject:
        role: user
        content: |
          You are candidate B. Do the task above in your working directory.
          Do not use regular expressions. Run the tests before you finish.
    save_message:
      role: assistant
      content: "Candidate B:\n{{output.response_text}}"

  # Waits for both agents. Its sources are every node with an edge into it.
  - id: both_done
    type: join

  - id: review
    type: workflow
    ref: builtin://structured-agent
    args:
      mode: auto
      max_turns: 30
      tools: ["view", "tag:shell"]
      system_prompt: You compare two implementations of one task. You never change files.
      response_tool_name: pick_winner
      response_schema:
        type: object
        required: [winner, rationale]
        properties:
          winner:
            type: string
            enum: [a, b]
          rationale:
            type: string
    thread:
      mode: fork
      inject:
        role: user
        content: |
          Two candidates did the task above. Read both and run their tests:
          - A: {{nodes.workspace_a.path}}
          - B: {{nodes.workspace_b.path}}
          Pick the one you would merge.

  - id: report
    type: save_message
    outcome: success
    args:
      role: assistant
      content: |
        Winner: candidate {{nodes.review.response.winner}}
        ({{nodes.review.response.winner == 'a' ? nodes.workspace_a.branch : nodes.workspace_b.branch}})

        {{nodes.review.response.rationale}}

edges:
  - from: workspace_a
    default: implement_a
  - from: workspace_b
    default: implement_b
  - from: implement_a
    default: both_done
  - from: implement_b
    default: both_done
  - from: both_done
    default: review
  - from: review
    default: report
```

What each part does:

* **`entry` lists two nodes**, so both branches start together.
* **[`create_worktree`](https://docs.reliantlabs.io/reference/nodes#create-worktree)** makes a workspace and outputs its `path` and `branch`. `base_branch` starts from the chat's workspace branch, or the main checkout's current commit (`HEAD`). Add `copy_files` for untracked files such as `.env` ([Workspaces](https://docs.reliantlabs.io/features/worktrees.md#copying-configuration-files)).
* **`project.path`** runs each agent inside its workspace. Without it, both would work in your main checkout.
* **`thread: mode: fork`** gives each agent your request; each `inject` adds a different approach.
* **[`join`](https://docs.reliantlabs.io/reference/nodes#join)** waits for both implementers. A skipped source counts as finished ([How workflows run](https://docs.reliantlabs.io/deep-dives/how-workflows-run.md)).
* **The reviewer** answers through a schema, so `report` can name the winning branch.

**2. Validate, lint and test it with a scenario**

A scenario checks the fan-out and join with mocked results, without spending tokens. Save it as `.reliant/workflows/two-approaches/scenarios/reviewer_picks_b.yaml`:

```yaml .reliant/workflows/two-approaches/scenarios/reviewer_picks_b.yaml theme={null}
name: reviewer_picks_b
description: Both candidates finish in their own workspaces; the reviewer picks B

events:
  - node: workspace_a
    output: { path: /home/me/.reliant/worktrees/approach-a-run1, branch: approach-a-run1 }
  - node: workspace_b
    output: { path: /home/me/.reliant/worktrees/approach-b-run1, branch: approach-b-run1 }
  - node: implement_a
    output: { response_text: "Added slugify() with re.sub. 2 tests pass." }
  - node: implement_b
    output: { response_text: "Added slugify() with a character loop. 3 tests pass." }
  - node: review
    output:
      completed: true
      response: { winner: b, rationale: "B handles repeated separators and has an extra test." }

expect:
  outcome: completed
  completed: [workspace_a, workspace_b, implement_a, implement_b, both_done, review, report]
  messages:
    report:
      content_contains: ["Winner: candidate b", "approach-b-run1"]
```

```bash terminal theme={null}
reliant workflow validate && reliant workflow lint && reliant workflow scenario run
```

```text theme={null}
  ✓ two-approaches.yaml (two-approaches)
✅ All workflows valid
...
1 workflow(s): 0 lint error(s), 0 warning(s)
Running 1 scenario(s) across 1 workflow(s)

  ✓ two-approaches/reviewer_picks_b (461ms)
...
✅ All scenarios passed
```

**3. Run it**

Commit your work first: each workspace starts from the current commit, so uncommitted edits are not in it.

```bash terminal theme={null}
reliant workflow run two-approaches --project-path . \
  --message "Add slugify(text) to text.py: lower-case the text, drop characters that are not letters, digits or spaces, and join the words with '-'. Add a unittest test in test_text.py. Run the tests with python3 -m unittest." \
  --follow --timeout 25m
```

```text theme={null}
Workflow "two-approaches" triggered
  Chat/Execution ID: 401f7605-031b-4e04-a990-3f68eaa8ab84
{"event":"node_started",...,"node_id":"workspace_b",...,"timestamp":"2026-11-20T10:00:12Z"}
{"event":"node_started",...,"node_id":"workspace_a",...,"timestamp":"2026-11-20T10:00:12Z"}
...
{"event":"workflow_completed",...,"new_state":"completed",...,"outcome":"success"}
```

Both workspaces were created in the same second, then both agents ran side by side.

**4. Verify the result**

Check the run, then look at the workspaces from the repository:

```bash terminal theme={null}
reliant workflow status 401f7605-031b-4e04-a990-3f68eaa8ab84
git worktree list
```

```text theme={null}
Execution 401f7605-031b-4e04-a990-3f68eaa8ab84
  Workflow:  two-approaches
  Status:    COMPLETED
  Outcome:   ✓ SUCCESS
  Started:   2026-11-20T10:00:07Z
  Completed: 2026-11-20T10:01:14Z
...
.../guides-sandbox-parallel                                                     7801d7d [main]
~/.reliant/worktrees/guides-sandbox-parallel/approach-a-401f7605-...-1bdfde86   7801d7d [worktree/approach-a-401f7605-...-1795168812] locked
~/.reliant/worktrees/guides-sandbox-parallel/approach-b-401f7605-...-46fb4193   7801d7d [worktree/approach-b-401f7605-...-1795168812] locked
```

Each candidate's change is in its own workspace. Here A used `re.sub` and B used `str.isalnum()`, as their prompts asked:

```bash terminal theme={null}
git -C ~/.reliant/worktrees/guides-sandbox-parallel/approach-b-401f7605-...-46fb4193 diff -- text.py
```

```text theme={null}
+def slugify(text):
+    kept = "".join(c for c in text.lower() if c.isalnum() or c == " ")
+    return "-".join(kept.split())
```

The `report` message, in the run under **Runs** in the app, names the winner and its branch:

```text theme={null}
Winner: candidate b
(worktree/approach-b-401f7605-031b-4e04-a990-3f68eaa8ab84-1795168812)

Both candidates are correct and their suites pass ... I chose B because it does what the task asks ...
A's `[^a-z0-9 ]` only keeps plain A–Z letters and 0–9, so it deletes letters from inside words.
```

**5. Keep the winner and clean up**

Open the winner in the app's **Workspaces** panel and commit, push or open a pull request from its **Changes** tab ([Git integration](https://docs.reliantlabs.io/features/git-integration.md)). Then **Archive** both workspaces. An archived workspace leaves the disk once nothing in it would be lost, so one with uncommitted or unpushed work stays.

`locked` in `git worktree list` is Reliant's lock, so plain `git worktree remove` refuses. To discard an archived candidate for good:

```bash terminal theme={null}
git worktree remove -f -f <path>
git branch -D <branch>
```

## From a chat: `spawn` with a workspace

Without a workflow file, ask a chat's agent to create the workspaces with its [`worktree` tool](https://docs.reliantlabs.io/reference/tools#worktree) and start a sub-agent in each:

```text Chat message theme={null}
Try two ways to add a word_count(text) function to text.py, in parallel. Create two workspaces
with the worktree tool, named wc-split and wc-regex. Start two general sub-agents in the same
turn, one in each workspace (spawn with worktree set): one implements it with str.split, the
other with the re module. Each adds a unittest test and runs python3 -m unittest. When both
report back, tell me which branch you would merge and why. Do not merge anything.
```

In a real run the agent called `worktree` with `action: create` twice, then `spawn` twice in one turn:

```json spawn call theme={null}
{ "preset": "general", "title": "word_count via str.split", "worktree": "wc-split", "prompt": "You are working in the worktree at ..." }
```

Each sub-agent committed on its own branch (`worktree/wc-split-1795170372`, `worktree/wc-regex-1795170372`), and the main agent recommended one ([Delegate work to parallel sub-agents](https://docs.reliantlabs.io/guides/workflows/delegate-to-sub-agents.md)). Use a workflow for the same steps every time, and a chat when the split depends on what the agent finds.

## The built-in version: Best of Three

[Best of Three](https://docs.reliantlabs.io/guides/best-of-three.md) runs three candidates in a parallel `loop`, after rewriting your prompt into a specification. It then applies the winner's changes with `git apply`, or has an agent merge the best parts, and runs your test and build commands.

## What this does not do

* **It does not merge anything.** Committing, pushing and merging are yours, or a [`git_publish`](https://docs.reliantlabs.io/reference/nodes#publish-branch) node's.
* **The pick is a model's judgment.** To make your test command the gate, add a `run` node per workspace and route on `exit_code`.
* **Workspaces are not a sandbox.** They isolate the agents' files from each other, not from your machine.
* **Everything runs on one machine.** A workspace exists on one machine's disk, so every agent working in it runs there ([chats, workspaces and machines](https://docs.reliantlabs.io/deep-dives/chats-worktrees-machines.md)).
* **Each candidate costs tokens.** Two cost about twice one implementation, plus the review.

## Troubleshooting

> [accordion] save\_message field 'content' references `nodes`, which is not available in save\_message
>
> A node's `save_message` reads only `output`, `inputs`, `workflow` and `iter`. Read `nodes.workspace_a.branch` in a later node, as `report` does.

> [accordion] no machine has synced this project's workflows yet
>
> The first run on a new folder creates the project before its machine has synced `.reliant/workflows/`. Wait about 20 seconds and run it again.

> [accordion] fatal: cannot remove a locked working tree, lock reason: reliant: worktree …
>
> Reliant locks the worktrees it creates. Archive the workspace in the app first. To delete its directory anyway, run `git worktree remove -f -f <path>`.

## Next steps

> [card] [Best of Three](https://docs.reliantlabs.io/guides/best-of-three.md)
>
> Three candidates, a reviewer, and the winner applied with `git apply`.

> [card] [Delegate work to parallel sub-agents](https://docs.reliantlabs.io/guides/workflows/delegate-to-sub-agents.md)
>
> Fan work out from a chat with `spawn`, a plan and briefing files.

> [card] [How sub-agents and threads isolate context](https://docs.reliantlabs.io/deep-dives/sub-agents-and-threads.md)
>
> Threads, nesting depth, concurrency caps and workspaces.

> [card] [Workspaces](https://docs.reliantlabs.io/features/worktrees.md)
>
> Create, open, archive and clean up workspaces.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.