Skip to main content

​
Overview

Worktrees in Jean are isolated git branches, each with their own working directory. They let you work on multiple features simultaneously without constant branch switching and stashing. Key concepts:
  • Each worktree is a separate directory with its own branch
  • Worktrees are named with random friendly names (e.g., fuzzy-tiger, happy-cloud)
  • Each worktree contains chat sessions tracking your AI conversations
  • Worktrees can be linked to GitHub PRs and issues

​
Creating a New Worktree

1

Start Worktree Creation

With a project selected, press Cmd+N (Mac) or Ctrl+N (Windows/Linux).Alternatively, click the ”+” button next to the project name in the sidebar.
2

Choose Creation Method

You have several options:Empty Worktree: Creates a clean worktree from the default branchFrom Issue: Creates a worktree linked to a GitHub issue. Jean will:
  • Generate a branch name from the issue title
  • Create the worktree
  • Start a chat session with the issue context loaded
From Pull Request: Checks out an existing PR as a worktree for review or continuationFrom Branch: Creates a worktree from an existing local or remote branch
3

Wait for Setup

Jean will:
  1. Pull the latest changes from the default branch (if auto-pull is enabled)
  2. Create the git worktree and branch
  3. Run the setup script from jean.json (if present)
  4. Create an initial chat session
You’ll see a loading indicator in the sidebar while this happens.
4

Start Working

Once ready, the worktree appears in the sidebar under your project. Click it to open the chat interface.

​
Creating from GitHub Issues

This is the most powerful worktree creation method for issue-driven development.
1

Open Magic Modal

Press Cmd+M to open the Magic Commands modal.
2

Navigate to Issues Tab

Click the Issues tab to see all open issues from your repository.
3

Select an Issue

Browse the list and click on the issue you want to work on. You’ll see:
  • Issue title and number
  • Description
  • Comments
  • Labels
4

Create Worktree

Click Investigate Issue. Jean will:
  1. Generate a branch name from the issue title (e.g., fix-login-bug-123)
  2. Create the worktree
  3. Save the issue context to a file in .github/issues/
  4. Start a chat session with a prompt to investigate the issue
  5. Store the issue number for later PR creation
5

Work on the Issue

The AI assistant will analyze the issue, explore the codebase, and propose solutions. You can iterate in the chat to refine the approach.

​
Switching Between Worktrees

1

Click to Switch

Click any worktree in the sidebar to switch to it. Jean will:
  • Save the current chat session
  • Load the selected worktree
  • Show the most recent chat session (or the canvas view if multiple sessions exist)
2

Keyboard Navigation

Use Cmd+Alt+→ and Cmd+Alt+← to cycle through sessions within a worktree.There’s no built-in keyboard shortcut to switch worktrees, but you can use the Quick Menu (Cmd+.) and type the worktree name.
3

Restore Last Session

Enable Restore Last Session in Preferences → General. When you switch projects, Jean will automatically return to the last worktree and session you were viewing.

​
Merging Worktrees

Once your work is complete, you can merge the worktree back into the base branch.
1

Open Magic Modal

With the worktree selected, press Cmd+M.
2

Select Merge Option

Choose one of:
  • Merge: Creates a merge commit (preserves full history)
  • Squash: Combines all commits into one (cleaner history)
  • Rebase: Replays commits on top of base branch (linear history)
3

Review Changes

Jean will show:
  • Files changed
  • Commit count
  • Diff summary
Verify the changes are correct before proceeding.
4

Confirm Merge

Click Merge. Jean will:
  1. Switch to the base branch
  2. Perform the merge/squash/rebase
  3. Push changes to remote (if configured)
  4. Archive the worktree (if “Auto-archive on PR merged” is enabled)
If there are conflicts, Jean will stop and prompt you to resolve them. See Handling Merge Conflicts below.

​
Handling Merge Conflicts

When merging produces conflicts, Jean provides AI-assisted resolution.
1

Detect Conflicts

