---
title: <Worktree>
description: Execute a subtree in a separate JJ worktree rooted at `path`.
---

## Import

```tsx
import { Worktree, Task, Parallel, MergeQueue } from "smithers-orchestrator";
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | auto-generated | Stable id for tracking/deduping. |
| `path` | `string` | -- | Filesystem path for the [JJ](https://martinvonz.github.io/jj) [worktree](https://git-scm.com/docs/git-worktree) root. Required; non-empty. |
| `branch` | `string` | `undefined` | Branch to check out. Omit to use the current branch. |
| `baseBranch` | `string` | `"main"` | Base branch/revision for sync or creation. |
| `skipIf` | `boolean` | `false` | Skip the subtree. |
| `children` | `ReactNode` | -- | Nested [tasks](/components/task) and [control-flow nodes](/concepts/control-flow). |

## Basics

```tsx
<Worktree path="/tmp/smithers/wt-a">
  <Task id="build" output={outputs.outputC}>{{ value: 1 }}</Task>
  <Task id="test" output={outputs.outputC}>{{ value: 2 }}</Task>
  <MergeQueue>
    <Task id="apply" output={outputs.outputC}>{{ value: 3 }}</Task>
  </MergeQueue>
  <Parallel maxConcurrency={2}>
    <Task id="lint" output={outputs.outputC}>{{ value: 4 }}</Task>
  </Parallel>
  <Task id="package" output={outputs.outputC}>{{ value: 5 }}</Task>
  <Task id="release" output={outputs.outputC}>{{ value: 6 }}</Task>
</Worktree>
```

Descendant [tasks](/components/task) receive `worktreeId` and a normalized absolute `worktreePath` in their descriptors. The engine uses `worktreePath` as `cwd` for JJ operations and tool execution.

## Path Resolution

| Input | Behavior |
| --- | --- |
| Relative path | Resolves against `baseRootDir` (or `process.cwd()`). |
| Absolute path | Preserved and normalized. |
| Empty/whitespace | Rejected: `<Worktree> requires a non-empty path prop`. |

## Nesting

Innermost `<Worktree>` in scope determines a task's effective `worktreeId`/`worktreePath`.

```tsx
<Worktree id="outer" path="/tmp/wt-outer">
  <Task id="a" output={outputs.outputC}>{{ value: "outer" }}</Task>
  <Worktree id="inner" path="./nested">
    <Task id="b" output={outputs.outputC}>{{ value: "inner" }}</Task>
  </Worktree>
</Worktree>
```

## With [`<Parallel>`](/components/parallel) and [`<MergeQueue>`](/components/merge-queue)

```tsx
<Worktree path="/tmp/wt-queue">
  <MergeQueue>
    {prs.map((pr) => (
      <Task key={pr.id} id={`apply-${pr.id}`} output={outputs.outputC}>
        {{ value: pr.id }}
      </Task>
    ))}
  </MergeQueue>
</Worktree>
```

## Internals

- Renders to `<smithers:worktree>`.
- Extraction assigns `worktreeId` and `worktreePath` to every descendant task descriptor.
- The scheduler is unaware of worktrees; the engine consumes these fields to scope JJ operations and reverts.

## Notes

- Duplicate `id` values are rejected.
- Use `baseBranch` to create/rebase from something other than `main`.
- Prefer absolute ephemeral paths in CI; relative paths for local portability.