Worktrees API

Create and manage Git worktrees for isolated development

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

id · 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

Request

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

Request

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 · number · required

Issue number

title · string · required

Issue title

body · string

Issue description

prContext · object

GitHub PR context

Show PR context properties

number · number · required

PR number

title · string · required

PR title

headRefName · string · required

Source branch name

baseRefName · string · required

Target branch name

Request

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

Request

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

Request

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

Request

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

Request

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

Request

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

Request

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

Request

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

Request

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

Request

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”)

Request

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”)

Request

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

Request

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

Request

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

Request

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

Request

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

Next Steps

Sessions API

Manage chat sessions within worktrees

Chat API

Send messages and interact with AI