All articles

AI development

Claude Code Agent Teams and Git Worktrees

Use Claude Code agent teams and Git worktrees for independently scoped tasks, with clear ownership, review and measured usage.

By , Founder, Luminous Digital Visions
Published · Updated

A team meeting around laptops
Illustrative photograph from the original article, sourced from Unsplash.

Introduction

This is it. Part 5 of the Claude Code Mastery Series. We have covered the fundamentals, full-stack development workflows, advanced configuration with hooks and MCP servers, and security at the enterprise level. Now we go into the features that push Claude Code beyond a single-developer tool and into something that operates more like a development team.

The features in this article are the newest and most experimental in Claude Code's arsenal. Agent Teams lets you coordinate multiple Claude Code instances that communicate with each other. Git worktrees give each instance an isolated environment so they do not step on each other's work. Background tasks keep long-running processes alive while you continue working. And the higher-capability Claude models available in Claude Code bring the reasoning depth that makes these parallel workflows practical rather than chaotic.

At Luminous Digital Visions, we started using these features on a client project that required simultaneous changes to a React frontend, a Node.js API, and a shared component library. Three Claude Code instances running in three worktrees, coordinating through the Agent Teams protocol. What would have taken a single developer three days took half a day with parallel agents. That is not a theoretical number. We measured it.

What You Will Learn

  • Agent Teams: the experimental multi-agent coordination system
  • Git worktrees for isolated parallel development
  • Model selection strategies and when to use faster versus more capable models
  • Background tasks with tmux integration
  • Real-world parallel development workflows
  • A full recap of the Claude Code Mastery Series

A Note on Experimental Features

Agent Teams launched as an experimental feature in early 2026. It requires an environment flag to enable. The API and behavior may change. That said, the core concept (multiple Claude Code instances coordinating on a shared goal) is stable enough for real work if you understand the tradeoffs.

Info: This article covers features that are only available in Claude Code's terminal interface, invoked with the claude command. Some features require specific environment variables or flags to enable.

Delegate bounded work with clear ownership

Agent teams coordinate multiple Claude Code sessions. Check the current team documentation for availability, configuration and limitations in your installation.

Choose work that can progress independently, such as investigating separate subsystems or reviewing a defined implementation. State the inputs, owned files, expected output and acceptance criteria for each task. If every task depends on the same uncertain decision, resolve that decision first.

Give one person or lead session responsibility for integration. Multiple useful outputs do not automatically form a working application. Review conflicts, run the combined checks and verify the customer workflow after changes are merged.

Git Worktrees

When multiple Claude Code instances work simultaneously, they need isolated file systems. If two agents edit the same file at the same time in the same working directory, you get conflicts and corruption. Git worktrees solve this by giving each agent its own copy of the repository with its own branch and working directory, all sharing the same git history.

What Git Worktrees Are

A git worktree is an additional working directory attached to your repository. Each worktree has its own branch, its own file state, and its own index. Changes in one worktree do not affect another until you merge branches. This is different from git clone, which creates an entirely separate repository. Worktrees share the .git directory, so they are fast to create and use minimal disk space.

Using Worktrees with Claude Code

Claude Code supports worktrees natively with the --worktree or -w flag:

claude --worktree

This creates a new worktree inside .claude/worktrees/ with a fresh branch based on your current HEAD. Claude Code switches its working directory to the new worktree automatically. When the session ends, you are prompted to keep or remove the worktree.

You can also name the worktree for clarity:

claude -w --worktree-name feature-notifications

Running Multiple Instances

Open three terminal windows. In each one, start Claude Code with a worktree:

Terminal 1 — Frontend work:

claude -w
# "Build the notification bell component and dropdown panel"

Terminal 2 — Backend work:

claude -w
# "Create the WebSocket server and notification REST API"

Terminal 3 — Test suite:

claude -w
# "Write comprehensive tests for the notification system"

Each instance works on its own branch in its own directory. There are no file conflicts. When all three are done, you merge the branches, either manually or with Claude Code's help:

claude "Merge the branches from all three worktrees: feature-notifications-frontend, feature-notifications-backend, and feature-notifications-tests. Resolve any conflicts, preferring the more recent changes. Run the full test suite after merging."

Managing Worktrees

List active worktrees:

git worktree list

