Worktree
Understand draft isolation, revision baselines, OT merging, and how AI SDK connects agent editing with human review.
Worktree provides isolated, collaboratively editable drafts of Office content. An agent can revise a budget, organize data, or improve a brief while people continue editing the main document (trunk). Validate and review the draft before merging its changes.
It isolates document content and changes, rather than a Git working directory. One task can contain multiple Units, such as a workbook, document, and presentation.
Isolation: evolve from a shared baseline
For an existing Unit, creation records its current trunk revision as the baseline. The draft starts there, with separate snapshots, changesets, revisions, Presence, and collaboration Rooms. Intermediate agent edits stay out of trunk.
| Concept | Role |
|---|---|
| Baseline | Identifies the trunk version the draft started from, for comparison and merging. |
| Draft head | Latest confirmed draft revision, advanced by draft submissions. |
| Ready head | Frozen draft revision that defines the reviewed and merged scope. |
Trunk and draft can advance independently. Their revisions describe separate submission sequences; comparing numbers alone does not tell you which content is newer. Pulling a draft synchronizes draft changes. New trunk edits do not automatically enter the review version; merge preview and merging reconcile them.
How AI SDK targets the same draft
AI SDK’s Collaboration Runtime handles one Unit’s snapshots, changesets, and revisions. Server SDK’s Worktree service owns creation, lifecycle, and merging. The Runtime does not need another editing engine for Worktrees.
The application resolves worktreeID + unitID into draft snapshot, submit, WebSocket, and Session Ticket URLs, then supplies them to the Runtime. The same inspection and editing tools can target trunk or a draft.
A Unit ID can exist in trunk and several Worktrees. Include its Worktree in the target, and use the same target for inspection, execution, screenshots, and Web preview. Otherwise, a tool might read a draft but write to trunk. Web loads the same draft with its matching collaboration configuration.
| Component | Responsibility |
|---|---|
| Web SDK | Shared content engine for Headless agent operations and browser editing. |
| Server SDK | Draft isolation, changeset and revision persistence, lifecycle, and OT merging. |
| AI SDK | Composable Runtime, Inspection, API lookup, Facade execution, and visual checks. |
| Your application | Model selection, target mapping, identity, authorization, tasks, and review UI. |
From agent editing to handoff
The application can organize parallel tasks with a separate Worktree for each agent. Each agent edits, checks, and marks its draft Ready. A person reviews drafts individually, Reopens the corresponding draft for changes, and merges accepted work into current trunk.
- Create and load: choose task Units, connect the Worktree target, and pull its latest content.
- Inspect and edit: understand structure with Inspection, look up APIs as needed, and edit through Facades.
- Commit and verify: submit to the draft, read back data and calculation results, and capture screenshots when needed. Slides can also use Layout Lint. Repeat when checks find issues.
- Mark Ready: freeze each Unit’s draft revision and stop editing for review.
- Review: Merge accepted work; Reopen to Draft before either a person or agent edits again; Discard unwanted drafts.
| Operation | Effect |
|---|---|
runtime.commit() | Submit only to the draft and advance its revision. |
markReady() | Freeze the review version without merging into trunk. |
reopenWorktree() | Return Ready to Draft and allow editing again. |
mergeWorktree() | Merge frozen draft changes into trunk per Unit. |
Commit, Ready, and Merge are separate operations. Both people and agents must Reopen a Ready draft before editing. See the AI SDK workflow for Runtime and CLI composition.
Merging changes into current trunk
For a trunk-sourced Unit, the service reads draft changesets from the baseline to Ready head, collects their mutations, and submits them through trunk Collaboration Service. If trunk has advanced, OT transforms these against subsequent trunk edits before confirming a new revision.
Merging therefore applies edits rather than replacing the latest document with an old snapshot. Transformable concurrent changes are reconciled. Untransformable or inapplicable changes return conflicts for the application to handle; OT cannot settle every business disagreement.
A Unit created inside a Worktree has no trunk baseline. Merge creates it in trunk without copying the entire draft changeset history.
Review the edits and the merge result
- What changed? Compare the complete baseline and Ready draft states with Compare.
- What would merging do now? Call
evaluateUnitMerge()after Ready. When trunk has advanced, an isolated Runtime applies an OT-transformed candidate to current trunk and produces a read-only preview. It submits no changeset and modifies neither trunk nor draft.
Preview describes the state at request time. Trunk can change later, and actual Merge uses its execution-time state. Multi-Unit merging is not one atomic transaction: successful Units remain merged if another fails. Show per-Unit outcomes and handle failures individually.
Integration and coverage
Combine Worktree Client, Service, Endpoint, and database adapters with collaboration core. Keep draft storage separate and share a Session Ticket Store with trunk. Applications authorize draft access and trunk writes separately; isolation does not grant access automatically.
Sheet, Doc, Slide, Canvases, and Relational Table are supported; PDF is not included. Start with the example, extension modules, and agent integration guide.
How is this guide?