# Worktree

> Understand draft isolation, revision baselines, OT merging, and how AI SDK connects agent editing with human review.

- Human documentation: [https://docs.univer.ai/overview/features/shared/worktree](https://docs.univer.ai/overview/features/shared/worktree)

- Agent Markdown: [https://docs.univer.ai/overview/features/shared/worktree.md](https://docs.univer.ai/overview/features/shared/worktree.md)

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.6.0`

- Source: [features/shared/worktree.mdx](https://github.com/dream-num/documentation/blob/dev/content/docs/features/shared/worktree.mdx)

---

Worktree provides isolated drafts of Office content that people and agents can still edit together. An agent can revise a budget, reorganize data, or rewrite a brief while people continue editing the main document, which is called the trunk. The draft is validated and reviewed before its changes reach the trunk.

The isolation applies to document content and its changes, not to a Git working directory. A single task can span several [Units](https://docs.univer.ai/guides/sheets/getting-started/quickstart.md#unit), for example a workbook, a document and a presentation.

## Isolation: evolve from a shared baseline

When a Worktree is created for an existing Unit, the service records that Unit's current trunk revision as the **baseline**. The draft starts from that revision and has its own snapshots, changesets, revisions, Presence and collaboration Rooms. Edits made in the draft do not affect the trunk.

```mermaid
flowchart LR
    A["Trunk at creation<br/>Baseline"]
    B["Trunk keeps evolving"]
    C["Worktree draft"]
    D["Ready · Review"]
    E["OT merge"]
    F["New trunk revision"]
    A --> B
    A --> C --> D
    B --> E
    D --> E --> F
```

| Concept | Role |
| --- | --- |
| Baseline | The trunk version from which the draft started, used for comparison and merging. |
| Draft head | The newest confirmed draft revision. Draft submissions move it forward. |
| Ready head | The frozen draft revision that defines what gets reviewed and merged. |

The trunk and the draft advance independently. Revisions on each side form a separate submission sequence, so a higher number does not indicate which content is newer. Pulling a draft synchronizes the draft's own changes. New trunk edits do not enter the version under review on their own; the merge preview and the merge itself reconcile the two.

## How AI SDK targets the same draft

AI SDK's Collaboration Runtime manages one Unit's snapshots, changesets and revisions. On the Server SDK side, the Worktree service owns creation, lifecycle and merging. The Runtime does not require a second editing engine to work with Worktrees.

The application resolves `worktreeID + unitID` into the draft's snapshot, submit, WebSocket and Session Ticket URLs, then passes them to the Runtime. The same inspection and editing tools can then target either the trunk or a draft.

```mermaid
flowchart LR
    A["Agent / business CLI"]
    B["Human Web review"]
    C["Application target adapter"]
    D["Worktree Endpoint"]
    E["Same draft Unit"]
    A --> C
    B --> C
    C --> D --> E
```

One Unit ID can exist in the trunk and in several Worktrees at once. The target must include the Worktree in which it lives, and inspection, execution, screenshots and the Web preview should all use that same target. Otherwise a tool can read from a draft and write to the trunk. The Web client loads the same draft with the collaboration configuration that matches it.

| Component | Responsibility |
| --- | --- |
| Web SDK | The shared content engine, for Headless agent operations and for editing in the browser. |
| Server SDK | Draft isolation, changeset and revision persistence, lifecycle, and OT merging. |
| AI SDK | The composable Runtime, Inspection, API lookup, Facade execution, and visual checks. |
| Your application | Model selection, target mapping, identity, authorization, tasks, and the review UI. |

## From agent editing to handoff

The application can run tasks in parallel by giving each agent its own Worktree. Each agent edits its draft, checks the result and marks it Ready. A person then reviews the drafts one at a time, reopens the draft that needs more work, and merges the accepted drafts into the current trunk.

```mermaid
flowchart TB
    TRUNK["Main document · Trunk"]
    subgraph PARALLEL["Agents work in parallel"]
        direction LR
        AGENT_A["Agent A<br/>Worktree A<br/>Edit and validate"]
        AGENT_B["Agent B<br/>Worktree B<br/>Edit and validate"]
        AGENT_C["Agent C<br/>Worktree C<br/>Edit and validate"]
    end
    REVIEW["Human review<br/>Drafts and previews"]
    MERGE["Merge individually<br/>Into current trunk"]
    RESULT["New trunk revision"]
    TRUNK --> AGENT_A
    AGENT_A -->|"Ready"| REVIEW
    TRUNK --> AGENT_B
    AGENT_B -->|"Ready"| REVIEW
    TRUNK --> AGENT_C
    AGENT_C -->|"Ready"| REVIEW
    REVIEW -->|"Approve"| MERGE
    REVIEW -.->|"Reopen the relevant draft"| PARALLEL
    MERGE --> RESULT
```

1. Create the Worktree and load it. Select the Units that the task covers, connect the Worktree target, and pull its latest content.
2. Inspect the structure with Inspection, look up APIs as needed, and make changes through Facades.
3. Submit to the draft, read back the data and the calculation results, and capture screenshots when needed. Slides can also run Layout Lint. If the checks report a problem, edit the draft again.
4. Mark Ready. This freezes each Unit's draft revision, and editing stops until the review is complete.
5. Review. Merge the accepted drafts. Reopen a draft back to Draft before a person or an agent edits again. Discard the drafts that are not needed.

| Operation | Effect |
| --- | --- |
| `runtime.commit()` | Submits to the draft only, and moves the draft revision forward. |
| `markReady()` | Freezes the review version without merging anything into the trunk. |
| `reopenWorktree()` | Takes a draft from Ready back to Draft, so editing can continue. |
| `mergeWorktree()` | Merges the frozen draft changes into the trunk, Unit by Unit. |

Commit, Ready and Merge are three separate operations. Once a draft is Ready, neither a person nor an agent can edit it until it has been reopened. For the relationship between the Runtime and the CLI, see the [AI SDK workflow](https://docs.univer.ai/ai/worktree.md).

## Merging changes into current trunk

For a Unit that came from the trunk, the service reads the draft changesets from the **baseline to Ready head**, collects their mutations, and submits them through the trunk Collaboration Service. If the trunk has advanced since the baseline, [OT](https://docs.univer.ai/overview/features/shared/collaboration.md) transforms those mutations against the later trunk edits before the service confirms a new revision.

Merging therefore applies edits; it does not replace the latest document with an old snapshot. Concurrent changes that can be transformed are reconciled. Changes that cannot be transformed, or that no longer apply, are returned as conflicts for the application to handle. OT does not settle every business disagreement.

A Unit created inside a Worktree has no trunk baseline to merge against. Merging creates it in the trunk without copying the whole draft changeset history.

## Review the edits and the merge result

- To see what changed, compare the complete baseline state with the Ready draft state using [Compare](https://docs.univer.ai/overview/features/shared/compare.md).
- To see what merging would do at a given moment, call `evaluateUnitMerge()` after Ready. When the trunk has advanced, an isolated Runtime applies an OT-transformed candidate to the current trunk and produces a read-only preview. It submits no changeset and modifies neither the trunk nor the draft.

A preview describes the state at the moment it is requested. The trunk can change afterwards, and the actual Merge works from the state it finds when it runs. Merging several Units is not one atomic transaction either, so if one Unit fails, the Units that have already merged remain merged. Display the outcome for each Unit and handle failures individually.

## Integration and coverage

Combine the Worktree Client, Service, Endpoint and database adapters with the collaboration core. Keep draft storage separate, and share one Session Ticket Store with the trunk. The application authorizes draft access and trunk writes separately; isolation does not grant access by itself.

Sheet, Doc, Slide, Canvases and Relational Table are supported. PDF is not included. The [example](https://docs.univer.ai/server/collaboration/examples.md#worktree), the [extension modules](https://docs.univer.ai/server/collaboration/packages.md#worktree) and the [agent integration guide](https://docs.univer.ai/ai/worktree.md) provide starting points.

[Back to all features](https://docs.univer.ai/overview/features.md)
