Worktrees API

Overview

The Worktrees API provides functionality for creating and managing Git worktrees - isolated working directories that share the same repository history but allow working on different branches simultaneously.

Data Structures

Worktree

string

required

Unique identifier (UUID v4)

project_id

string

required

Foreign key to the parent project

name

string

required

Random workspace name (e.g., “fuzzy-tiger”)

path

string

required

Absolute path to worktree (defaults to ~/jean/PROJECT_NAME/WORKTREE_NAME)

branch

string

required

Git branch name (same as workspace name)

created_at

number

required

Unix timestamp when worktree was created

session_type

'worktree' | 'base'

default:"worktree"

Type of session (worktree = git worktree, base = base directory)

order

number

default:0

Display order within project (lower = higher in list)

pr_number

number | null

GitHub PR number (if a PR has been created)

pr_url

string | null

GitHub PR URL (if a PR has been created)

issue_number

number | null

GitHub issue number (if created from an issue)

label

object | null

User-assigned label with color

Show Label properties

name

string

required

Label text (e.g., “In Progress”)

color

string

required

Hex color code (e.g., “#eab308”)

archived_at

number | null

Unix timestamp when worktree was archived (null = not archived)

last_opened_at

number | null

Unix timestamp when worktree was last opened/viewed

Cached Status Fields

Worktrees maintain cached Git and GitHub status for performance:

cached_pr_status

string | null

PR status: “draft” | “open” | “review” | “merged” | “closed”

cached_check_status

string | null

CI check status: “success” | “failure” | “pending” | “error”

cached_behind_count

number | null

Commits behind base branch

cached_ahead_count

number | null

Commits ahead of base branch

cached_uncommitted_added

number | null

Lines added in working directory

cached_uncommitted_removed

number | null

Lines removed in working directory

cached_branch_diff_added

number | null

Lines added vs base branch

cached_branch_diff_removed

number | null

Lines removed vs base branch

cached_unpushed_count

number | null

Commits not yet pushed to origin

cached_status_at

number | null

Unix timestamp when status was last checked

Commands

List Worktrees

Retrieve all worktrees for a project.

projectId

string

required

ID of the project

const worktrees = await api.invoke('list_worktrees', {
  projectId: '550e8400-e29b-41d4-a716-446655440000'
});

Get Worktree

Retrieve a specific worktree by ID.

worktreeId

string

required

ID of the worktree

const worktree = await api.invoke('get_worktree', {
  worktreeId: '770e8400-e29b-41d4-a716-446655440002'
});

Create Worktree

Create a new Git worktree.

projectId

string

required

ID of the project

baseBranch

string

Branch to create worktree from (defaults to project’s default_branch)

customName

string

Custom worktree name (defaults to random name like “fuzzy-tiger”)

issueContext

object

GitHub issue context

Show Issue context properties

number

required

Issue number

title

string

required

Issue title

body

string

Issue description

prContext

object

GitHub PR context

Show PR context properties

number

required

PR number

title

string

required

PR title

headRefName

string

required

Source branch name

baseRefName

string

required

Target branch name

const worktree = await api.invoke('create_worktree', {
  projectId: '550e8400-e29b-41d4-a716-446655440000',
  baseBranch: 'main',
  issueContext: {
    number: 123,
    title: 'Add authentication',
    body: 'Implement JWT-based authentication'
  }
});

Delete Worktree

Delete a worktree (moves to archive).

worktreeId

string

required

ID of the worktree to delete

await api.invoke('delete_worktree', {
  worktreeId: '770e8400-e29b-41d4-a716-446655440002'
});

Archive Worktree

Archive a worktree without deleting files.

worktreeId

string

required

ID of the worktree to archive

await api.invoke('archive_worktree', {
  worktreeId: '770e8400-e29b-41d4-a716-446655440002'
});

Unarchive Worktree

Restore an archived worktree.

worktreeId

string

required

ID of the worktree to restore

const worktree = await api.invoke('unarchive_worktree', {
  worktreeId: '770e8400-e29b-41d4-a716-446655440002'
});

Rename Worktree

Rename a worktree and its branch.

worktreeId

string

required

ID of the worktree

newName

string

required

New worktree name

const worktree = await api.invoke('rename_worktree', {
  worktreeId: '770e8400-e29b-41d4-a716-446655440002',
  newName: 'auth-feature'
});

Update Worktree Label

Set or clear a worktree’s label.

worktreeId

string

required

ID of the worktree

label

object | null

required

Label object or null to clear

Show Label properties

name

string

required

Label text

color

string

required

Hex color code

await api.invoke('update_worktree_label', {
  worktreeId: '770e8400-e29b-41d4-a716-446655440002',
  label: {
    name: 'In Progress',
    color: '#3b82f6'
  }
});

// Clear label
await api.invoke('update_worktree_label', {
  worktreeId: '770e8400-e29b-41d4-a716-446655440002',
  label: null
});

Reorder Worktrees

Reorder worktrees within a project.

projectId

string

required

ID of the project

worktreeIds

string[]

required

Array of worktree IDs in the desired order

await api.invoke('reorder_worktrees', {
  projectId: '550e8400-e29b-41d4-a716-446655440000',
  worktreeIds: [
    '770e8400-e29b-41d4-a716-446655440002',
    '880e8400-e29b-41d4-a716-446655440003'
  ]
});

Git Operations

Fetch Worktrees Status

Update cached Git/GitHub status for all worktrees in a project.

projectId

string

required

ID of the project

await api.invoke('fetch_worktrees_status', {
  projectId: '550e8400-e29b-41d4-a716-446655440000'
});

Has Uncommitted Changes

Check if a worktree has uncommitted changes.

worktreeId

string

required

ID of the worktree

const hasChanges = await api.invoke('has_uncommitted_changes', {
  worktreeId: '770e8400-e29b-41d4-a716-446655440002'
});

Get Git Diff

Get the diff for a worktree.

worktreePath

string

required

Absolute path to the worktree

diffType

string

required

Type of diff: “working” | “staged” | “branch”

baseBranch

string

Base branch for branch diff

const diff = await api.invoke('get_git_diff', {
  worktreePath: '/Users/john/jean/my-app/fuzzy-tiger',
  diffType: 'working'
});

Git Pull

Pull changes from remote.

worktreePath

string

required

Absolute path to the worktree

baseBranch

string

required

Branch to pull from

remote

string

Remote name (defaults to “origin”)

const result = await api.invoke('git_pull', {
  worktreePath: '/Users/john/jean/my-app/fuzzy-tiger',
  baseBranch: 'main',
  remote: 'origin'
});

Git Push

Push changes to remote.

worktreePath

string

required

Absolute path to the worktree

prNumber

number

PR number (for updating PR)

remote

string

Remote name (defaults to “origin”)

const result = await api.invoke('git_push', {
  worktreePath: '/Users/john/jean/my-app/fuzzy-tiger',
  remote: 'origin'
});

Commit Changes

Create a Git commit.

worktreeId

string

required

ID of the worktree

message

string

required

Commit message

stageAll

boolean

default:false

Stage all changes before committing

const result = await api.invoke('commit_changes', {
  worktreeId: '770e8400-e29b-41d4-a716-446655440002',
  message: 'Add authentication system',
  stageAll: true
});

Pull Request Operations

Save Worktree PR

Associate a PR with a worktree.

worktreeId

string

required

ID of the worktree

prNumber

number

required

GitHub PR number

prUrl

string

required

GitHub PR URL

await api.invoke('save_worktree_pr', {
  worktreeId: '770e8400-e29b-41d4-a716-446655440002',
  prNumber: 456,
  prUrl: 'https://github.com/user/repo/pull/456'
});

Clear Worktree PR

Remove PR association from a worktree.

worktreeId

string

required

ID of the worktree

await api.invoke('clear_worktree_pr', {
  worktreeId: '770e8400-e29b-41d4-a716-446655440002'
});

Open Pull Request

Create a GitHub PR for a worktree.

worktreeId

string

required

ID of the worktree

title

string

PR title (auto-generated if omitted)

body

string

PR description (auto-generated if omitted)

draft

boolean

default:false

Create as draft PR

const result = await api.invoke('open_pull_request', {
  worktreeId: '770e8400-e29b-41d4-a716-446655440002',
  title: 'Add authentication system',
  body: 'Implements JWT-based authentication with refresh tokens',
  draft: false
});

Events

worktree:creating

Emitted when worktree creation starts (background operation).

{
  "type": "event",
  "event": "worktree:creating",
  "payload": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "project_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "fuzzy-tiger",
    "path": "/Users/john/jean/my-app/fuzzy-tiger",
    "branch": "fuzzy-tiger"
  }
}

