An Agent per Worktree: Setup Guide

Managing multiple feature branches simultaneously often leads to cognitive overload and terminal clutter. The traditional method of switching branches within a single directory forces you to stash changes, rebuild dependencies, and restart dev servers. Implementing an agent per worktree setup offers a cleaner alternative. By combining Git worktrees with autonomous coding agents, you can maintain isolated environments for different tasks, allowing each agent to operate within its own specific context without interference.

The Logic Behind Git Worktrees

Git worktrees allow you to have multiple branches checked out at the same time in different directories. Unlike a standard clone, these directories share the same .git history, making them lightweight and fast to manage. When you work on a complex project, you might have a long-running feature branch, a quick bug fix, and a code review happening all at once.

Standard context switching involves git checkout commands that overwrite your current working files. If your project has a heavy build process, this switch might cost you several minutes of productivity. With a worktree, you simply move to a different folder. The files are already there, the environment is already built, and your progress is preserved exactly where you left it.

Why Assign an Agent per Worktree

The rise of AI coding agents like Claude Code or OpenCode changes how we interact with these directories. An agent works best when its context is narrow and focused. If you use a single agent instance and jump between tasks, the agent may struggle with stale file references or conflicting instructions from previous sessions.

By adopting an agent per worktree setup, you gain several advantages:

• Parallel execution: One agent can run a test suite in the background while you pair with another agent on a UI component.
• Context isolation: The agent only sees the files relevant to that specific branch or feature.
• Persistent memory: Each agent instance maintains its own command history and thought process relevant to the specific task.
• Resource management: You can allocate different LLM models to different tasks based on complexity.

Setting Up Your Environment

To begin, you need a project structure that supports multiple entry points. Instead of nesting worktrees inside your main repository, it is better to create a parent folder for the project and treat the main branch as one of several sibling directories.

1. Create a main project directory.
2. Clone your repository into a subdirectory called main.
3. Use the git worktree add ../feature-branch-name command to create a new directory for a specific task.
4. Open each directory in a separate instance of your preferred tool.

This structure prevents accidental nesting and makes it easier for scripts or automation tools to find the different environments. It also ensures that your IDE or coding agent does not accidentally scan the contents of other branches when performing a global search.

Implementing the Workflow in Deska

The canvas approach in Deska is particularly suited for managing an agent per worktree setup. Because Deska allows you to place panels anywhere on an infinite workspace, you can visually group your worktrees.

You might place a terminal, a code editor, and a coding agent for "Feature A" on the left side of your canvas. On the right side, you can have a similar cluster for "Bug Fix B". As you zoom out, you see the entire landscape of your current sprint. Each panel remains active, meaning you can watch two different agents work in real time.

Within Deska, you can run multiple coding agents such as Claude Code and OpenCode side by side. Each agent panel is scoped to the directory it was opened in. This ensures that when you ask an agent to refactor a function, it is looking at the correct version of the code in the correct worktree. You can manage these sessions using Ask Deska, the built-in assistant that helps you navigate between these active clusters or run specific commands across your workspace.

Monitoring Progress Remotely

A common challenge with long-running agent tasks is the need to stay at your desk. If an agent is performing a deep refactor in one of your worktrees, you can use the mobile app to keep track of the progress. Since Deska is local-first, your code stays on your machine, but the secure relay allows you to check the terminal output or the agent status from your phone.

This is helpful for worktree management because you can verify if a build passed or if an agent encountered an error while you are away from your workstation. You do not need to expose any ports or change your firewall settings, as the devices pair directly through a secure relay.

Comparison of Management Approaches

While tools like Tmux or standard IDE windows differ in approach, they often lack the persistent visual layout that a canvas provides. Traditional IDEs might struggle with running multiple language server instances for the same project in different branches, whereas isolated panels in a dedicated workspace maintain clear boundaries.

Frequently Asked Questions

How to manage multiple git worktrees effectively?

The most effective way is to use a dedicated parent directory for all worktrees of a project. Avoid adding worktrees inside the main repository folder. Use descriptive names for the directories that match the branch names to avoid confusion when navigating via the command line or a canvas interface.

Are AI coding agents compatible with git worktrees?

Yes, most agents operate on the file system level. As long as you point the agent to the specific path of the worktree, it will function normally. The primary benefit is that the agent will not be confused by files or changes existing in other branches, as the worktree provides a clean, isolated snapshot.

Can I run different LLMs for different worktrees?

Absolutely. You might use a more powerful, expensive model for a complex architectural change in one worktree while using a smaller, faster model for writing unit tests in another. This is easily managed by opening different agent panels and providing the respective API keys or using managed inference options.

Getting Started with Deska

If you are ready to organize your development environment with an agent per worktree setup, you can download the free desktop application for Mac, Windows, or Linux. The infinite canvas and support for multiple side-by-side agents provide the technical foundation needed to manage complex, parallel workflows without the typical friction of context switching. For more information on how to configure your first workspace, visit the getting started guide in our documentation.