Worktree Automation

​

Overview

​

Key Capabilities

​

Worktree Creation

• Generates random workspace names (e.g., “fuzzy-tiger”)
• Creates matching Git branch
• Sets up directory structure
• Runs optional setup scripts
• Creates initial base session

1. Manual Creation - New branch from base
2. From GitHub Issue - Automatically investigates issue and creates context
3. From Pull Request - Checks out PR branch as worktree
4. From Workflow Failure - Investigates failed CI run

// From src-tauri/src/projects/storage.rs
pub fn get_project_worktrees_dir(name: &str, custom_base_dir: Option<&str>) -> PathBuf {
    match custom_base_dir {
        Some(dir) => PathBuf::from(dir).join(name),
        None => dirs::home_dir()
            .unwrap_or_else(|| PathBuf::from("."))
            .join("jean")
            .join(name),
    }
}

~/jean/
  ├─ project-name/
  │   ├─ fuzzy-tiger/          # Worktree 1
  │   │   └─ ...               # Git files
  │   ├─ happy-dolphin/        # Worktree 2
  │   │   └─ ...
  │   └─ eager-panda/          # Worktree 3
  │       └─ ...

​

Worktree Types

interface Worktree {
  session_type: 'worktree'  // Default type
  branch: string             // Branch name (matches workspace name)
  path: string               // Absolute path to worktree directory
  status: WorktreeStatus     // pending | ready | error | deleting
}

interface Worktree {
  session_type: 'base'  // Base session in original repo
  path: string          // Points to original repository
}

​

Background Operations

1. User initiates worktree creation
2. Pending worktree created with status: 'pending'
3. Background task runs:
   • Pull base branch (if auto-pull enabled)
   • Create Git worktree
   • Run setup script (if configured)
   • Emit completion event
4. Status updates to ready or error

// Worktree creation events
interface WorktreeCreatingEvent {
  id: string
  project_id: string
  name: string
  path: string
  branch: string
  issue_number?: number
  pr_number?: number
}

interface WorktreeCreatedEvent {
  worktree: Worktree
}

interface WorktreeCreateErrorEvent {
  id: string
  project_id: string  
  error: string
}

​

Setup Scripts

• Stored in project settings (setup_script field)
• Runs after Git worktree creation
• Output captured and stored
• Success/failure tracked

#!/bin/bash
# Install dependencies
bun install

# Build project
bun run build

# Run database migrations
bun run migrate

interface Worktree {
  setup_output?: string       // Script stdout/stderr
  setup_script?: string       // The script that was executed
  setup_success?: boolean     // undefined = no script
}

​

Archiving & Restoration

• Worktree marked with archived_at timestamp
• Hidden from main view, visible in Archive modal
• Git directory and all files remain intact
• Sessions and data preserved
• Can be restored at any time

• When PR is merged (if auto_archive_on_pr_merged enabled)
• Triggered by GitHub webhook or polling detection
• Configurable in Settings → Worktrees

1. Open Archive modal (Cmd/Ctrl + Shift + A)
2. Click “Restore” on archived worktree
3. Worktree returns to active view
4. All sessions and state preserved

• Archives are cleaned up based on retention policy
• Default: 7 days (configurable in Settings)
• Can manually delete from Archive modal
• Irreversible - removes Git directory and all data

​

Path Conflict Resolution

interface WorktreePathExistsEvent {
  id: string                  // Pending worktree ID
  path: string                // Conflicting path
  suggested_name: string      // Name with incremented suffix
  archived_worktree_id?: string  // If matches archived worktree
  archived_worktree_name?: string
  issue_context?: {...}       // Preserve issue context
}

1. Restore archived worktree - If path matches archived one
2. Use suggested name - Automatically incremented (e.g., fuzzy-tiger-2)
3. Cancel - Abort worktree creation

​

Branch Conflict Resolution

interface WorktreeBranchExistsEvent {
  branch: string              // Conflicting branch name
  suggested_name: string      // Alternative name
  issue_context?: {...}       // Context to preserve
  pr_context?: {...}          // Context to preserve
}