worktree:created

Emitted when worktree creation completes successfully.

{
  "type": "event",
  "event": "worktree:created",
  "payload": {
    "worktree": { /* full worktree object */ }
  }
}

worktree:create_error

Emitted when worktree creation fails.

{
  "type": "event",
  "event": "worktree:create_error",
  "payload": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "project_id": "550e8400-e29b-41d4-a716-446655440000",
    "error": "Failed to create worktree: ..."
  }
}

worktree:status_updated

Emitted when cached Git/GitHub status is updated.

{
  "type": "event",
  "event": "worktree:status_updated",
  "payload": {
    "worktree_id": "770e8400-e29b-41d4-a716-446655440002",
    "cached_pr_status": "open",
    "cached_check_status": "success"
  }
}

Error Codes

Error	Description
`Worktree not found: {id}`	The specified worktree ID does not exist
`Worktree name already exists: {name}`	A worktree with this name already exists in the project
`Worktree path already exists: {path}`	The target path is already in use
`Branch already exists: {branch}`	The branch name is already in use
`No uncommitted changes to commit`	Cannot commit with no staged or unstaged changes
`Failed to create worktree: {reason}`	Git worktree creation failed

Overview

Endpoints

Worktrees API

Overview

Data Structures

Worktree

Cached Status Fields

