ctx-worktree

name	ctx-worktree
description	Manage git worktrees for parallel agent development. Use when splitting work across independent task tracks.

Manage git worktrees to parallelize agent work across independent task tracks. Supports creating, listing, and tearing down worktrees with ctx-aware guardrails.

When to Use

• User wants to parallelize a backlog across multiple agents
• Multiple independent task tracks with non-overlapping files
• User says "create worktree", "let's parallelize", "split the work"
• 3+ independent tasks that can be worked concurrently

When NOT to Use

• Single task or tightly coupled tasks
• Tasks that touch overlapping files (high merge conflict risk)
• Fewer than 3 independent tasks (overhead exceeds benefit)
• Already inside a worktree (manage from the main checkout only)
• User just wants concurrent Claude Code sessions in the same tree

Operations

create <name>

Create a new worktree as a sibling directory with a work/ branch.

Process:

1. Check count: refuse if 4 worktrees already exist:

   git worktree list
   

   Count lines. If >= 5 (1 main + 4 worktrees), stop and explain the limit.

2. Determine project name from the current directory basename:

   basename "$(git rev-parse --show-toplevel)"
   

3. Create the worktree as a sibling directory:

   git worktree add "../<project>-<name>" -b "work/<name>"
   

4. Verify the worktree was created:

   ls "../<project>-<name>"
   

5. Remind the user:

   Do NOT run ctx init in the worktree. The context directory is already tracked in git and will be present. Launch a separate Claude Code session there and work normally.

list

Show all active worktrees:

git worktree list

teardown <name>

Merge a completed worktree back and clean up.

Process:

1. Check for uncommitted changes in the worktree:

   git -C "../<project>-<name>" status --porcelain
   

   If output is non-empty, warn and stop. The user must commit or discard changes first.

2. Merge the work branch into the current branch:

   git merge "work/<name>"
   

   If there are conflicts, stop and help the user resolve them. TASKS.md conflicts are common: see guidance below.

3. Remove the worktree:

   git worktree remove "../<project>-<name>"
   

4. Delete the branch:

   git branch -d "work/<name>"
   

5. Verify cleanup:

   git worktree list
   git branch | grep "work/<name>"
   

Guardrails

• Max 4 worktrees: more than 4 parallel tracks makes merge complexity outweigh productivity gains
• Sibling directories only: worktrees go in ../<project>-<name>, never inside the project tree
• work/ branch prefix: all worktree branches use work/<name> for easy identification and cleanup
• No ctx init in worktrees: the context directory is tracked in git; running init would overwrite shared context files
• Manage from main checkout only: create and teardown worktrees from the main working tree, not from inside a worktree
• TASKS.md conflict resolution: when merging, TASKS.md will often conflict because multiple agents marked different tasks as complete. Resolution: accept all [x] completions from both sides. No task should go from [x] back to [ ].

What Works Differently in Worktrees

The encryption key lives at ~/.ctx/.ctx.key (user-level, outside the project). All worktrees on the same machine share this path, so ctx pad and ctx hook notify work in worktrees automatically.

One thing to watch:

• Journal enrichment: ctx journal import and journal enrichment resolve paths relative to the current working directory. Files created in a worktree stay in that worktree and are discarded on teardown. Enrich journals on the main branch after merging: the JSONL session logs are intact regardless.

Task Grouping Guidance

Before creating worktrees, analyze the backlog to group tasks into non-overlapping tracks:

1. Read TASKS.md and identify all pending tasks
2. Estimate blast radius: which files/directories does each task touch?
3. Group by non-overlapping directories: tasks that touch the same package or file must go in the same track
4. Present the grouping to the user before creating worktrees:

Proposed worktree groups:

  work/docs     : recipe updates, blog post, getting started guide
                  (touches: docs/)
  work/crypto   : P3.1-P3.3 encrypted scratchpad infra
                  (touches: internal/crypto/, internal/config/)
  work/pad-cli  : P3.4-P3.9 pad CLI commands
                  (touches: internal/cli/pad/)

Let the user approve or adjust before proceeding.

Quality Checklist

Before any operation, verify:

• Worktree count checked (max 4)
• Branch uses work/ prefix
• Worktree is a sibling directory (../)
• User reminded not to run ctx init in worktree
• Uncommitted changes checked before teardown
• Merge completed before worktree removal
• Branch deleted after worktree removal