Remove a worktree when you are done:

git worktree remove .claude/worktrees/feature-notifications

Prune stale worktree references:

git worktree prune
Warning: Do not manually delete a worktree directory. Always use git worktree remove to ensure git cleans up its internal references properly. Manually deleting the directory leaves orphaned metadata that can cause confusing errors later.

Select models using the task and available access

Choose from the models available in the installed product and account. Compare reasoning quality, latency and total usage on the type of work you need. Do not assume a model name in an older tutorial still identifies the preferred or available choice.

A small code-reading task and a difficult architecture change may need different levels of capability. Keep the task bounded and verify the output regardless of model choice. Estimate the total work across all sessions when evaluating cost.

Background Tasks

Development workflows often involve long-running processes: test suites that take minutes, builds that compile slowly, deployment scripts that wait for provisioning. Background tasks let you kick off these processes and continue working while they run.

How Background Tasks Work

Claude Code integrates with tmux to manage background processes. When you ask Claude Code to run a long process, it can execute it in a tmux session that persists even if you close your terminal or start a new Claude Code session.

Starting a Background Task

Run the full E2E test suite in the background. It takes about 8 minutes. Let me know when it finishes and show me the results.

Claude Code starts the test suite in a tmux session and continues the conversation. When the tests complete, it reports the results.

Managing Background Tasks

You can check on running background tasks, view their output, or stop them:

What background tasks are currently running?
Show me the output from the E2E tests background task.

Disabling Background Tasks

If you prefer not to use background tasks, set the environment variable:

export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=true

This forces all tasks to run in the foreground, which means Claude Code waits for each process to complete before continuing.

Practical Uses

  • Run tests while implementing the next feature — Start the test suite for your current work, then move on to the next task. Review results when they arrive.
  • Build in the background — Kick off a production build while you work on documentation or README updates.
  • Deploy while continuing — Start a deployment and continue fixing other issues. Check the deployment status periodically.
  • Run database migrations — Start a migration in the background and continue development work that does not depend on the migration completing.
Tip: Background tasks work best when the task is independent of your current work. Do not run a migration in the background and then try to query the new tables before the migration finishes. That creates race conditions that are hard to debug.

Parallel Development Workflows

Now let us put it all together. The real power of Claude Code's advanced features comes from combining Agent Teams, git worktrees, model selection, and background tasks into cohesive workflows.

Workflow 1: Full-Stack Feature Development

You need to build a complete user dashboard with analytics, settings management, and a notification system.

Step 1: Create three worktrees.

# Terminal 1
claude -w
# "You are the frontend developer. Build the dashboard UI with React components:
# analytics charts, settings page with form validation, notification panel.
# Use Tailwind CSS. Follow the patterns in our existing components."

# Terminal 2
claude -w
# "You are the backend developer. Create API routes for dashboard analytics data,
# user settings CRUD, and notification endpoints. Use Express with Zod validation.
# Follow our controller/service pattern."

# Terminal 3
claude -w
# "You are the test engineer. Write tests for the dashboard feature.
# Unit tests for services, integration tests for API routes,
# E2E tests for the dashboard UI with Playwright."

Step 2: Let all three work simultaneously. Each agent works on its own branch without conflicts.

Step 3: Merge and integrate.

claude "Merge all three feature branches into a single dashboard-feature branch. Resolve conflicts. Run the full test suite. Fix any failures."

Workflow 2: Large-Scale Refactor

You need to migrate from a custom authentication system to Auth.js across a 200-file codebase.

Step 1: Use Agent Teams with a coordinated plan.

Enable Agent Teams. I need to migrate from our custom auth to Auth.js.

Lead: You coordinate the migration plan and handle the core auth configuration.

Teammate 1: Migrate all API route auth checks to use Auth.js session verification.
Teammate 2: Migrate all frontend components that use auth context to use Auth.js hooks.
Teammate 3: Update all tests to work with the new auth system.

Start by having all teammates agree on the Auth.js configuration, session shape, and the migration approach before making any changes.

Step 2: The lead creates the plan. Teammates discuss and agree on the session shape. Then each teammate works through their area of the codebase.

Step 3: Merge, test, and validate.

Workflow 3: Code Review Pipeline

For a critical pull request that needs thorough review before merge:

Step 1: One Claude Code instance performs a security review.

