AI-Powered Features

Overview

LazyWorktree can integrate with AI tools like aichat or claude code to automatically generate:

Branch names from PR/issue titles or uncommitted diffs
Worktree notes from PR/issue descriptions

This eliminates manual naming decisions and provides context-aware summaries for each worktree.

AI features are completely optional. LazyWorktree works perfectly without them using manual branch names.

Automatic Branch Names

Why Use AI for Branch Names?

When creating worktrees from:

Pull requests - Get concise, semantic names instead of long PR titles
Issues - Convert issue descriptions into actionable branch names
Uncommitted diffs - Generate meaningful names for your current changes

Smaller, faster models suffice for branch naming. You don’t need expensive or powerful models—tools like gemini-2.5-flash-lite work excellently.

Configuration

Add branch_name_script to your LazyWorktree config:

# For PRs/issues: generate a title (available via {generated} placeholder)
branch_name_script: "aichat -m gemini:gemini-2.5-flash-lite 'Generate a short title for this PR or issue. Output only the title (like feat-session-manager), nothing else.'"

# Use the generated title in branch naming templates
pr_branch_name_template: "pr-{number}-{generated}"
issue_branch_name_template: "issue-{number}-{generated}"

For uncommitted diffs, generate complete branch names:

branch_name_script: "aichat -m gemini:gemini-2.5-flash-lite 'Generate a short git branch name (no spaces, use hyphens) for this diff. Output only the branch name, nothing else.'"

Template Placeholders

Use these placeholders in your branch name templates:

Placeholder	Description	Example
`{number}`	PR or issue number	`42`
`{title}`	Original title, sanitised for Git	`add-ai-session-management`
`{generated}`	AI-generated title (falls back to `{title}` on failure)	`feat-ai-session-manager`
`{pr_author}`	PR author username (PR templates only)	`alice`

Template Examples

Assuming AI generates: feat-ai-session-manager for Issue #2

Template	Result
`issue-{number}-{title}`	`issue-2-add-ai-session-management`
`issue-{number}-{generated}`	`issue-2-feat-ai-session-manager`
`pr-{number}-{generated}`	`pr-7-feat-ai-session-manager`
`pr-{number}-{pr_author}-{title}`	`pr-7-alice-add-ai-session-management`
`{generated}`	`feat-ai-session-manager`

If the AI script fails or times out, {generated} automatically falls back to {title}. Your workflow continues uninterrupted.

Script Requirements

Your branch_name_script must:

Read from stdin - LazyWorktree pipes PR/issue content or diffs
Write to stdout - Output the branch name (first line is used)
Complete within 30 seconds - Scripts that exceed this timeout are terminated

Example script:

#!/bin/bash
# Reads stdin, generates branch name, outputs to stdout
aichat -m gemini:gemini-2.5-flash-lite 'Generate a short branch name. Output only the name, nothing else.'

Environment Variables

LazyWorktree provides context via environment variables:

Variable	Description	Values
`LAZYWORKTREE_TYPE`	Type of item being processed	`pr`, `issue`, or `diff`
`LAZYWORKTREE_NUMBER`	PR or issue number	`42` (empty for diffs)
`LAZYWORKTREE_TEMPLATE`	The template being used	`pr-{number}-{generated}`
`LAZYWORKTREE_SUGGESTED_NAME`	LazyWorktree’s default suggestion	`pr-42-add-feature`

Use these to customise prompts:

branch_name_script: |
  if [ "$LAZYWORKTREE_TYPE" = "diff" ]; then
    aichat -m gemini:gemini-2.5-flash-lite 'Generate a complete branch name for this diff'
  else
    aichat -m gemini:gemini-2.5-flash-lite 'Generate a short title (no issue-/pr- prefix) for this issue or PR'
  fi

Or reference the item number in prompts:

branch_name_script: |
  aichat -m gemini:gemini-2.5-flash-lite "Generate a title for item #$LAZYWORKTREE_NUMBER. Output only the title."

Branch Name Sanitisation

All branch names (manual or AI-generated) are automatically sanitised:

Special characters converted to hyphens: ., :, @, /, \, etc.
Spaces become hyphens
Leading and trailing hyphens removed
Consecutive hyphens collapsed to one
Length capped at 50 characters (manual) or 100 characters (AI-generated)

Input	Sanitised
`feature.new`	`feature-new`
`bug fix here`	`bug-fix-here`
`feature:test`	`feature-test`
`user@domain/fix`	`user-domain-fix`

Automatic Worktree Notes

Why Use AI for Notes?

When creating worktrees from PRs or issues, AI can summarise the description into practical implementation notes. This gives you immediate context when switching worktrees.

Configuration

Add worktree_note_script to generate notes automatically:

worktree_note_script: "aichat -m gemini:gemini-2.5-flash-lite 'Summarise this ticket into practical implementation notes.'"

The script receives the PR/issue title and body on stdin, then outputs your worktree note.

Synchronisable Notes with JSON Storage

By default, notes are stored in git config (local to each repository clone). For notes that sync across machines or team members, use JSON storage:

worktree_notes_path: ".lazyworktree/notes.json"

This creates a single JSON file in your repository with all worktree notes:

{
  "worktrees/feature-x": "Implement user authentication with OAuth2. Key files: auth.go, middleware.go",
  "worktrees/bugfix-123": "Fix race condition in session manager. Check session.go:45"
}