When a merge fails due to conflicts, Jean will:
  • Show which files have conflicts
  • Display the conflict diff with <<<<<<<, =======, and >>>>>>> markers
2

Open Resolve Conflicts

In the Magic Modal, select Resolve Conflicts. Jean will:
  1. Create a new chat session
  2. Load the conflict diff as context
  3. Send a prompt asking Claude to analyze and resolve each conflict
3

Review AI Suggestions

Claude will:
  • Explain what’s conflicting in each file
  • Recommend resolutions
  • Provide commands to stage resolved files
You can ask follow-up questions or request alternative approaches.
4

Apply Resolutions

Claude can directly edit the conflicted files to remove markers and merge changes. After each file is resolved, run:
git add <file>
5

Complete the Merge

Once all conflicts are resolved and staged, run:
git merge --continue
# or
git rebase --continue
# or
git cherry-pick --continue
The merge operation completes and your worktree is clean.

​
Cleaning Up Worktrees

You can archive or permanently delete worktrees when they’re no longer needed.
1

Close the Worktree

Press Cmd+W with the worktree selected, or right-click and select Close.
2

Choose Removal Behavior

Depending on your Preferences → General → Session Removal Behavior setting:Archive (default): Worktree is hidden but not deleted. You can restore it later via Cmd+Shift+T.Delete: Worktree is permanently removed:
  • Git worktree is deleted
  • Branch is deleted locally and remotely (if pushed)
  • All chat sessions are deleted
  • Teardown script runs (if configured)
3

Restore Archived Worktrees

Press Cmd+Shift+T to restore the most recently archived worktree.Or right-click the project → View Archived to see all archived worktrees and restore specific ones.

​
Advanced: Auto-Pull Base Branch

When enabled (Preferences → General), Jean automatically pulls the latest changes from the default branch before creating a new worktree. Why this matters:
  • Ensures new worktrees start from the latest code
  • Reduces merge conflicts later
  • Catches upstream changes early
Trade-off:
  • Adds a few seconds to worktree creation
  • Requires network access
Disable auto-pull if you work offline or want faster worktree creation. You can manually pull the base branch later with Cmd+M → Pull.

​
Advanced: Teardown Scripts

Just like setup scripts, you can define a teardown script in jean.json that runs when a worktree is deleted: 
{
  "scripts": {
    "setup": "bun install",
    "teardown": "docker-compose down && rm -rf node_modules"
  }
}
Use cases:
  • Stop development servers
  • Clean up Docker containers
  • Remove large build artifacts
  • Free disk space

​
Common Pitfalls

Worktree Path Already Exists: If you try to create a worktree with a name that already exists on disk, Jean will:
  • Show an error dialog
  • Suggest an alternative name (e.g., fuzzy-tiger-2)
  • Offer to restore the archived worktree if it exists
Solution: Choose the suggested name or restore the existing worktree.
Branch Already Exists: If you try to create a worktree from an issue but the branch name already exists:
  • Jean will suggest an alternative name with a numeric suffix
  • The existing branch is NOT deleted or modified
Solution: Use the suggested name or manually delete the old branch first.
Setup Script Fails: If the setup script exits with a non-zero status:
  • The worktree is still created (so you can debug)
  • Setup output is saved and shown in the worktree logs
  • The worktree status shows an error indicator
Solution: Click the worktree, open the logs tab, and review the error output. Fix the issue and manually run the setup commands.

​
Best Practices

One Worktree per Feature: Create separate worktrees for each feature, bug fix, or experiment. This keeps work isolated and easy to review.
Archive Early, Archive Often: Don’t let unused worktrees pile up. Archive them when done to keep your sidebar clean. You can always restore them later.
Link PRs Early: If you’re working on a feature that will become a PR, create the PR as soon as you have a first commit. Jean will track PR status and CI checks automatically.
Use Descriptive Issue Titles: When creating worktrees from issues, Jean generates branch names from issue titles. Clear titles → clear branch names.

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us