Claude Code for Parallel Development 🔥
※This is an English translation of this article.
Introduction
Hello! I'm Masataka Mayuzumi, the CTO at OCT-PATH, Inc.. (My X profile is here: @masataka_net)
Are you using "Claude Code," the AI coding assistant from Anthropic?
Claude's ability to tenaciously see complex, time-consuming tasks through to the end is truly amazing, isn't it? I benefit from it every single day.
As I was working with Claude, a thought suddenly struck me.
"This feature I'm building now... couldn't I get Claude to handle that bug fix over there and this refactoring over here, all at the same time...?"
I wanted to execute multiple tasks in parallel, as if I had three brilliant assistants. But I was about to give up, thinking it would be too difficult with the hassle of switching branches in the same repository (project folder).
However, it turns out the answer was hiding in plain sight. When I reread the official Claude Code tutorial... the method was written right there (lol). Man, you should always read the official documentation, seriously.
So today, based on this officially recommended method, I'm going to share a special technique for running multiple tasks simultaneously in the same repository!
Lately, I've been hearing that even non-engineers are enjoying "vibes coding" using tools like Cursor and Claude Code. So, in this article, I'll introduce a method that can be done entirely with a GUI (clicking around on the screen), so even those who aren't comfortable with command-line operations in a black terminal window have nothing to worry about!
Today's Star: What is "Git Worktree"?
The key to this method is a feature called "Git Worktree."
Many of you might be thinking, "What's that?" Simply put, it's a standard Git feature that lets you "create separate folders on your PC for different branches of a single repository."
Normally, when you develop a new feature, you switch branches with a command like git checkout -b feature/new-task, but you're still working within the same folder.
With Git Worktree, you can physically separate folders for each branch. For example, the main branch could be in the my-project folder, the feature-a branch in the my-project-feature-a folder, and so on.
To be honest, I knew this feature existed, but I never really understood its true value, wondering, "When would I ever use this...?" However, in this modern era of co-developing with AI assistants like Claude Code, I feel that the time has come for Git Worktree to truly shine.
How to Use It (It's Easy with a GUI!)
By default, you use Git Worktree with a command like this:
git worktree add ../my-project-feature -b feature-branch develop
In this example, it creates a folder named my-project-feature one level above the my-project folder and checks out the contents of a new branch named feature-branch, which is based on the develop branch, into that new folder.
git worktree add [①Folder Path] [②Branch Option] [③Base Branch]
↓ ↓ ↓
../my-project-feature -b feature-branch develop
If you're thinking, "Ugh, commands are still a bit much..." don't worry!
If you install the following extension in VSCode (or Cursor, WindSurf, etc.), you can do everything with UI operations.
-
Git Worktree Manager
https://marketplace.visualstudio.com/items?itemName=jackiotyu.git-worktree-manager
This extension is very simple but has all the worktree management functions you need.
(Easy operations from the VSCode UI)
- Check the current state of your worktrees
- Create a new worktree
- Delete unneeded worktrees
...and more, all can be done intuitively with a few clicks. It's incredibly convenient, so I highly recommend installing it!
What Does the Directory Structure Look Like?
So, you might be curious how this magical feature actually works.
The answer is very simple: the folders are just physically separated. So easy to understand!
# Original Project
/Users/username/my-project/
├── .git/
├── src/
├── package.json
└── README.md
# After creating a worktree
/Users/username/
├── my-project/ # Main worktree (e.g., main branch)
│ ├── .git/ # The actual Git repository itself is here
│ ├── src/
│ └── package.json
├── my-project-feature-a/ # New physical folder (feature-a branch)
│ ├── .git # A file with link info to the .git/worktrees above
│ ├── src/ # Files for the feature-a branch
│ └── package.json # Files for the feature-a branch
└── my-project-bugfix/ # Another physical folder (bugfix branch)
├── .git # A similar file
├── src/ # Files for the bugfix branch
└── package.json # Files for the bugfix branch
The main Git repository (the .git folder) remains in one place in the original location. The newly created folders contain a "file" named .git which holds the information to reference that main repository. It's a simple but very well-designed system.
Open Each Branch in VSCode! The Ultimate Parallel Development Environment is Complete
What does it mean if the folders are physically separate...?
That's right! You can open each folder in a separate VSCode (or Cursor) window!
(Imagine something like this, where you can work on one task per window!)
This enables a dream-like fully parallel development workflow:
- Window A: Let Claude handle the task on the
feature-abranch - Window B: Have Claude work on the fix in the
bugfixbranch - Window C: You personally organize code on the
refactorbranch
Both Claude Code and Cursor are designed to run in parallel, creating a situation where it feels like multiple brilliant engineers are working on your PC at the same time.
Of course, you need to be mindful of API rate limits (usage limits in a short period) and credit consumption, but even with those considerations, there's no doubt that your development efficiency will dramatically improve.
🤖 6 Tips for Successful Concurrent Parallel Development
Now, here are some concrete tips for running your parallel development smoothly.
1. Keep Your Environment Setup Simple
Even when you create a new folder with Worktree, things like Node.js packages (node_modules) are not shared. Therefore, you need to set up the environment again in each folder.
cd ../my-project-feature-a
npm install
To minimize this effort, it's best to avoid complex environment setups and aim for a simple configuration from the get-go.
Ideally, it should be as easy as running npm install and copying over a .env.local (environment variable file).
There's also the issue of what to do with local databases. For example, if you're running Supabase with Docker, you can stand up one container locally and have all your Worktrees use it in common.
2. Prepare a Markdown File for Instructions
It's a pain to type out long instructions in the chat every time you give Claude a task.
That's why I strongly recommend preparing a Markdown file for task instructions.
First, if you place a file named CLAUDE.md in the root of your project, Claude will recognize the rules written there as common instructions. You should place this in your main branch to be shared.
Furthermore, for each task (Worktree), create an instruction file like ISSUE.md. (You'll want to exclude these from Git's tracking, so add ISSUE.md to your .gitignore.)
Then, all you have to do is tell Claude this:
Understand the requirements in
ISSUE.mdand implement them perfectly.
If you detail what you want implemented, what needs fixing, and any rules to follow in this ISSUE.md, Claude will execute it faithfully.
3. Simultaneous Debugging is Possible by Separating Ports
If you're developing a web app with Next.js or React, you need to run a development server. You can run multiple servers at the same time by assigning them different port numbers.
Terminal in Window A (feature-a):
npm run dev -- --port 3000
Terminal in Window B (bugfix):
npm run dev -- --port 3001
Terminal in Window C (refactor):
npm run dev -- --port 3002
Now you can check the behavior of each branch simultaneously at http://localhost:3000, http://localhost:3001, and http://localhost:3002. Of course, you need to be careful not to get confused yourself (lol).
4. Avoid Development Environment Confusion with "Peacock"
When you have three or four VSCode (or Cursor) windows open, it's easy to get confused and think, "Wait, which task is this window for?"
There's an amazing extension that solves this problem in one fell swoop.
Once you install this extension, you can simply open the command palette (Cmd+Shift+P), choose "Peacock: Change to a Favorite Color," and it will color the frame of your VSCode window.
(Example of setting the color to red)
- Feature Addition (Red)
- Bug Fix (Blue)
- Refactoring (Green)
By color-coding your windows based on the task type, you can intuitively know which task you're working on just by glancing at the window. It's very simple, but the effect is huge!
5. Reliably Receive Completion Notifications
When you delegate a long-running task to Claude, it can be hard to know when it's finished.
The official documentation describes a method using OS notifications, but in my environment (Mac + Cursor), it didn't always work reliably.
So, as a more reliable method, I recommend adding the following rule to your CLAUDE.md (common instructions).
【IMPORTANT】
When all tasks are complete, **always, as the very last step**, execute the following command in the terminal.
```bash
echo -e "\a"
```
This command simply plays the terminal's "bell" sound. By having Claude run this every time, it will notify you of task completion with an audible alert. It's primitive, but highly effective!
6. How to Reduce the Risk of Conflicts
The biggest unavoidable challenge in parallel development is conflicts.
While it's difficult to eliminate conflicts entirely, there are tips to minimize the risk.
- Break tasks into smaller pieces: If feature A and feature B are likely to modify the same file, making the decision not to develop them simultaneously is also important. Tasks delegated to the AI should be broken down into small, specific units so that the scope of change is as limited as possible.
-
Pull in
mainfrequently: Once a task is completed and merged into themainbranch, immediately incorporate those changes into your other work-in-progress branches (rebaseormerge). If you resolve conflicts while the changes are still small, the AI is more likely to handle a "please resolve the conflicts" instruction successfully.
"Small Task → Develop → Frequent Rebase → Immediate Merge"
By running this fast cycle, you prevent each branch from diverging too far from the main branch, which in turn helps you avoid major conflicts.
In Conclusion
Today, I introduced a hyper-efficient parallel development technique combining Git Worktree and Claude Code.
Using this method, you can have a development experience unlike any other, as if you were working alongside a team of brilliant engineers. You can delegate tedious tasks and time-consuming implementations to Claude, allowing you to focus on more creative and essential problem-solving.
Of course, you might be a little hesitant at first, but I encourage you to give it a try using the tips introduced in this article. It might just be the catalyst that revolutionizes your development style and the very concept of "engineering" as a job.
I hope your development becomes more fun and more powerful.
Happy Hacking!!🐙
Finally, please allow me to promote our services a little 🙏
AI & Web3 Development Services
Our company, OCT-PATH, provides high-quality, fast-turnaround development services by leveraging cutting-edge AI technology. We have extensive experience and expertise, especially in the AI and Web3 domains, and we strongly support our clients' digital transformation.
If your company is interested in our services, please feel free to contact us through our company website.
NeoTechPark Community Collaboration
Our engineer community, "NeoTechPark," is home to many talented young Indonesian engineers who actively exchange technical knowledge.
We are currently actively promoting initiatives to discover talent and foster technical exchange by holding joint hackathons with corporate partners. We can plan and manage events focused on developing solutions using the latest AI technologies, including the creation of AI agents, which have been gaining a lot of attention lately.
If your company is interested in collaborating with global talent or putting next-generation AI technology into practice, we would be delighted to hear from you.
For inquiries and consultations, please contact us via our company website.
Discussion