Add --worktree flag to enable isolated parallel Qwen Code sessions using Git worktrees

[jqueguiner]

What happened?

Description

Running multiple Qwen Code sessions in the same repository currently causes conflicts because all sessions operate on the same working directory and file state.

This issue proposes adding a --worktree flag that creates isolated Git worktrees for each session, allowing developers to run multiple Qwen Code instances in parallel without interfering with each other.

The implementation is inspired by Claude Code's worktree-based parallel session model.

Motivation

When developers run multiple AI-assisted coding sessions simultaneously, they often want each session to modify files independently.

Without isolation:

• Sessions overwrite each other's changes
• File state becomes inconsistent
• Experiments across multiple features become difficult

Using Git worktrees allows:

• Shared git history
• Fully isolated file states
• Parallel development workflows

Proposed Solution

Introduce a CLI flag:

--worktree [name]

When enabled, Qwen Code will automatically create and use a Git worktree for the session.

Behavior

1. Validate the current directory is a Git repository
2. Create a worktree under:

.qwen/worktrees/<name>

3. Create a branch:

worktree/<name>

4. Change the process working directory to the new worktree
5. Start the Qwen Code session inside the isolated environment

Worktree naming

Two modes are supported:

Auto-generated name

qwen --worktree

Example generated worktree:

.qwen/worktrees/session-17482

Custom name

qwen --worktree feature-auth

Worktree path:

.qwen/worktrees/feature-auth

Branch:

worktree/feature-auth

Usage Examples

Single isolated session

qwen --worktree feature-auth

Auto-generated session

qwen --worktree

Multiple parallel sessions

qwen --worktree feature-a &
qwen --worktree feature-b &

Each session runs in its own independent working directory.

Features

• Auto-generated or custom worktree names
• Isolated working directories
• Dedicated branch per worktree
• Git repository validation
• Clear error handling and user feedback

Expected Outcome

Developers will be able to run multiple Qwen Code sessions concurrently, each operating on a fully isolated workspace while sharing the same Git repository history.

What did you expect to happen?

NA

Client information

NA

Login information

NA

Anything else we need to know?

NA

[m13v]

We use parallel Claude Code sessions in worktrees heavily and can confirm this pattern is essential for multi-agent workflows. A few implementation notes from experience.

The worktree naming scheme matters more than you might think. Auto-generated names like session-17482 are fine for throwaway work, but for anything that might need debugging later, include the task description in the name. We use agent-<short-description>-<timestamp> so it is easy to find the right worktree when something goes wrong.

For the .qwen/worktrees/ location - be careful putting worktrees inside the repo. File watchers (VSCode, IDE indexers, build tools watching for changes) will pick up modifications in nested worktrees and trigger unnecessary rebuilds or re-indexes. We recommend putting worktrees outside the repo entirely, like in ~/.qwen/worktrees/<repo-hash>/ or /tmp/qwen-worktrees/.

On the branch creation: using HEAD as the base is correct for most cases, but for feature work you often want the worktree branching from the latest main/master. We always do git fetch origin main && git worktree add -b <branch> <path> origin/main to make sure the agent starts from a clean, up-to-date base.

Cleanup is critical. Without automatic cleanup, worktrees accumulate fast. We run a cleanup sweep on session exit: if the worktree branch was merged (via PR or direct merge), delete both the worktree and the branch. If it was not merged, keep it for 24 hours then auto-delete with a warning.

[m13v]

Our orchestrator that manages parallel agent sessions with worktree creation, naming, and lifecycle: https://github.com/m13v/tmux-background-agents/blob/main/SKILL.md

And for shared resource contention between parallel worktree sessions (e.g., browser, ports): https://github.com/m13v/browser-lock/blob/main/playwright-lock.sh

[DragonnZhang]

Thanks for the suggestion!
We agree that this would be a useful feature, and we plan to add support for it in the future.

[m13v]

awesome, looking forward to it. the worktree naming convention is worth thinking about early - we use the task/branch name as the worktree dir name so it's easy to find which worktree belongs to which agent. also worth considering auto-cleanup of stale worktrees, they pile up fast