在AI工具中處理多個儲存庫的困境

Agentic Tooling Across Multiple Repositories in coding

Jan 10, 2026
• Ricky Smith

In my organization, we have a great number of repositories that contain overlapping logic. For example, to manage our large number of cloud environments, we have separate repositories just for Terraform. We've split up our code based on purpose and audience to better organize our work. However, this creates challenges when we need to make a change that spans multiple repositories. This challenge has always existed, but it was manageable when doing work manually – you can just open the multiple repositories in your editor of choice and have multiple terminal tabs open for working with git in each repository.

But as we lean into the use of agentic tooling (AI agents that can act on your behalf) to automate repetitive tasks – especially when we want those tools to perform broader changes that require context across multiple repositories – this becomes a bigger challenge. In this post I’ll walk through how I use git worktrees and a simple directory convention to give those agents the right context to work safely across many repos.

Organizing My Repositories

Before we get into the solution, let's take a look at how I organize my repositories locally. My usual setup is to place all of my repositories in a ~/projects directory structure, usually by organization, then by full project namespace that matches our remote repository.

So, you'd expect to see a structure like this on my laptop:

A High-Level Solution – Directory Structure with Git Worktrees

My idea was to use git worktrees to create a single directory structure that contains multiple repositories, all synced to the same branch name. This way, I can create a workspace for a specific task that requires context across multiple repositories. The branch-named parent directory provides a space for defining context for the task at hand and provides a workspace for agentic tooling without polluting the individual repositories.

Git Worktrees

Git worktrees let you create additional working directories for the same repository. Each worktree is tied to a branch and shares the same .git data, so you don’t need to reclone. Creating a worktree is fast and uses little disk space, and remote operations (fetch, pull, push) are shared across the main repo and all worktrees.

The common use case is when you need to quickly pivot to working on another problem/feature, but you have a lot of WIP stuff in your working directory. Most developers I know would go about stashing their changes or creating a "WIP" commit, then switching branches. With git worktrees, you can just create a new working directory for the branch you want to work on and leave your main working directory alone. It's very handy, but not a tool that most people reach for often (maybe not often enough).

Git Worktree Directory Structure

In my new scheme, I've started to create a directory structure that looks like ~/projects/worktrees/<branch-name>/<repository-name>.

So, if we think of a really broad task, like "scan all Terraform modules using Trivy and fix any issues found", I might create a worktree structure like this:

This has some really big benefits:

Giving Context

The big "aha" moment was that the parent directory (the branch name) provides a context for the task at hand. This is really powerful when using agentic tooling, because the tooling can be run from the parent directory, and it can operate on all repositories within that context. So far, I'm starting my tasks with two key files: AGENTS.md and PLAN.md.

The AGENTS.md file is already a well-known pattern for providing seed context for agentic tooling. By placing this file in the parent directory, I can give high-level information about the directory structure and instructions for the agents to read AGENTS.md files in each repository, and to reference the PLAN.md file for the overall plan.

In my PLAN.md file, I've found that providing a high-level outline of the steps, and a checklist of the steps to perform, helps the agent stay on track and also provides a way for the agent to keep track of progress. You're likely to pause the overall task execution to focus on a specific issue, to push changes and address CI/CD results, or if you need to reboot your computer. At any time, you can just tell your agent to "continue the plan" and it can pick up where it left off.

Shell Alias for Creating Worktrees

Now, one of the pain points of working with git worktrees is that the commands can be a bit verbose. To make it easier to create these worktree structures, I've created a few ZSH aliases that automate the process, especially focusing on this workflow.

This alias, wt-new, takes a branch name as an argument, creates the necessary directory structure, and sets up a new worktree for the current repository. It also copies any .envrc files from the source repository to the new worktree, ensuring that environment configurations are preserved.

The Real Magic

Now, if you're paying attention, you might think this is a pretty nice way to create a per-task structure, but there's some extra steps that REALLY turn this whole thing into pure magic.

With this directory layout in place, agentic tooling gets really interesting when you add a few conventions:

Demonstrating the Workflow

To demonstrate the workflow, let's say I want to create a new worktree for the branch scan-fix-trivy-issues for a few repositories, I would navigate to each repository and run wt-new scan-fix-trivy-issues.

Next, create my AGENTS.md and PLAN.md files in the scan-fix-trivy-issues directory to provide context for the task.

From there, I can just run my favorite AI tool (codex) in the parent directory and prompt it to Get started. It will read the AGENTS.md file by default, which tells it to read the PLAN.md file and follow the steps outlined there.

At some key points, I'll instruct the agent to push changes, which will cause it to create commits, push them to the remote repository, and create merge requests automatically and log them in the MERGE_REQUESTS.md file. I can tell it to Check the status of the merge request pipelines and it'll go off and look at the output of the CI/CD jobs and get to work on troubleshooting failures.

Early Results

I've only been using this workflow for a couple of days, but it's been extremely promising. There have been a few key moments where the agent has (rightly) indicated that it might cause an outage with a change and I've been able to pull in additional repositories (like our repositories that manage helm charts and environment-specific input values) to give it more context to make more "informed decisions".

I also very much like that I have given it a large sandbox where it can play safely. The worktrees are all created with a branch, so there's a low risk that I'll have the wrong branch checked out. I also don't have to worry about a lot of pending changes in my main working directories and it getting in the way of other work. In fact, I've found myself already setting up this context, setting the agent off to do work, and then I'll switch my focus to something else in the main working directory. As someone who has been very hesitant to relinquish control to AI tools, this has been a really nice way to reap the benefits while still having some confidence that it's not going to make a huge mess.

(A human wrote this blog post, but GPT-5.1 was used for editing assistance. Use of emdashes was a human choice. 😄)

Ricky Smith

Staff Software Engineer at Cisco