Commit .lazyworktree/notes.json to your repository to share notes with team members or sync across your own machines.

When worktree_notes_path is set, keys are stored relative to worktree_dir instead of absolute paths, making them portable across different systems.

Script Requirements

Your worktree_note_script must:

Read from stdin - Receives PR/issue title and description
Write to stdout - Output the note text (can be multiline)
Complete within 30 seconds - Timeout enforced

Example:

#!/bin/bash
aichat -m gemini:gemini-2.5-flash-lite 'Summarise this into 2-3 practical notes for implementation.'

If the note script fails or outputs nothing, worktree creation continues normally without saving a note.

AI Tool Setup

Using aichat

aichat is a CLI tool supporting multiple AI providers. Install:

# macOS
brew install aichat

# Linux
cargo install aichat

Configure:

# Set up your preferred model
aichat --model gemini:gemini-2.5-flash-lite

LazyWorktree config:

branch_name_script: "aichat -m gemini:gemini-2.5-flash-lite 'Generate a short branch name. Output only the name.'"
worktree_note_script: "aichat -m gemini:gemini-2.5-flash-lite 'Summarise into practical notes.'"

Using claude code

If you have access to claude code:

branch_name_script: "claude code --prompt 'Generate a short branch name for this content. Output only the name.'"

Custom AI Scripts

Any script or tool that reads stdin and writes stdout works:

branch_name_script: "/path/to/custom-ai-script.sh"

Example custom script:

#!/bin/bash
# custom-ai-script.sh
# Reads stdin, calls your preferred AI API, outputs result

content=$(cat)
curl -s https://api.your-ai-service.com/generate \
  -d "{\"prompt\": \"Generate branch name\", \"content\": \"$content\"}" \
  | jq -r '.result'

Troubleshooting AI Features

Script times out after 30 seconds

Your AI provider is too slow. Try:

Using a faster model (e.g., flash variants)
Reducing context sent to the model
Checking network connectivity

Generated names contain spaces or invalid characters

LazyWorktree automatically sanitises all branch names. If you’re still seeing issues, check that your script outputs only the branch name with no extra formatting.

always uses fallback

Your script is failing. Test it manually:

echo "Test PR title\n\nTest description" | aichat -m gemini:gemini-2.5-flash-lite 'Generate a branch name'

Check for:

API authentication issues
Network errors
Model availability

Worktree notes not appearing

Check that:

worktree_note_script is defined in your config
The script runs successfully when tested manually
You’re viewing notes in the correct location (git config vs JSON file)

Notes not syncing across machines

Ensure:

worktree_notes_path is set to a file in your repository
The JSON file is committed and pushed
Other machines have pulled the latest changes

Performance Tips

Use smaller models

Branch naming doesn’t require powerful models. gemini-2.5-flash-lite, gpt-3.5-turbo, or similar fast models work excellently and complete in under 2 seconds.

Cache common responses

For repeated PR/issue names, consider a caching layer in your custom script to avoid redundant API calls.

Limit context sent to AI

If PR descriptions are very long, truncate them before sending to the AI model:

head -n 50 | aichat -m gemini:gemini-2.5-flash-lite 'Generate name'

See Branch Naming for more template customisation
See Notes and Taskboard for managing worktree notes without AI

Getting Started

Core Features

Configuration

Usage Guides

Advanced

Overview

Automatic Branch Names

Why Use AI for Branch Names?

Configuration

Template Placeholders

Template Examples

Script Requirements

Environment Variables

Branch Name Sanitisation

Automatic Worktree Notes

Why Use AI for Notes?

Configuration

Synchronisable Notes with JSON Storage

Script Requirements

AI Tool Setup

Using aichat

Using claude code

Custom AI Scripts

Troubleshooting AI Features

Script times out after 30 seconds

Generated names contain spaces or invalid characters

always uses fallback

Worktree notes not appearing

Notes not syncing across machines

Performance Tips

Build docs developers (and LLMs) love

Getting Started

Core Features

Configuration

Usage Guides

Advanced

​Overview

​Automatic Branch Names

​Why Use AI for Branch Names?

​Configuration

​Template Placeholders

​Template Examples

​Script Requirements

​Environment Variables

​Branch Name Sanitisation

​Automatic Worktree Notes

​Why Use AI for Notes?

​Configuration

​Synchronisable Notes with JSON Storage

​Script Requirements

​AI Tool Setup

​Using aichat

​Using claude code

​Custom AI Scripts

​Troubleshooting AI Features

​Script times out after 30 seconds

​Generated names contain spaces or invalid characters

​ always uses fallback

​Worktree notes not appearing

​Notes not syncing across machines

​Performance Tips

​Related Configuration

Build docs developers (and LLMs) love

Overview

Automatic Branch Names

Why Use AI for Branch Names?

Configuration

Template Placeholders

Template Examples

Script Requirements

Environment Variables

Branch Name Sanitisation

Automatic Worktree Notes

Why Use AI for Notes?

Configuration

Synchronisable Notes with JSON Storage

Script Requirements

AI Tool Setup

Using aichat

Using claude code

Custom AI Scripts

Troubleshooting AI Features

Script times out after 30 seconds

Generated names contain spaces or invalid characters

always uses fallback

Worktree notes not appearing

Notes not syncing across machines

Performance Tips

Related Configuration