​

How to Use

​

Creating a Worktree

1. Click ”+” next to project name
2. Select “New Worktree”
3. Worktree creates in background
4. Status indicator shows progress
5. Opens automatically when ready

1. Open GitHub integration panel
2. Browse issues list
3. Click “Investigate” on any issue
4. Jean creates worktree and loads issue context
5. AI analyzes issue and proposes solution

1. Find PR in GitHub integration
2. Click “Checkout PR”
3. Creates worktree on PR’s branch
4. Loads PR context, reviews, and comments

​

Managing Worktrees

• Listed under each project in sidebar
• Shows status badges (CI, PR, uncommitted changes)
• Color-coded labels
• Last opened timestamp

• Click any worktree in sidebar
• Recent worktrees appear at top
• Each has independent sessions and state

• Right-click for context menu
• Open in terminal
• Open in editor (Zed, VS Code, Cursor, etc.)
• View in Finder
• Archive or delete

​

Archiving Workflow

1. Right-click worktree → Archive
2. Confirmation dialog appears (if enabled)
3. Worktree moves to archive
4. Badge shows archived status

1. Press Cmd/Ctrl + Shift + A
2. Archives listed by project
3. Search and filter options
4. Shows age and retention countdown

1. Find archived worktree
2. Click “Restore”
3. Returns to active worktrees
4. All data intact and ready to use

​

Cleanup & Deletion

1. Right-click → Delete (or from Archive modal)
2. Confirmation dialog with warning
3. Runs teardown script if configured
4. Removes Git worktree
5. Deletes directory and all files
6. Removes from Jean database

#!/bin/bash
# Cleanup before deletion
rm -rf node_modules
rm -rf .next
docker-compose down

• Archived worktrees deleted after retention period
• Runs daily cleanup check
• Logs cleanup actions
• No recovery possible after deletion

​

Configuration Options

​

Settings → Worktrees

• auto_pull_base_branch: Pull base before creating worktree (default: true)
• auto_archive_on_pr_merged: Archive when PR merges (default: true)
• archive_retention_days: Days before permanent deletion (default: 7)
• removal_behavior: “archive” or “delete” on close (default: delete)

• confirm_session_close: Show confirmation before closing (default: true)

​

Per-Project Settings

• Custom base directory
• Browse to select location
• Reset to default (~/jean)

• Bash script to run on creation
• Can use project-specific commands
• Output displayed in UI

​

Best Practices

​

Worktree Naming

• Avoid ambiguous names like “feature” or “fix”
• Memorable animal/adjective combinations
• Easy to reference in conversation
• Branch names match worktree names

• Reduces cognitive load
• Prevents naming conflicts
• Focuses on work, not naming things

​

Setup Scripts

#!/bin/bash
set -e  # Exit on error

# Check if dependencies already installed
if [ ! -d "node_modules" ]; then
  bun install
fi

# Only build if needed
if [ ! -d ".next" ]; then
  bun run build
fi

• Don’t install global tools
• Assume Git and language runtimes present
• Keep execution time under 2 minutes

​

Archive Management

• 7 days: Fast-moving teams, many PRs
• 14 days: Standard development cycles
• 30 days: Slow review process, external dependencies
• Never: Manual cleanup only (use with caution)

• Archive: Safe default, can undo mistakes
• Delete: Saves disk space, requires more care

​

Disk Space Management

• Each worktree is a full Git checkout
• Build artifacts (node_modules, target/, etc.) multiply storage
• Clean up unused worktrees regularly
• Use custom locations to spread across drives

• Small project (5 MB repo): ~50 MB per worktree
• Medium project (50 MB repo): ~500 MB per worktree
• Large project (500 MB repo + deps): ~5 GB per worktree

​

Conflict Resolution

1. Check if it’s an archived worktree first
2. Restore if you want to continue that work
3. Use suggested name for new work
4. Clean up archives if running out of names

1. Likely a remote branch already exists
2. Use suggested name for new branch
3. Or delete remote branch if no longer needed
4. Pull requests preserve issue context automatically