claude -p "Perform a security audit of the changes in this PR compared to the main branch. Focus on auth, input validation, and data exposure."

Step 2: Another instance reviews code quality.

claude -p "Review the code quality of changes in this PR. Check architecture, patterns, error handling, type safety, and test coverage."

Step 3: A third instance runs the full test suite in the background.

All three run in parallel. You get a thorough review in the time it would take to do just one of these manually.

Workflow 4: Monorepo Multi-Package Development

In a monorepo with shared packages, changes often cascade. A type change in the shared package breaks consumers.

# Worktree 1: Shared types package
claude -w
# "Update the User type in packages/shared-types to include a 'preferences' field.
# Update all exports and ensure backward compatibility."

# Worktree 2: Backend consumer
claude -w
# "Update the backend to use the new User type with preferences.
# Add API endpoints for reading and updating preferences."

# Worktree 3: Frontend consumer
claude -w
# "Update the frontend to use the new User type with preferences.
# Add a preferences page to the settings section."

Real-World Examples

Theory is fine, but let us look at concrete scenarios where these features paid off.

Example: E-Commerce Platform Overhaul

A client needed to add a product recommendation engine, update the checkout flow, and migrate their database schema, all within a two-week sprint. We used three Claude Code instances in worktrees:

  1. Recommendations agent — Built the recommendation API using collaborative filtering, connected it to the product catalog, and created the UI widgets.
  2. Checkout agent — Redesigned the checkout flow with address validation, tax calculation, and Stripe integration updates.
  3. Migration agent — Handled the Prisma schema migration, data backfill scripts, and backward-compatible API changes.

Each agent worked on its branch. We merged daily, ran the test suite, and resolved conflicts incrementally. The sprint finished three days ahead of schedule.

Example: Open-Source Library Maintenance

Maintaining an open-source library means handling bug reports, feature requests, and dependency updates simultaneously. We set up a workflow where:

  • A security-focused Claude Code instance triages new issues and identifies security-relevant reports
  • A development instance works on the highest-priority bug fix
  • A review instance checks incoming pull requests

This does not replace human judgment. But it means that when we sit down to review, the initial triage is done, the bug fix has a draft implementation, and the PR review has preliminary feedback ready for us to verify.

Example: Legacy Codebase Modernization

Converting a JavaScript codebase to TypeScript across 300 files. We split the codebase into three sections by directory and assigned one Claude Code instance to each section. Each instance:

  1. Added TypeScript types to files
  2. Fixed type errors introduced by strict mode
  3. Updated tests to work with typed code
  4. Ran the test suite for its section

The parallel approach cut the migration time from an estimated week to two days.

Info: In our experience at Luminous Digital Visions, and as we have seen building projects through our development environment setup guide, the biggest productivity gains from parallel workflows come from reducing context-switching overhead. A single developer jumping between frontend, backend, and test code loses time at every switch. Three focused agents, each holding the full context of their domain, work without that penalty.

Keep the delivery record reproducible

Record the task, relevant constraints, changed files and checks performed. Review the final diff, not only the assistant’s summary. A clean build does not establish that authorization, data migrations or customer workflows are correct.

Use a preview or test environment to exercise the affected behavior. Preserve the existing runtime and dependency versions unless an upgrade is part of the task. When a change affects data, include a recovery plan and verify it on a copy before release.

Frequently Asked Questions

