Git Worktrees

Work on multiple tasks in parallel using Git worktrees — each task gets its own branch and working directory without switching branches in your main workspace.

What is a worktree?

A Git worktree is a separate checkout of your repository at a different branch. Instead of stashing work and switching branches, you open a second copy of your project alongside the first.

AgentKanban automates creating, opening, and cleaning up worktrees tied to your tasks. When you create a worktree for a task, the extension:

1. Creates a new Git branch (agentkanban/<directory-name>)
2. Checks out that branch into an adjacent directory
3. Writes the task binding files so the extension in the new window automatically loads the correct board, task, and agent context
4. Opens the worktree in a new VS Code window (optional)

Worktrees are entirely optional — you can work on tasks without them.

Prerequisites

• A Git repository (the workspace must be inside a Git working tree)
• An active task selected in the AgentKanban sidebar (see IDE Remote Mode)

Creating a worktree

From the sidebar

1. Select a task in the Active Task section of the AgentKanban sidebar
2. The Git Worktree section appears below the task with a pre-filled directory name in kebab-case (e.g. a task called "Add OAuth2 Support" suggests add-oauth2-support)
3. Edit the directory name if you prefer something different
4. Click Create Worktree
5. When prompted, click Open in VS Code to launch the worktree in a new window

From the command palette

1. Open the command palette (Ctrl+Shift+P / Cmd+Shift+P)
2. Run Agent Kanban: Create Worktree
3. Edit the suggested directory name and press Enter
4. When prompted, click Open in VS Code

Where worktrees are created

By default, worktrees are created in a sibling directory next to your workspace:

~/projects/my-app/                    ← your main workspace
~/projects/my-app-worktrees/          ← worktree root (auto-created)
    add-oauth2-support/               ← one worktree per task
    fix-login-redirect/

The root directory follows the pattern ../{repo}-worktrees where {repo} is your workspace folder name.

Customising the location

Change the agentKanban.worktreeRoot setting to use a different template:

{
    "agentKanban.worktreeRoot": "../{repo}-worktrees"
}

{repo} is replaced with the workspace folder name. Relative paths resolve from the workspace root. Absolute paths are used as-is.

Opening an existing worktree

When a worktree exists for the active task, the sidebar shows:

• The branch name
• The directory path
• Open in VS Code — opens the worktree in a new window
• Delete — removes the worktree and its branch

Click Open in VS Code to resume work. The new VS Code window will have the task already bound — your AI agent and conversation capture work exactly as if you had selected the task manually.

Deleting a worktree

From the sidebar

Click Delete in the worktree section and confirm the dialog.

From the command palette

Run Agent Kanban: Delete Worktree and confirm.

Deleting a worktree:

1. Removes the worktree directory (git worktree remove --force)
2. Deletes the associated branch (git branch -D)
3. Clears the worktree binding from the extension state

If the branch has been merged or deleted manually, the branch cleanup step is skipped silently.

How task context works in worktrees

When a worktree is created, the extension writes several files into the worktree's .agentkanban/ directory:

• AGENTS.md — the sentinel section that tells your AI agent to read the task instructions
• INSTRUCTION.md — the task binding with board ID, task ID, and workflow rules
• worktree-context.json — board and task IDs used by the extension to automatically select the correct board and task in the sidebar

When you open the worktree in VS Code, the extension reads these files on activation and:

1. Automatically sets the sidebar board and task selection to match the original task
2. Starts conversation capture for that task
3. Makes MCP tools and @kanban /resume available immediately

No manual task selection is needed — the worktree window is ready to work in as soon as it opens.

Tips

• One worktree per task. If you try to create a worktree when one already exists for that task, you'll be offered the option to open or delete the existing one.
• Stale cleanup. If you manually delete a worktree directory from disk, the extension clears the stale reference automatically on next activation.
• Branch naming. Branches are prefixed with agentkanban/ followed by the directory name you chose, e.g. agentkanban/add-oauth2-support.
• Main branch is unaffected. Creating a worktree never changes your current branch or working directory.