Run parallel Claude Code sessions with Git worktrees

Two agents in one checkout can change the same files or see each other’s unfinished work. They can also change the branch during an ongoing task. A second chat window alone does not separate those files. Worktree execution gives a thread its own working files; Local execution intentionally uses the workspace checkout.

This guide focuses on that execution choice in Aiola. For the broader choice between terminal sessions and a desktop manager, read the multiple Claude Code sessions guide. Neither arrangement removes the need to inspect changes and decide how they should reach the shared branch.

In a new thread, use the composer’s Project or new worktree control. Select the provider and model, then the branch or worktree base using the available branch controls. A draft becomes a thread when you send its first message. Existing threads keep their workspace and execution context; context-defining choices can lock after work starts.

Use Local for a focused change in your open checkout. That can help when the task depends on edits you are reviewing there. Use Worktree for independent changes that should proceed concurrently on separate branches. Do not assume your uncommitted Local edits are available in a separate checkout. Check the starting files before asking the agent to implement anything.

For example, open a repository workspace and prepare two threads. Improve an empty-state message in one and repair a validation rule in the other. Select Claude Code for each and choose Worktree for both. Give each thread a clear base branch and a distinct scope so the resulting diffs can be reviewed independently.

Ask the first thread to change only the empty state and its relevant checks. Ask the second to reproduce the invalid-input case, explain the cause, and propose the smallest correction with a regression check. These are example prompts, not automatic Aiola steps. Keep shared configuration changes out of both tasks unless you deliberately assign ownership.

If you use Tasks instead of drafting chat directly, set the task’s Local or Worktree run mode. Project Settings → Tasks supplies the default for new tasks, and an individual task can override it. Moving a task to In Progress starts its configured workflow.

Open the thread’s Review panel and inspect the changed files before committing. Confirm that the branch matches the intended task and that the diff contains no unrelated edits. Run the project’s relevant checks in that thread’s checkout. A successful Local test does not establish that another worktree passes.

Keep the terminal, browser, and chat visible while reviewing. Terminals supports persistent Split and Canvas arrangements. Split can place panes horizontally or vertically; Canvas can retain terminal, browser, chat, file, and image cards. These layouts help organize review, but their positions do not determine a thread’s execution mode.

Stage and commit the intended changes, push the branch, and prepare a pull request through the connected GitHub workflow. Check the PR diff and checks before merging. Workspace Settings → Git records the repository remote and branch prefix used when an AI workflow creates a branch.

For board-driven work, Human Review and Create PR are separate task statuses. Moving a task to Create PR starts PR creation. The auto-create-PR setting can route successful tasks there instead of Human Review. Decide whether that setting fits your review process. Creating a PR still leaves the integration decision with the reviewer.

App Log, Feedback, and GitHub issue actions have their own worktree toggles in Git settings. Those settings govern those action flows; they do not mean every manually created thread automatically receives a worktree.

Separate working files can still produce conflicting changes when branches are combined. Merge one reviewed change at a time. Update remaining branches against the new base as appropriate, then rerun affected checks. Worktree isolation does not isolate shared databases, network services, provider quotas, or external writes made by commands.

After integrating a PR, check the branch for uncommitted work you still need. Then remove its worktree through your normal Git cleanup process. Preserve useful changes first. This is a recommended review habit, not a promise of automatic cleanup. The execution and task controls described here follow the Tasks documentation and Git settings documentation.