this isn't a bug report — instead it's a pattern I've been working with claude for a few weeks, to the extent I thought it would be worth sharing. I now use it for basically all my development where I can use claude code.

the main advantage is that it allows running an arbitrary number of claude instances without overhead, by encapsulating the main git worktree operations.

fwiw I also used claude code to help write the functions, and to summarize it into an issue here. no need to keep the issue open

Git worktree workflow

The overall workflow I use is:

Start a new feature with git worktree-llm feature-name
Work on the feature with Claude's assistance
When ready to merge, use git worktree-merge
The changes are committed, the worktree is closed, and changes are rebased and merged

This creates a clean, efficient workflow for feature development with AI assistance and handles all the git operations to create a clean history.

git worktree-llm

This function creates a git worktree and immediately starts an LLM session. It's a streamlined workflow for feature development with AI assistance:

function git worktree-llm -d "Create a git worktree and start claude"
    # Create the worktree, then run setup in background and start claude
    if git worktree-create $argv
        task setup-worktree </dev/null >/dev/null 2>&1 & disown
        claude
    end
end

The function:

Creates a new worktree with git worktree-create passing through any arguments
Runs a background task to set up the worktree (task setup-worktree). This is a task that each project can define which does things like:

install dependencies; uv sync
starts daemon processes; uv run dmypy run --timeout=3600
add claude configs, like allowedTools, which didn't have global configs

Immediately launches claude (without waiting for the background task to finish)

(We still need to hit return twice, to approve MCPs and approve loading a CLAUDE.md from a parent directory. Hopefully these could be eliminated by claude in the future.)

Work

Then we do work!

When finished:

git worktree-merge

This function finishes work on a branch and merges it into the main branch:

function git worktree-merge --description "Finish worktree and merge branch into main"
    # Save the branch name before finishing the worktree
    set branch (git branch --show-current)
    set default_branch (git default-branch)

    # Skip if already on default branch (let git worktree-finish handle this normally)
    if test "$branch" = "$default_branch"
        return 0
    end

    # Add all changes first
    git add .

    # Finish the worktree first
    git worktree-finish; or return

    # Rebase branch onto default branch first
    set_color cyan
    echo "⚙️  Rebasing $branch onto $default_branch"
    set_color normal

    git rebase $default_branch $branch; or return
    git switch $default_branch; or return

    # Now merge the branch (don't delete it)
    set_color cyan
    echo "🔄 Merging $branch into $default_branch"
    set_color normal

    git merge --no-edit $branch; or return
end

The function:

Captures the current branch name
Adds all changes to the git index
Finishes the worktree (returning to the main repository)
Rebases the feature branch onto the default branch
Switches to the default branch
Merges the feature branch without prompting for a commit message

Supporting Functions

These main functions rely on several supporting functions:

git worktree-create

Creates a new worktree for a branch and navigates to it, either creating a new branch or using an existing one.