Multi-Repo Feature Folders with Git Worktrees and Claude Code

You’re working on a feature that spans three repositories. A shared library, a backend service, and a frontend app. You clone the first repo, start making changes, then realize the backend needs an API update too. So you open another terminal, clone another repo, and start context-switching between them.

Now multiply that by a team of AI coding agents, each capable of working independently. The question becomes: how do you give each agent its own isolated workspace across multiple repos, let them work in parallel, and tear everything down when the feature ships?

The answer is a pattern I call feature folders — a directory that groups git worktrees from multiple repositories under a single feature name, combined with Claude Code’s agent teams to orchestrate parallel work across all of them.

The Problem with Polyrepo Development

Most organizations beyond a certain size run a polyrepo architecture. Each service, library, and application lives in its own repository with its own CI pipeline, its own release cadence, and its own team.

This works well for autonomy. It works poorly for cross-cutting changes.

When a feature requires coordinated modifications across three repositories, you’re looking at three separate branches, three separate PRs, and a careful ordering of merges to avoid breaking the dependency chain. GitHub’s own Well-Architected guidance acknowledges this friction and recommends patterns like change sets, manifest-based composition, and integration repos to manage it.

Benchmark data from Faros AI across 320 scrum teams shows that polyrepo environments achieve median PR cycle times of 2 hours compared to 19 hours in monorepos — but that speed advantage disappears when a single feature touches multiple repos simultaneously. The coordination overhead eats the gains.

The symlink hack — cloning repos side by side and symlinking them into one project — partially solves the visibility problem. Your editor can see all the code. But it doesn’t solve isolation. You’re still working on one branch per repo, and you can only drive one feature at a time.

Git Worktrees: The Foundation

Git worktrees let you check out multiple branches of the same repository simultaneously, each in its own directory, sharing a single .git object database. Instead of stashing your work, switching branches, and praying you remember which stash belongs where, you just open a new directory.

git worktree add ../my-repo-feature-x -b feature-x

This creates a new working directory at ../my-repo-feature-x, checked out to a fresh feature-x branch. The original repo and this worktree share history, remotes, and objects. Fetch once, and both see the update.

The key advantages over multiple clones:

Single .git folder — no duplicate object databases eating disk space
Shared fetch — git fetch in one worktree updates all of them
Branch isolation — each worktree is locked to its own branch, preventing accidental cross-contamination
Instant cleanup — git worktree remove deletes the directory and unlocks the branch

Worktrees have been stable since Git 2.5 (2015). There’s nothing experimental about them.

The Feature Folder Pattern

Here’s the core idea: for every cross-repo feature, create a top-level directory that contains a worktree from each repository involved.

~/features/
  PROJ-123-user-auth/
    shared-lib/          ← worktree of github.com/org/shared-lib, branch feature/PROJ-123
    api-service/         ← worktree of github.com/org/api-service, branch feature/PROJ-123
    web-app/             ← worktree of github.com/org/web-app, branch feature/PROJ-123
    CLAUDE.md            ← project context for Claude Code agents

Each subdirectory is a fully functional git worktree with its own branch, its own working files, and its own commit history. But they’re all co-located under a single feature name, making it trivial to open the entire feature in one editor window or hand it to an AI agent that can see all the pieces.

Setting Up a Feature Folder

The setup is a shell script. Here’s the workflow:

#!/bin/bash
FEATURE_NAME="$1"
FEATURE_DIR="$HOME/features/$FEATURE_NAME"
REPOS_DIR="$HOME/repos"

REPOS=(
  "shared-lib"
  "api-service"
  "web-app"
)

mkdir -p "$FEATURE_DIR"

for repo in "${REPOS[@]}"; do
  if [ ! -d "$REPOS_DIR/$repo/.git" ]; then
    echo "Cloning $repo..."
    git clone "git@github.com:org/$repo.git" "$REPOS_DIR/$repo"
  fi

  echo "Creating worktree for $repo..."
  cd "$REPOS_DIR/$repo"
  git fetch origin
  git worktree add "$FEATURE_DIR/$repo" -b "feature/$FEATURE_NAME"
  cd -
done

echo "Feature folder ready at $FEATURE_DIR"

This script does three things:

Ensures the bare repos exist — clones them if they don’t
Creates a worktree per repo — each gets its own feature branch
Groups them under one directory — the feature folder

You run it once: ./feature-setup.sh PROJ-123-user-auth. Now you have an isolated workspace for this feature across all three repos.

Tearing Down

When the feature is done and all PRs are merged:

#!/bin/bash
FEATURE_NAME="$1"
FEATURE_DIR="$HOME/features/$FEATURE_NAME"
REPOS_DIR="$HOME/repos"

REPOS=(
  "shared-lib"
  "api-service"
  "web-app"
)

for repo in "${REPOS[@]}"; do
  echo "Removing worktree for $repo..."
  cd "$REPOS_DIR/$repo"
  git worktree remove "$FEATURE_DIR/$repo" --force
  git branch -d "feature/$FEATURE_NAME" 2>/dev/null
  cd -
done

rm -rf "$FEATURE_DIR"
echo "Feature folder cleaned up."

Clean removal. The worktree directories disappear, the feature branches are deleted, and the base repos remain untouched. No orphaned branches, no leftover directories.

Bringing in Claude Code

A feature folder is useful on its own. It becomes powerful when you combine it with Claude Code’s ability to run parallel sessions.

Single-Agent Approach: Worktree Flag

Claude Code has a built-in --worktree flag that creates isolated worktree sessions:

claude --worktree feature-auth

This creates a worktree at .claude/worktrees/feature-auth/ with its own branch. But this works within a single repository. For multi-repo work, you’d cd into each worktree inside the feature folder and start a separate Claude session:

