worktree-manager

Worktree Manager

Automated git worktree management for AI coding agents (Cursor, Claude Code, etc.) with smart naming, auto-setup, and cleanup.

Cursor Native Worktree Support

Cursor has built-in worktree support via .cursor/worktrees.json. When you create a worktree through Cursor's UI or this script, the following files are automatically copied:

• .env - Environment variables
• .claude/settings.local.json - AI agent local settings

Dependencies are installed in the background via pnpm install.

Note: MCP settings (.cursor/mcp.json, .mcp.json) are NOT copied because Cursor inherits MCP configuration from the main application automatically.

Quick Start

Create a Worktree

When the user asks to create a worktree for a feature or environment, derive a short, descriptive kebab-case name from their request:

Naming examples:

• "staging environment" → staging-env
• "add dark mode toggle" → dark-mode
• "fix authentication bug" → fix-auth-bug
• "update API endpoints" → update-api

Then run:

# Standard (uses shared dev database)
.claude/skills/worktree-manager/scripts/worktree.sh create <derived-name>

# Isolated (creates dedicated database with seeding)
.claude/skills/worktree-manager/scripts/worktree.sh create <derived-name> --isolated

What happens:

1. Cleans up worktrees older than 7 days
2. Creates branch: worktree/<name>-<timestamp>
3. Creates worktree at: ~/ai-worktrees/<project-name>/<name>-<timestamp>
4. Copies configuration files from main repo:
   • .env
   • .claude/settings.local.json
5. Starts pnpm install in background
6. If --isolated: Creates dedicated database and seeds it with test data
7. Returns the worktree path immediately

When to Use --isolated

Use the --isolated flag when:

• Schema changes: Testing database migrations
• Migration testing: Verifying migration scripts work correctly
• Isolated experiments: Need a clean database state
• Breaking changes: Don't want to affect shared dev data

For normal feature development, skip --isolated to use the shared database.

List Worktrees

.claude/skills/worktree-manager/scripts/worktree.sh list

Shows all active worktrees for the current project with their branches.

Manual Cleanup

# Cleanup worktrees older than 7 days (default)
.claude/skills/worktree-manager/scripts/worktree.sh cleanup

# Custom age threshold
.claude/skills/worktree-manager/scripts/worktree.sh cleanup --days 14

Workflow

1. User Requests Worktree

User says: "I want to create a new worktree for developing a staging environment"

2. Derive Smart Name

Analyze the request and derive a concise kebab-case name:

• Extract key purpose: "staging environment"
• Convert to kebab-case: staging-env

3. Create Worktree

.claude/skills/worktree-manager/scripts/worktree.sh create staging-env

4. Return Path to User

The script outputs the worktree path. Return it to the user so they can open it in their preferred environment:

Worktree created at: ~/ai-worktrees/orient/staging-env-1736639420

pnpm install is running in the background. Check progress with:
tail -f ~/ai-worktrees/orient/staging-env-1736639420/.pnpm-install.log

You can open this worktree in:
- Cursor: File > Open Folder > navigate to path
- Terminal: cd ~/ai-worktrees/orient/staging-env-1736639420

Background Installation

The worktree creation starts pnpm install in the background using nohup. This means:

• The path is returned immediately (don't wait for pnpm)
• Installation runs async and logs to .pnpm-install.log
• User can start working right away
• Dependencies will be available after a few moments

Check if installation is complete:

# Check if still running
ps aux | grep pnpm

# Watch the log
tail -f <worktree-path>/.pnpm-install.log

Database Seeding (Isolated Mode)

When using --isolated, the script automatically:

1. Creates a new PostgreSQL database: worktree_<timestamp>
2. Updates the worktree's .env with the new DATABASE_URL
3. Runs all migrations from data/migrations/
4. Seeds the database with test data

Database seeding starts after pnpm install completes. Check progress:

tail -f <worktree-path>/.db-seed.log

Manual Database Seeding

If you need to seed an existing worktree:

# Seed with shared database (from .env)
./scripts/seed-worktree-db.sh

# Create isolated database and seed
ISOLATED=true ./scripts/seed-worktree-db.sh

Configuration Files

The script automatically copies configuration files:

Automatically Available (via git):

• .claude/skills/ - All skills are available in worktrees
• .claude/settings.json - Committed settings

Automatically Copied:

• .env - Environment variables for the application
• .claude/settings.local.json - Local settings (API keys, preferences)

Inherited from Main App (not copied):

• .cursor/mcp.json - Cursor MCP configuration
• .mcp.json - Root MCP configuration

Cursor inherits MCP settings from the main application, so worktrees have full MCP tool access without copying these files.

Directory Structure

~/ai-worktrees/
└── <project-name>/
    ├── feature-a-1736639420/
    ├── staging-env-1736639421/
    └── fix-bug-1736639422/

Each project gets its own subdirectory under ~/ai-worktrees/.

Cleanup Policy

• Automatic: Runs before each worktree creation
• Threshold: Removes worktrees older than 7 days (based on modification time)
• Safe: Only removes worktrees in the AI worktree directory
• Manual: Can be triggered anytime with ./worktree.sh cleanup

.env Configuration Requirements

The .env file is copied to worktrees automatically. Ensure proper formatting to avoid shell parsing errors:

Quote Special Characters

Values with special characters MUST be quoted:

# Correct - quoted values
DATABASE_URL="postgresql://user:pass@localhost:5432/db"
STANDUP_CRON="30 9 * * 1-5"
STANDUP_CHANNEL="#orienter-standups"

# Wrong - unquoted special chars cause shell errors
STANDUP_CRON=30 9 * * 1-5          # Shell expands * as glob
STANDUP_CHANNEL=#orienter-standups  # Shell treats # as comment

Required Variables

For database seeding to work, ensure DATABASE_URL is set:

DATABASE_URL="postgresql://aibot:aibot123@localhost:5432/whatsapp_bot"

Troubleshooting

pnpm install failed

Check the log:

cat <worktree-path>/.pnpm-install.log

Re-run manually if needed:

cd <worktree-path>
pnpm install

Config files not copied

Copy manually:

cp <main-repo>/.env <worktree-path>/.env
cp <main-repo>/.claude/settings.local.json <worktree-path>/.claude/settings.local.json

Database seeding failed

Check the log:

cat <worktree-path>/.db-seed.log

Common issues:

• PostgreSQL not running: docker compose -f docker/docker-compose.infra.yml up -d postgres
• Invalid DATABASE_URL: Check quotes and format
• Missing tables: Run npm run db:migrate first

Worktree creation failed

Check git status and ensure:

• You're in a git repository
• Remote is accessible
• No uncommitted changes blocking the operation

Examples

Create worktree for a feature

User: "Create a worktree for adding OAuth support"

.claude/skills/worktree-manager/scripts/worktree.sh create oauth-support

Create worktree for bug fix

User: "I need a worktree to fix the login redirect issue"

.claude/skills/worktree-manager/scripts/worktree.sh create fix-login-redirect

Create worktree with isolated database

User: "I need a worktree to test new database migrations"

.claude/skills/worktree-manager/scripts/worktree.sh create test-migrations --isolated

List all worktrees

User: "Show me all my worktrees"

.claude/skills/worktree-manager/scripts/worktree.sh list

Cleanup old worktrees

User: "Clean up worktrees older than 3 days"

.claude/skills/worktree-manager/scripts/worktree.sh cleanup --days 3