Agent Teams launched as experimental in early 2026 and requires the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS environment flag (check Anthropic's current documentation to confirm the flag name has not changed). The core functionality works, but the coordination protocol may evolve. Use it for development and testing workflows. Do not build mission-critical automation on top of the Agent Teams API until it graduates from experimental status.

There is no hard limit defined in the protocol, but practical limits exist. Each teammate is a separate Claude Code instance that consumes API tokens and system resources. Two to four teammates is the practical range for most workflows. Beyond four, coordination overhead often exceeds the parallel processing benefit.

Yes. Git worktrees are a core git feature available on all platforms. Claude Code's --worktree flag works on macOS, Linux, and Windows via WSL. On native Windows, git worktrees work but Claude Code itself requires WSL.

Teammates communicate through messages, not shared file access. If a teammate needs a file that another teammate created, it requests it through the communication protocol. This is by design. It prevents file conflicts and keeps each teammate's working directory clean.

Claude Code captures the exit code and output of background tasks. When a background task fails, Claude Code reports the failure and includes the error output so you can diagnose the issue. You can then ask Claude Code to fix the problem and rerun the task.

Use Agent Teams when the tasks are interdependent and teammates need to coordinate — like building a frontend and backend that must agree on an API contract. Use manual worktrees when the tasks are fully independent — like working on three separate bug fixes that do not interact.

Yes. Each Claude Code instance in a worktree is independent. You can start one with the most capable model available to you for complex work and another with a faster model for straightforward tasks. Use the --model flag when starting Claude Code, then pick from the models available in your account.

Each instance consumes API tokens independently. Running three instances in parallel costs roughly three times as much as running one instance for the same duration. However, if the parallel approach completes the work in one-third the time, the total cost is roughly equivalent. The real savings are in developer time, not API cost.

Yes. The larger context window means each teammate can hold more of the codebase in memory, which reduces the need for context switching and file re-reading. This makes each teammate more effective and reduces the total number of tool calls needed to complete a task.

Git worktrees are a standard git feature that works with any tool. You could have Claude Code in one worktree and another AI tool in a different worktree. Agent Teams is specific to Claude Code.

Each teammate consumes its own context and model usage, and coordination adds work. Measure the cost of a representative team session instead of assuming a fixed multiplier. Use teams when tasks can proceed independently and the benefit justifies the additional review.

If a teammate process crashes or encounters an unrecoverable error, the lead agent is notified through the coordination protocol. The work completed by that teammate before the crash is preserved in its worktree. You can restart the failed teammate manually in a new terminal, or ask the lead agent to redistribute the incomplete work to one of the remaining teammates. Always commit intermediate progress from each worktree so no work is lost.

After teammates finish their work, merge their branches into a single integration branch. If conflicts arise, use Claude Code to resolve them: "Merge feature-backend into feature-integration and resolve all conflicts. For conflicting imports, keep both. For conflicting logic, prefer the more complete implementation and ensure tests pass." Claude Code understands both sides of the conflict and can make informed merge decisions. Always run the full test suite after merging.

Yes. Unlike subagents which only report to the main agent, teammates in Agent Teams communicate directly with each other. If the frontend teammate discovers that the API response format needs to change, it can tell the backend teammate directly rather than routing the message through the lead. This direct communication is what makes Agent Teams suitable for interdependent work where decisions in one area affect another.

Debugging Agent Teams requires monitoring multiple Claude Code instances. Keep each teammate in a visible terminal window so you can observe their progress. If something goes wrong, check the specific teammate's terminal output for errors. You can also ask the lead agent for a status update on all teammates. For complex debugging, pause the problematic teammate and investigate its worktree state manually using git diff and git log in the worktree directory.

Yes. You can assign a dedicated test teammate that runs tests while other teammates continue development. The test teammate watches for changes (either by polling or by receiving messages from other teammates) and runs relevant test suites. This mirrors how a CI system works, but runs locally with faster feedback. For large test suites, you can split tests across multiple test teammates — one for unit tests, one for integration tests, one for e2e tests.

The most effective patterns mirror real team structures. Common specializations include: frontend teammate (UI components, styling, client-side state), backend teammate (API routes, business logic, database queries), test teammate (writing and running tests), and infrastructure teammate (Docker, CI/CD, deployment configs). For large refactors, specialize by codebase area instead — one teammate per package or module. Avoid having teammates with overlapping scope, as that creates merge conflicts.

Git worktrees share the .git directory with the main repository, so they only consume space for the working directory files, not a second copy of the git history. For a project with 100MB of source files, each worktree adds roughly 100MB. Node modules are not shared between worktrees, so if each worktree runs npm install, add the node_modules size per worktree. Use du -sh .claude/worktrees/* to check actual disk usage. Clean up old worktrees with git worktree remove when done.

Agent Teams is designed for local development workflows, not CI/CD. In CI, use individual Claude Code instances running in non-interactive mode (claude -p "prompt") for specific tasks like security review or code quality checks. If you need parallel CI tasks, use your CI platform's native parallelism (GitHub Actions matrix strategies, parallel jobs) with separate Claude Code invocations in each job.

In practice, two to four teammates is the productive range. Beyond four teammates, several factors create diminishing returns: coordination overhead increases because more teammates need to agree on shared interfaces, merge conflicts become more likely, API token consumption grows linearly, and the lead agent's context fills up tracking more teammates. If your task needs more than four parallel workers, break it into sequential phases instead, each phase using two to three teammates.

When you set up a team, instruct teammates to agree on shared interfaces before starting implementation. The lead agent coordinates this initial agreement. For example, a frontend and backend teammate might first agree on the API endpoint shapes, response formats, and error codes. Once agreed, each teammate implements their side independently. If a teammate needs to change the contract, it communicates the change to affected teammates through the direct messaging protocol.

Use descriptive, prefixed branch names that indicate the purpose and scope: feature/notifications-frontend, feature/notifications-backend, feature/notifications-tests. This makes it easy to identify which worktree produced which branch when merging. Claude Code's --worktree-name flag controls the worktree directory name but not the branch name — you can set the branch name by instructing Claude Code: "Create a new branch named feature/notifications-backend and work on it."

Each background task runs in a tmux session that you can attach to. List all tmux sessions with tmux list-sessions to see what is running. Attach to a specific session to check output. You can also ask any active Claude Code instance "What background tasks are currently running?" and it will check for you. For a centralized view, create a monitoring terminal that periodically polls tmux sessions and displays their status.

Use a PostToolUse hook in your project's .claude/settings.json that logs all tool invocations to a shared log file. Since each teammate runs in its own worktree but shares the same project configuration, the hook runs in every teammate. Direct the logs to an absolute path outside the worktrees (like /tmp/agent-team-session.log) so all teammates write to the same file. Include the worktree name or branch in each log entry to distinguish which teammate performed each action.

Conclusion

This is the end of the Claude Code Mastery Series. Over five articles, we have gone from installation to coordinated multi-agent development workflows.

Series Recap

Part 1: The Complete Claude Code Guide — Installation, authentication, basic usage in terminal and Cursor IDE. The foundation that everything else builds on.

Part 2: Claude Code for Full-Stack Development — Project scaffolding, frontend and backend development, database integration with Prisma, testing at every level, and deployment to production.

Part 3: Advanced Claude Code — Hooks, MCP, and Custom Commands — CLAUDE.md project configuration, the hooks system with PreToolUse and PostToolUse events, MCP server integration for external tools, custom slash commands, and all built-in commands.

Part 4: Claude Code Security and Enterprise Workflows — Claude Code Security announcement, security scanning workflows, CI/CD integration with GitHub Actions, enterprise deployment patterns, security best practices for AI-generated code, and the permission model.

Part 5: Agent Teams and Parallel Development — Experimental Agent Teams for multi-agent coordination, git worktrees for isolated parallel work, model selection strategies, background tasks, and real-world workflow patterns.

Where Claude Code is Headed

Claude Code is evolving rapidly. Agent Teams is experimental today but points toward a future where AI development tools operate more like coordinated teams than individual assistants. The 1M token context window expands what is possible in a single session. Claude Code Security brings defensive capabilities that were previously only available through expensive manual security audits.

The developers and teams who invest in learning these tools deeply (the hooks, the MCP integrations, the custom commands, the parallel workflows, beyond the basics) will have a significant productivity advantage over those who treat AI as a simple autocomplete.

From Our Team to Yours

At Luminous Digital Visions, we have been using Claude Code on every project since it launched. The series you just read reflects what we have learned from real client work: what works, what to watch out for, and where the tool shines brightest. Our goal was not to write a manual. It was to share practical experience that helps you ship better software, faster.

Thank you for reading the entire series. We hope it saves you real time on real projects.

Work With Us

Whether you are building your first application or scaling a platform to millions of users, Luminous Digital Visions provides end-to-end development, AI integration, and consulting services. We practice what we preach. Every technique in this series is part of our daily workflow.

  • Custom application development — Full-stack web and mobile applications
  • AI integration and automation — Claude Code setup, custom MCP servers, workflow automation
  • Security auditing — Code review, vulnerability assessment, and compliance consulting
  • Team training — Get your engineering team productive with AI-assisted development

Get a Free Consultation

The future of software development is not AI replacing developers. It is developers who know how to use AI tools effectively building circles around those who do not. You now have the knowledge. Go build something great.