Home › Agent workflows › Parallel agents with git worktrees CLAUDE.md

Parallel agents with git worktrees CLAUDE.md

CLAUDE.md conventions for running several coding agents in parallel with git worktrees, task scoping, and safe merging.

Claude Code (CLAUDE.md)Agent workflows

Copy CLAUDE.md

How to use

Save this as CLAUDE.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

Note: Review and test before use. Provided as is, without warranty. See Terms.

# CLAUDE.md: Parallel agent sessions

Several agent sessions may work on this repo at once. Each one follows these rules.

## Isolation
- One task per session, in its own git worktree and branch:
  `git worktree add ../<repo>-<task> -b agent/<task> main`
- Never edit files in another session's worktree or switch branches in the main checkout.
- Install dependencies per worktree; don't share `node_modules`/virtualenvs across them.
- Use a unique port and database/schema per worktree (e.g. `PORT=31<NN>`, `DATABASE_URL=...<task>`), configured in that worktree's `.env.local`.

## Scope
- Stay inside the task's described files/modules. If you need to change shared code (configs, schema, shared components), stop and report it, because another session may be touching it.
- Keep diffs small and focused so they merge cleanly.

## Coordination
- Write progress in `notes/<task>.md` in your worktree: goal, decisions, status, and anything other sessions should know.
- Rebase on `main` before finishing (`git fetch && git rebase origin/main`), rerun tests, and resolve conflicts carefully. Don't force-push shared branches.

## Finish
- All tests, lint, and typecheck pass in your worktree.
- Summarize the branch, files changed, and merge notes. Don't merge into `main` yourself unless asked.
- Cleanup (when told): `git worktree remove ../<repo>-<task>`.