Physical Git Worktree Isolation

Developing directly on primary branches (main or master) or in a single shared working directory creates severe multi-agent concurrency risks:

Uncommitted edits from concurrent tasks get overwritten or cross-contaminated.
Branch switches abort background compilations or active test suites.
Half-finished experiments accidentally leak into tracking branches.

Physical Git worktrees resolve concurrency at the filesystem level. Each task or agent operates in an independent physical directory linked to the shared .git repository.

Standard worktree lifecycle

1. Provision a dedicated worktree

From the repository root:

# Create a new feature branch in an isolated worktree directory
git worktree add -b feat/<task-id> ../worktrees/<task-id> main
cd ../worktrees/<task-id>

2. Implement, verify, and commit

Inside the isolated worktree:

Make targeted changes.
Run local tests and deterministic formatters.

Stage changes and commit using conventional commit format:

git add <files>
git commit -m "feat(module): implement scoped capability"

3. Push and generate pull request

Push the branch to remote origin:

git push -u origin feat/<task-id>

Create the pull request via GitHub CLI using the WHAT-WHY-HOW-LEARNINGS template:

gh pr create \
  --title "feat(module): implement scoped capability" \
  --body-file docs/reports/<task-id>-telemetry.md \
  --base main \
  --head feat/<task-id>

4. Cleanup after merge

Once the PR is merged or the task is completed:

cd ../main-repo
git worktree remove ../worktrees/<task-id>

T3 Code managed worktrees

When operating within the T3 Code control plane, worktree provisioning, branch isolation, and diff tracking are handled natively per conversation thread. Use T3 Code's built-in PR tools (link_pull_request, list_thread_pull_requests) to associate PRs with the active task.

1.9 KiB Raw Blame History