Create or Adopt a Worktree

Create a Worktree when CompozyOS should choose the managed path and run the workspace bootstrap. Adopt one when git worktree list already contains the checkout.

Create a managed Worktree

1. Check the repository

compozy worktree list --workspace . --refresh -o json

Expected result:

[]

The CLI list is the registered-record projection. Use compozy__worktree_list or GET /api/workspaces/{workspace_id}/worktrees when automation also needs discovered checkouts and the repository capability diagnostic. If creation returns workspace_not_git_backed, register the repository root as the workspace before continuing.

2. Create from a base ref

compozy worktree create feature-auth --workspace . --base main -o json

The response is accepted before filesystem work finishes. IDs and paths vary, but the initial shape is:

{
  "id": "wt_01...",
  "name": "feature-auth",
  "branch": "feature-auth",
  "state": "pending",
  "pending_phase": "branch",
  "origin": "manual"
}

Use --branch <branch> to choose the new branch, --existing-branch <branch> to attach an existing branch, or --path <absolute-path> to override managed placement. A new branch base resolves from --base, the repository's remote default, then the current branch.

3. Wait for readiness

compozy worktree inspect feature-auth --workspace . -o json

Creation advances through branch, checkout, copy, and setup. The Worktree becomes selectable only after:

{
  "worktree": {
    "name": "feature-auth",
    "state": "ready",
    "setup_state": "none"
  }
}

With a non-empty setup_command, setup_state becomes ok after a successful bootstrap.

Cancel only while it is pending:

compozy worktree cancel feature-auth --workspace . -o json

Adopt an existing linked checkout

1. Confirm Git owns it

git -C /src/acme worktree list

The candidate must be a linked Worktree for the same repository. The main checkout, an unrelated repository, a bare checkout, or an unreadable .git pointer is refused.

2. Adopt the absolute path

compozy worktree adopt /src/acme-feature-auth --workspace /src/acme -o json

Expected result:

{
  "id": "wt_01...",
  "name": "feature-auth",
  "path": "/src/acme-feature-auth",
  "state": "ready",
  "origin": "adopted"
}

Adoption is idempotent: repeating it returns the existing record. If that exact recorded path was missing, adoption verifies the Git identity and restores the same record to ready.

Bootstrap contract

Managed creation applies [worktrees] in this order:

1. Create or attach the branch and linked checkout.
2. Copy ignored, untracked files matched by the relative Git pathspecs in copy_list, without overwriting repository files.
3. Run setup_command inside the new Worktree with setup_timeout.
4. Publish worktree.created only after the record is ready.

See Worktree configuration for an annotated setup and validation rules.