Commands

List Worktrees

Get Worktree

Create Worktree

Delete Worktree

Archive Worktree

Unarchive Worktree

Rename Worktree

Update Worktree Label

Reorder Worktrees

Git Operations

Fetch Worktrees Status

Has Uncommitted Changes

Get Git Diff

Git Pull

Git Push

Commit Changes

Pull Request Operations

Save Worktree PR

Clear Worktree PR

Open Pull Request

Events

worktree:creating

worktree:created

worktree:create_error

worktree:status_updated

Error Codes

Next Steps

Sessions API

Chat API

Build docs developers (and LLMs) love

Overview

Endpoints

​Overview

​Data Structures

​Worktree

​Cached Status Fields

​Commands

​List Worktrees

​Get Worktree

​Create Worktree

​Delete Worktree

​Archive Worktree

​Unarchive Worktree

​Rename Worktree

​Update Worktree Label

​Reorder Worktrees

​Git Operations

​Fetch Worktrees Status

​Has Uncommitted Changes

​Get Git Diff

​Git Pull

​Git Push

​Commit Changes

​Pull Request Operations

​Save Worktree PR

​Clear Worktree PR

​Open Pull Request

​Events

​worktree:creating

​worktree:created

​worktree:create_error

​worktree:status_updated

​Error Codes

​Next Steps

Sessions API

Chat API

Build docs developers (and LLMs) love

Overview

Data Structures

Worktree

Cached Status Fields

Commands

List Worktrees

Get Worktree

Create Worktree

Delete Worktree

Archive Worktree

Unarchive Worktree

Rename Worktree

Update Worktree Label

Reorder Worktrees

Git Operations

Fetch Worktrees Status

Has Uncommitted Changes

Get Git Diff

Git Pull

Git Push

Commit Changes

Pull Request Operations

Save Worktree PR

Clear Worktree PR

Open Pull Request

Events

worktree:creating

worktree:created

worktree:create_error

worktree:status_updated

Error Codes

Next Steps