Skip to main content

​
Worktree Workflows

Git worktrees let you have multiple branches checked out simultaneously in different folders. Combined with Cline CLI’s --cwd flag, this enables powerful parallel development workflows and isolated experimentation.
New to Git worktrees? See our comprehensive Worktrees guide for the full concept explanation, VS Code integration, and best practices.

​
Quick Worktree Setup

If you haven’t used Git worktrees before, here’s the essentials: 
# Create a new worktree in ~/worktree-a on branch feature-a
git worktree add ~/worktree-a -b feature-a

# Create another worktree for a different feature
git worktree add ~/worktree-b -b feature-b

# List all worktrees
git worktree list

# Remove a worktree when done
git worktree remove ~/worktree-a
Each worktree is a separate folder with its own branch checked out. They all share the same Git history and .git directory, but have independent working directories.

​
The --cwd Flag

The -c, --cwd <path> flag tells Cline to run in a specific directory without changing your current location: 
# Run Cline in a different directory
cline --cwd ~/worktree-a -y "refactor the authentication code"

# Short form
cline -c ~/worktree-b -y "add unit tests"
This is the key to worktree workflows—you can run multiple Cline instances in different worktrees simultaneously from a single terminal.

​
Pattern 1: Parallel Task Execution

Run different tasks in parallel across multiple worktrees. Each task works on a separate branch in complete isolation.

​
Example: Parallel Feature Development

# Terminal 1: Update docs in worktree-a
cline --cwd ~/worktree-a -y "read the last 10 changes using git show and update our README with them" &

# Terminal 2: TypeScript migration in worktree-b
cline --cwd ~/worktree-b -y "update the index.js to use typescript" &

# Terminal 3: Refactoring in worktree-c
cline --cwd ~/worktree-c -y "refactor the cli/ folder to be more modular" &

# Wait for all to complete
wait
The & runs each command in the background, allowing all three to execute simultaneously.

​
When to Use Parallel Execution

Perfect for:
  • Multiple independent features
  • Bulk refactoring across different modules
  • Running tests in one worktree while developing in another
  • Trying multiple approaches to the same problem
Not ideal for:
  • Tasks that modify the same files (merge conflicts likely)
  • Tasks that depend on each other’s results
  • When you need to monitor progress closely

​
Pattern 2: Cross-Worktree Context Piping

Pipe output from one worktree as input to another. Use when a task in one worktree needs context from attempts in another worktree.

​
Example: Learning from Failures

# Try approach A in worktree-a, capture only the failure summary
cline --cwd ~/worktree-a -y \
  "edit the index.ts to be better and then npm run. if it fails, output ONLY the failure summary. nothing else but the failure summary" \
  | cline --cwd ~/worktree-b -y \
  "i've tried to edit the index.ts in a different worktree but it failed. use a different approach for this work tree"
How it works:
  1. First Cline instance runs in worktree-a, attempts a change, tests it
  2. If it fails, outputs just the failure summary
  3. That summary is piped to a second Cline instance in worktree-b
  4. Second instance sees the failure and tries a different approach

​
When to Use Context Piping

Perfect for:
  • A/B testing different solutions
  • Learning from failed attempts
  • Iterative refinement (try → analyze → try differently)
  • Comparing outputs across approaches
Not ideal for:
  • Simple tasks that don’t need cross-context
  • When both worktrees would succeed independently
  • Real-time collaboration (use parallel execution instead)

​
Combining with Other CLI Features

​
Different Models Per Worktree

Use --config to run different models in different worktrees: 
# Cheap model for simple docs update
cline --cwd ~/worktree-docs --config ~/.cline-haiku -y \
  "update README with latest changes"

# Expensive model for complex refactoring
cline --cwd ~/worktree-refactor --config ~/.cline-opus --thinking -y \
  "refactor authentication system for better security"
This optimizes costs while maintaining quality where it matters.

​
Task Isolation

Keep long-running worktree sessions isolated by running each task against a different worktree path: 
# Run tasks in dedicated worktrees
cline --cwd ~/worktree-a -y "long-running task"
cline --cwd ~/worktree-b -y "another task"
Each worktree has its own Git branch and working directory, so task history and changes stay separated without needing instance management.

​
With YOLO Mode

The -y (YOLO) flag is essential for worktree workflows: 
# Without -y: Opens interactive chat (blocks other tasks)
cline --cwd ~/worktree-a "refactor code"

# With -y: Runs autonomously (doesn't block)
cline --cwd ~/worktree-a -y "refactor code" &
For parallel execution, always use -y to avoid blocking on user approval.

​
Real-World Workflow Example

Here’s a complete workflow showing how these patterns work together: 
# Setup: Create three worktrees
git worktree add ~/cline-worktrees/feature-auth -b feature/authentication
git worktree add ~/cline-worktrees/feature-api -b feature/api-endpoints
git worktree add ~/cline-worktrees/fix-tests -b fix/failing-tests

# Pattern 1: Run parallel independent tasks
cline -c ~/cline-worktrees/feature-auth -y --config ~/.cline-sonnet \
  "implement JWT authentication" &

cline -c ~/cline-worktrees/feature-api -y --config ~/.cline-sonnet \
  "create REST API endpoints for user management" &

cline -c ~/cline-worktrees/fix-tests -y --config ~/.cline-haiku \
  "fix all failing unit tests" &

wait
echo "All parallel tasks complete!"

# Pattern 2: Use piping for iterative refinement
cline -c ~/cline-worktrees/feature-auth -y \
  "test the authentication with curl. output only errors if any" \
  | cline -c ~/cline-worktrees/feature-auth -y \
  "fix the authentication issues described in the input"

# Merge successful changes back
cd ~/cline-worktrees/feature-auth
git checkout main
git merge feature/authentication

# Cleanup
git worktree remove ~/cline-worktrees/feature-auth

​
Best Practices

  • Use a dedicated folder: Create ~/cline-worktrees/ for all worktrees
  • Meaningful branch names: Use feature/, fix/, refactor/ prefixes
  • Clean up regularly: Remove worktrees after merging branches
  • Independent features only: Don’t parallelize tasks that touch the same files
  • Test in isolation: Each worktree should have its own test run
  • Separate configs: Use .worktreeinclude to copy node_modules and build artifacts
  • Monitor disk space: Each worktree is a full checkout
  • Limit parallel tasks: Running too many simultaneously can slow your system
  • Use background jobs wisely: Track with jobs command, kill with kill %1, etc.
  • Check exit codes: Use || echo "Task failed" to catch errors
  • Log outputs: Redirect to files for debugging: > worktree-a.log 2>&1
  • Graceful cleanup: Always remove worktrees after tasks complete

​
Troubleshooting

Git doesn’t allow the same branch in multiple worktrees. Solutions:
  • Use different branch names for each worktree
  • Remove the existing worktree first: git worktree remove <path>
Make sure you’re using:
  • & at the end of each command to background it
  • -y flag so Cline doesn’t wait for approval
  • Different worktrees (not the same path)
Verify:
  • First command outputs to stdout (not stderr)
  • Second command reads from stdin (use -- separator if needed)
  • Both commands use correct --cwd paths
Check:
  • You’re in the right worktree: git worktree list
  • Files aren’t gitignored
  • You committed/staged changes if needed

Worktrees Overview

Complete guide to Git worktrees, VS Code integration, and .worktreeinclude

Model Orchestration

Use different models strategically with —config and —thinking flags

CLI Reference

Complete documentation for —cwd and all other CLI flags

Three Core Flows

Learn about interactive mode, task mode, and plain text workflows