Worktrees

Git worktrees allow you to have multiple working directories from the same repository, each on a different branch. Autogit makes worktrees easy to manage and visualize.

Automatic Worktree Creation

When you start work from an issue using Smart PR (8), Autogit automatically creates a worktree for your new branch. This is the recommended workflow for multi-agent development.

Why Worktrees?

Parallel Development

Work on multiple features simultaneously without stashing or switching branches. Each worktree is an independent workspace with its own files.

Multi-Agent Development

Worktrees are essential for running multiple AI coding agents in parallel. Each agent operates in its own isolated workspace, preventing conflicts and allowing true concurrent development.

Clean Separation

• No merge conflicts between in-progress work
• Each worktree has its own node_modules, build artifacts, etc.
• Switch between tasks instantly

Managing Worktrees

Autogit displays worktrees in the status tab with PR status indicators:

Indicator	Meaning
Yellow dot	Draft PR open
Green dot	PR ready for review
No dot	No PR for this branch

Keyboard Shortcuts

Key	Action
Enter	Switch to selected worktree
Ctrl+W	Create new worktree
Ctrl+Shift+W	Delete worktree
Ctrl+Shift+P	Prune dead worktrees
i	Show worktree info

Worktree Location

Worktrees are created as siblings to your main repository:

~/projects/
├── my-app/              # Main worktree (main branch)
├── my-app-feature-1/    # Worktree for feature-1 branch
├── my-app-feature-2/    # Worktree for feature-2 branch
└── my-app-bugfix/       # Worktree for bugfix branch

---

Multi-Agent Development

Worktrees unlock the ability to run multiple AI coding agents simultaneously, each working on different issues without interfering with each other.

The Problem with Single Workspaces

When multiple agents share one workspace:

• File conflicts when agents edit the same files
• Unpredictable state as changes interleave
• Agents block each other waiting for file access
• Difficult to attribute changes to specific agents

The Worktree Solution

Each agent gets its own worktree:

• Complete isolation between agents
• No file locking or conflicts
• Parallel execution at full speed
• Clean git history per feature

---

Example: 3 Agents Working in Parallel

Imagine you have three issues to tackle:

• #42 - Add user authentication
• #43 - Implement dark mode
• #44 - Fix payment processing bug

Setup

Create three worktrees, one per issue:

~/projects/
├── my-app/           # Main repo
├── 42-auth/          # Agent 1: Claude Code
├── 43-dark-mode/     # Agent 2: Codex CLI
└── 44-payment-fix/   # Agent 3: OpenCode

Workflow

Step-by-Step

1. Create worktrees from issues (automatic)

   In Autogit on main, select issue #42 and press 8 (Smart PR). Autogit automatically:

   • Creates branch 42-add-user-authentication
   • Creates worktree at ~/projects/42-add-user-authentication/
   • Switches to the new worktree
   • Creates a draft PR linking to issue #42

   Repeat for issues #43 and #44. Each gets its own isolated workspace.

2. Launch agents in separate terminals

   # Terminal 1 - Claude Code on auth
   cd ~/projects/42-add-user-authentication
   claude "Implement user authentication per issue #42"
   
   # Terminal 2 - Codex on dark mode
   cd ~/projects/43-dark-mode
   codex "Add dark mode toggle per issue #43"
   
   # Terminal 3 - OpenCode on payment fix
   cd ~/projects/44-payment-fix
   opencode "Fix payment processing bug per issue #44"

3. Agents work in parallel

   Each agent:

   • Reads and writes files in its own worktree
   • Makes commits to its feature branch
   • Pushes to the draft PR
   • No conflicts with other agents

4. Review and merge

   As each agent completes:

   • Mark PR ready for review (press 8 in that worktree)
   • Review the PR
   • Merge to main
   • Delete the worktree

5. Monitor progress in Autogit

   The worktrees panel shows all active work:

   • Yellow dots = agents still working (draft PRs)
   • Green dots = ready for review
   • Switch between worktrees to check progress

Benefits

Benefit	Description
True parallelism	3 agents = 3x throughput (roughly)
No conflicts	Each agent has exclusive file access
Clean PRs	Each PR contains only relevant changes
Easy rollback	Delete worktree to abandon work
Visibility	Autogit shows all agent progress at a glance

---

Best Practices

For Multi-Agent Workflows

1. One issue per worktree - Keep work focused and isolated
2. Use draft PRs - Signals to other agents that work is in progress
3. Name worktrees by issue - Easy to track which agent is doing what
4. Prune regularly - Clean up merged worktrees with Ctrl+Shift+P

For Solo Development

1. Long-running tasks - Create worktree for refactors while fixing bugs on main
2. Code review - Check out PR branches in separate worktrees
3. Experiments - Try risky changes without affecting main work

---

Keyboard Reference

Action	Key	Context
Create worktree	Ctrl+W	Worktrees panel
Delete worktree	Ctrl+Shift+W	Worktrees panel
Prune worktrees	Ctrl+Shift+P	Worktrees panel
Switch worktree	Enter	Worktrees panel
Worktree info	i	Worktrees panel