Git Worktrees

Kangentic uses git worktrees to give each agent an isolated copy of your repository. This lets multiple agents work on different tasks simultaneously without stepping on each other’s changes.

What Are Git Worktrees?

A git worktree is a linked working copy of your repository that shares the same .git directory. Each worktree can have a different branch checked out, so multiple branches can be worked on at the same time without cloning the repo multiple times.

How Kangentic Uses Worktrees

When an agent is spawned for a task with worktrees enabled, Kangentic:

1. Creates a new branch from the configured base branch (e.g., fix-websocket-a1b2c3d4)
2. Creates a worktree in .kangentic/worktrees/{slug}-{id}/ inside your project
3. Launches the agent in the worktree directory

The agent makes all its changes in the worktree. Your main working directory is never touched.

Per-Task Toggle

Each task has a Main / Worktree toggle that overrides the global worktree setting. Use this when you want a specific task to run directly in your main working directory (e.g., a quick config change) while keeping worktrees enabled for everything else.

Set this when creating a task or in the task detail dialog.

Branch Naming

Auto-generated branch names depend on whether the task’s base branch matches the project default:

<task-slug>-<8-char-id>
<flattened-base-branch>/<task-slug>-<8-char-id>

When the base branch equals the project default (e.g., both main), the name is plain:

• fix-websocket-a1b2c3d4
• add-user-auth-d4e5f678

When the base branch differs from the default, it is encoded as a namespace prefix (any / in the base is flattened to -), so git branch and GitHub’s branch list group work by base:

• base release/1.2 + default main produces release-1.2/fix-regression-g7h8i9j0
• base bugfix/inacc-adjustments + default main produces bugfix-inacc-adjustments/task-title-ab12cd34

The 8-character ID prevents collisions when tasks have similar titles. The resolved base branch is also shown in the task detail dialog so you can confirm what the worktree branched from without leaving the app.

Base Branch

The branch each worktree is created from follows a priority order:

1. Task’s base branch — per-task override set in the task creation dialog
2. Action config’s base branch — per-transition override
3. Global defaultBaseBranch — project or global setting (default: main)

Worktree Lifecycle

Caution

Understanding what happens to worktrees during task transitions is important to avoid losing work.

Task Action	Session	Worktree	Branch
Move to active column	Spawns/resumes	Created (if new)	Created (if new)
Move to Backlog	Killed	Kept (code stays on disk)	Kept
Move to Done / Archive	Suspended	Kept (code stays on disk)	Kept
Delete task	Killed	Removed	Removed

Moving a task to Backlog or Done does not delete the worktree — your code stays on disk. Only deleting the task removes the worktree, branch, and session data.

Reviewing Changes

When an agent completes its task, review the changes before merging:

# See what the agent changed
git diff main..fix-websocket-a1b2c3d4

# Merge when satisfied
git merge fix-websocket-a1b2c3d4

Working with Worktrees Manually

Since Kangentic uses standard git worktrees, you can interact with them using normal git commands:

# List all worktrees
git worktree list

# Navigate to a worktree
cd .kangentic/worktrees/fix-websocket-a1b2c3d4/

Tip

Kangentic stores worktree metadata in its database, so if you remove a worktree manually, the UI will detect the change and update accordingly.

PR Auto-Detection

When an agent runs gh pr create or gh pr view in a worktree session, Kangentic automatically detects the PR URL from the terminal output and links it to the task. You can also link PRs manually using the kangentic_update_task MCP tool from within an agent session.