# Terminal 1
cd ~/features/PROJ-123-user-auth/shared-lib
claude

# Terminal 2
cd ~/features/PROJ-123-user-auth/api-service
claude

# Terminal 3
cd ~/features/PROJ-123-user-auth/web-app
claude

Three independent Claude sessions, each with full context of its own repo, all working on the same feature. You can give each one specific instructions and they won’t interfere with each other.

Multi-Agent Approach: Agent Teams

Claude Code’s agent teams (experimental, as of March 2026) take this further. Instead of manually managing three terminals, you can have a single lead agent coordinate teammates across all three repos.

Enable agent teams first:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Then start Claude from the feature folder root with a CLAUDE.md that describes the project structure:

# Feature: PROJ-123 User Auth

## Repositories

- `shared-lib/` — Shared TypeScript library with auth types and validation
- `api-service/` — Go backend service, handles JWT issuance and verification
- `web-app/` — React frontend, login/signup flows

## Task

Implement OAuth2 PKCE flow across all three repos.
The shared lib defines the types, the API service implements the
token exchange, and the web app handles the redirect callback.

Ask Claude to create a team:

Create an agent team with three teammates. One for each repository
in this feature folder. Each teammate should work in its own
repository directory. Coordinate the implementation order:
shared-lib first, then api-service, then web-app.

The lead agent creates a shared task list, spawns teammates, and coordinates the dependency order. Each teammate operates in its own context window with full access to its repo.

Generating PRs

Once each agent has committed its changes, generating PRs is straightforward. Each worktree is a standard git repository with its own branch. You can either:

Ask each agent to create a PR using the gh CLI:

cd ~/features/PROJ-123-user-auth/shared-lib
gh pr create --title "feat: add OAuth2 PKCE types" \
  --body "Part of PROJ-123. Adds TypeScript types for PKCE flow."

Let Claude handle it — Claude Code can run gh pr create as part of its workflow. Tell the lead agent “create PRs for all repositories” and it will delegate to each teammate.
Use --remote for async PR creation — fire off remote sessions for each repo and let them run:

claude --remote "Create a PR for the changes in shared-lib. Title: feat: add OAuth2 PKCE types"
claude --remote "Create a PR for the changes in api-service. Title: feat: implement PKCE token exchange"
claude --remote "Create a PR for the changes in web-app. Title: feat: add PKCE login flow"

All three run simultaneously. Monitor from your phone or terminal with /tasks.

The Complete Lifecycle

Here’s the full workflow from feature inception to teardown:

1. Create the feature folder

./feature-setup.sh PROJ-123-user-auth

2. Add project context

Create a CLAUDE.md at the feature folder root describing the repos, the feature, and the implementation plan.

3. Start Claude agents

Either manually (three terminals) or via agent teams from the feature folder root.

4. Implement, commit, iterate

Each agent works in its own worktree. Changes are isolated. Commits are on feature branches. No interference between repos.

5. Generate PRs

Each agent creates a PR in its own repo using gh pr create. The PRs can reference each other in their descriptions for reviewers to understand the dependency chain.

6. Review and merge

Review PRs in dependency order: shared-lib first, then api-service, then web-app. Merge each one as it’s approved.

7. Tear down

./feature-teardown.sh PROJ-123-user-auth

Worktrees removed. Feature branches deleted. Clean state.

Practical Considerations

Port conflicts. If multiple agents need to run dev servers, each needs its own port. Set PORT=3001, PORT=3002, etc. in each worktree’s environment.

Dependency installation. Each worktree needs its own node_modules (or equivalent). Include npm install / go mod download in your setup script or Claude’s CLAUDE.md instructions.

Token costs. Agent teams use 3-7x more tokens than a single session. For a three-repo feature with three teammates, expect roughly 3x the normal token usage. Research and review tasks are good starting points before committing to full parallel implementation.

File conflict prevention. The beauty of this pattern is that each agent owns a separate repo, so file conflicts between agents are impossible. Within a single repo, if you use subagent worktrees, Claude handles isolation automatically with isolation: worktree.

Hooks for automation. Claude Code supports WorktreeCreate and WorktreeRemove hooks. Use these to automatically install dependencies, copy .env files, or run setup scripts when worktrees are created or destroyed.

Existing tooling. Several open-source tools automate worktree management with lifecycle hooks: wt-cli supports template variables and setup/teardown hooks, wtree (Rust) offers hooks.toml configuration, and worktree-make is purpose-built for multi-repo branch organization. Any of these can replace the shell scripts above if you want more features.

When This Pattern Makes Sense

This isn’t for every project. It shines when:

A feature genuinely spans 2+ repositories that can’t easily be merged into a monorepo
You’re using AI coding agents that benefit from isolated, parallel workspaces
Your team already follows a polyrepo architecture and isn’t going to change
The coordination cost of cross-repo changes is a recurring bottleneck

If your repos are all in a monorepo, you don’t need feature folders — just use branches. If your cross-repo changes are rare one-offs, the setup overhead isn’t worth it. But if you regularly ship features that touch a shared library and two or three consumers, this pattern pays for itself quickly.

The combination of git worktrees and AI agent teams transforms polyrepo development from a coordination headache into a parallelizable workflow. The worktrees provide isolation. The feature folder provides structure. Claude Code provides the agents. And the teardown script makes sure nothing is left behind.

The future of multi-repo development isn’t switching back to monorepos. It’s making polyrepo workflows feel as atomic as monorepo ones — with AI agents doing the heavy lifting across the boundaries.

Sources:

Luis Mori Guerra

Recent Articles

Topics