feat: add --worktree flag for parallel session execution #2194

[jqueguiner]

Summary

Implement git worktree functionality similar to Claude Code. The --worktree flag creates isolated worktrees for running multiple Qwen Code sessions in parallel with complete file isolation.

Features

• Auto-generated or custom worktree names: Use --worktree for auto-generated names or --worktree feature-name for custom names
• Isolated working directories: Each session runs in its own worktree under .qwen/worktrees/
• Dedicated branches: Creates branch worktree/<name> for each worktree
• Git repository validation: Validates git repository before attempting worktree creation
• Proper error handling: Clear error messages and user feedback

Usage

# Auto-generated worktree name
qwen --worktree

# Custom worktree name
qwen --worktree feature-auth

# Multiple parallel sessions
qwen --worktree feature-a &
qwen --worktree feature-b &

Implementation Details

Files Changed

1. packages/cli/src/utils/worktree.ts (new) - Git worktree management utilities
2. packages/cli/src/config/config.ts - Added --worktree CLI flag
3. packages/cli/src/gemini.tsx - Integrated worktree setup in startup
4. packages/cli/src/gemini.test.tsx - Updated tests
5. docs/users/common-workflow.md - Documentation

How It Works

1. When --worktree flag is provided, Qwen Code:

   • Validates the current directory is a git repository
   • Creates a new worktree in .qwen/worktrees/<name>
   • Creates a new branch worktree/<name>
   • Changes the working directory to the worktree
   • Starts the session in the isolated environment

2. Each worktree has:

   • Independent file state
   • Shared git history
   • Isolated changes that don't affect other sessions

Related

#2194
Inspired by Claude Code's worktree implementation for parallel session execution.

[tanzhenxin]

@jqueguiner Thanks for your contribution, great work done here!
But we are undergoing a major refactor to underlying core system in PR #1912 , which includes a git worktree service builtin, so we would not take any PR targeting git worktree at this moment. The mentioned PR expects to be merged into main next week.