From klair-legacy
Guides users through creating, using, and cleaning up git worktrees for parallel feature development. Use when users want to work on multiple branches simultaneously, test changes in isolation, or manage parallel development workflows.
npx claudepluginhub ai-builder-team/ai-builder-plugin-marketplace --plugin klair-legacyThis skill is limited to using the following tools:
This skill helps you work with multiple branches simultaneously using git worktrees. Each worktree is an isolated working directory with its own dependencies, environment configuration, and dedicated ports for services.
Generates design tokens/docs from CSS/Tailwind/styled-components codebases, audits visual consistency across 10 dimensions, detects AI slop in UI.
Records polished WebM UI demo videos of web apps using Playwright with cursor overlay, natural pacing, and three-phase scripting. Activates for demo, walkthrough, screen recording, or tutorial requests.
Delivers idiomatic Kotlin patterns for null safety, immutability, sealed classes, coroutines, Flows, extensions, DSL builders, and Gradle DSL. Use when writing, reviewing, refactoring, or designing Kotlin code.
This skill helps you work with multiple branches simultaneously using git worktrees. Each worktree is an isolated working directory with its own dependencies, environment configuration, and dedicated ports for services.
Git worktrees allow you to check out multiple branches simultaneously in separate directories:
/path/to/project/
├── .git/ # Shared git directory
├── klair-api/ # Main worktree (tree1)
├── klair-client/ # Main worktree (tree1)
└── trees/
├── tree2/ # Second worktree (ports 3002/5002)
│ ├── klair-api/
│ └── klair-client/
└── tree3/ # Third worktree (ports 3003/5003)
├── klair-api/
└── klair-client/
Benefits:
Use this skill when the user wants to:
Use this when starting new development work:
bash .claude/scripts/create-worktrees/create.sh <feature-name>
What it does:
treeN-<feature-name> from main.env files from main worktree3000+N, backend 5000+Nhttp://localhost:5000+NExample:
# Create worktree for user authentication feature
bash .claude/scripts/create-worktrees/create.sh user-authentication
# Result:
# - Location: trees/tree2/
# - Branch: tree2-user-authentication (new)
# - Based on: main
# - Ports: 3002 (frontend), 5002 (backend)
# - API URL: http://localhost:5002
Flags:
--full: Install all sub-project dependencies (not just client+api)--no-install: Skip dependency installation (fastest)--no-terminal: Don't open terminal window--no-claude: Skip opening Claude Code session--task "desc": Task description for Claude sessionExamples:
# Create from develop branch
bash .claude/scripts/create-worktrees/create.sh payment-gateway develop
# Quick worktree without installation
bash .claude/scripts/create-worktrees/create.sh quick-fix --no-install --no-terminal
# Full installation with Claude task
bash .claude/scripts/create-worktrees/create.sh new-feature --full --task "Implement user dashboard"
Use this when you need to work on an existing branch (local or remote):
bash .claude/scripts/create-worktrees/create.sh --branch <branch-name>
What it does:
.env files and configures based on branch:
main branch → Dev API: https://dev-adoption-api.klairvoyant.ai/prod branch → Prod API: https://adoption-api.klairvoyant.ai/http://localhost:5000+NExamples:
# Work on main branch (uses dev API)
bash .claude/scripts/create-worktrees/create.sh --branch main
# Work on prod branch (uses prod API)
bash .claude/scripts/create-worktrees/create.sh --branch prod
# Work on existing feature branch
bash .claude/scripts/create-worktrees/create.sh --branch feature/analytics-dashboard
# Work on remote branch
bash .claude/scripts/create-worktrees/create.sh --branch origin/feature/payment-gateway
# Existing branch without installation
bash .claude/scripts/create-worktrees/create.sh --branch hotfix/critical-bug --no-install
After creating a worktree, start the services:
cd trees/tree2
./start-services.sh 3002 5002
What it does:
.env files with dynamic ports (preserves remote API URLs)[FRONTEND] and [BACKEND] tagsImportant: The script preserves remote API URLs (dev/prod) and only updates localhost URLs to use the dynamic port.
Each worktree is completely isolated:
# Main worktree (tree1)
cd ~/project
pnpm dev # Frontend: 3001
uv run fast_endpoint.py # Backend: 5001
# Second worktree (tree2)
cd ~/project/trees/tree2
./start-services.sh 3002 5002
# Third worktree (tree3)
cd ~/project/trees/tree3
./start-services.sh 3003 5003
Access your apps:
After merging PRs or abandoning features, clean up worktrees.
Interactive cleanup (recommended):
bash .claude/scripts/create-worktrees/cleanup.sh
Shows a list of all worktrees with:
You can then select which worktrees to remove.
Automated cleanup:
# Remove specific worktrees
bash .claude/scripts/create-worktrees/cleanup.sh --auto tree2,tree3
# Remove all worktrees
bash .claude/scripts/create-worktrees/cleanup.sh --auto "*"
# Remove and update main branch
bash .claude/scripts/create-worktrees/cleanup.sh --auto tree2 --update-main
IMPORTANT: Always ask the user if they want to update main branch after cleanup:
"Would you like me to also checkout main and pull the latest changes after cleanup?
(This is useful since the worktree cleanup typically happens after a PR is merged)"
When to clean up:
Note: Ensure changes are committed and pushed before cleanup!
| Worktree Location | Tree Number | Frontend Port | Backend Port |
|---|---|---|---|
| Main worktree (repo root) | 1 | 3001 | 5001 |
trees/tree2/ | 2 | 3002 | 5002 |
trees/tree3/ | 3 | 3003 | 5003 |
trees/treeN/ | N | 3000+N | 5000+N |
The creation script automatically configures .env files based on the branch:
| Branch | Frontend API URL | Backend Port |
|---|---|---|
main | https://dev-adoption-api.klairvoyant.ai/ | N/A (uses remote) |
prod | https://adoption-api.klairvoyant.ai/ | N/A (uses remote) |
| Other branches | http://localhost:5000+N | 5000+N |
Preserved by start-services.sh:
When creating new branches via worktrees, use descriptive names:
# Good
bash .claude/scripts/create-worktrees/create.sh user-authentication
bash .claude/scripts/create-worktrees/create.sh fix-invoicing-bug
bash .claude/scripts/create-worktrees/create.sh refactor-api-client
# Avoid
bash .claude/scripts/create-worktrees/create.sh test
bash .claude/scripts/create-worktrees/create.sh tmp
bash .claude/scripts/create-worktrees/create.sh asdf
.venv, node_modules)uv and pnpm - they hardlink packages from cache (saves disk space)With direnv installed and configured:
.env files auto-loadWithout direnv:
source klair-api/.venv/bin/activatesource klair-api/.envSince worktrees share the same git repository:
For comparing different approaches:
"Branch already exists":
# Remove the branch first
git branch -D tree2-feature-name
# Or use --branch to checkout existing branch
bash .claude/scripts/create-worktrees/create.sh --branch existing-branch
"Worktree already exists":
# Remove the worktree
git worktree remove trees/tree2 --force
# Or use cleanup script
bash .claude/scripts/create-worktrees/cleanup.sh --auto tree2
"Directory not empty":
# Manually remove directory
rm -rf trees/tree2
# Then recreate worktree
bash .claude/scripts/create-worktrees/create.sh feature-name
Frontend (pnpm) issues:
# Manually install in worktree
cd trees/tree2/klair-client
pnpm install
Backend (uv) issues:
# Manually install in worktree
cd trees/tree2/klair-api
uv sync
Quick worktree without installation:
# Skip installation, install manually later
bash .claude/scripts/create-worktrees/create.sh feature-name --no-install
"Port already in use":
# start-services.sh will detect and offer to kill the process
# Or manually find and kill process:
lsof -ti:3002 | xargs kill -9 # Frontend
lsof -ti:5002 | xargs kill -9 # Backend
Check what's running on a port:
lsof -i:3002 # Check frontend port
lsof -i:5002 # Check backend port
API URL not updating:
# Manually update frontend .env
cd trees/tree2/klair-client
# Edit .env and update VITE_AI_ADOPTION_API_URL
Backend port not updating:
# Manually update backend .env
cd trees/tree2/klair-api
# Edit .env and update PORT
start-services.sh overwrites remote API URL:
"Worktree not found":
# Verify git version supports worktrees
git --version # Need 2.5+
# List all worktrees
git worktree list
# Prune stale worktree records
git worktree prune
"Branch not tracking remote":
# Set upstream tracking
cd trees/tree2
git branch --set-upstream-to=origin/tree2-feature-name
Environment not auto-loading:
# Allow direnv for worktree
cd trees/tree2
direnv allow
# Also allow subdirectories
direnv allow klair-api/
direnv allow klair-client/
Port variables not set:
# Check if direnv is working
cd trees/tree2
echo $KLAIR_FRONTEND_PORT # Should show 3002
echo $KLAIR_BACKEND_PORT # Should show 5002
# If empty, direnv may not be installed or configured
# Follow direnv setup in CLAUDE.md
# 1. Create worktree for new feature
bash .claude/scripts/create-worktrees/create.sh user-dashboard
# 2. Start services
cd trees/tree2
./start-services.sh 3002 5002
# 3. Develop and test at http://localhost:3002
# 4. Commit and push
git add .
git commit -m "Add user dashboard"
git push -u origin tree2-user-dashboard
# 5. Create PR
gh pr create --draft
# 6. After PR merged, clean up
bash .claude/scripts/create-worktrees/cleanup.sh --auto tree2 --update-main
# 1. Checkout existing branch in worktree
bash .claude/scripts/create-worktrees/create.sh --branch feature/analytics
# 2. Start services
cd trees/tree2
./start-services.sh 3002 5002
# 3. Test the feature at http://localhost:3002
# 4. Clean up when done
bash .claude/scripts/create-worktrees/cleanup.sh --auto tree2
# 1. Create first worktree with approach A
bash .claude/scripts/create-worktrees/create.sh approach-a
# 2. Create second worktree with approach B
bash .claude/scripts/create-worktrees/create.sh approach-b
# 3. Start services for both
cd trees/tree2 && ./start-services.sh 3002 5002 &
cd trees/tree3 && ./start-services.sh 3003 5003 &
# 4. Test both implementations
# - Approach A: http://localhost:3002
# - Approach B: http://localhost:3003
# 5. Choose best implementation and clean up
bash .claude/scripts/create-worktrees/cleanup.sh --auto tree3
# 1. Create worktree for main branch (uses dev API)
bash .claude/scripts/create-worktrees/create.sh --branch main
# 2. Services will use remote dev API
cd trees/tree2
./start-services.sh 3002 5002
# Frontend at :3002 calls https://dev-adoption-api.klairvoyant.ai/
# 3. Similarly for prod
bash .claude/scripts/create-worktrees/create.sh --branch prod
cd trees/tree3
./start-services.sh 3003 5003
# Frontend at :3003 calls https://adoption-api.klairvoyant.ai/
# New feature from main
bash .claude/scripts/create-worktrees/create.sh <feature-name>
# New feature from specific branch
bash .claude/scripts/create-worktrees/create.sh <feature-name> <base-branch>
# Existing branch
bash .claude/scripts/create-worktrees/create.sh --branch <branch-name>
# Quick setup (no install, no terminal)
bash .claude/scripts/create-worktrees/create.sh <feature-name> --no-install --no-terminal
# Full setup (all dependencies)
bash .claude/scripts/create-worktrees/create.sh <feature-name> --full
cd trees/tree2
./start-services.sh 3002 5002
# Interactive
bash .claude/scripts/create-worktrees/cleanup.sh
# Automated
bash .claude/scripts/create-worktrees/cleanup.sh --auto tree2
bash .claude/scripts/create-worktrees/cleanup.sh --auto tree2,tree3
bash .claude/scripts/create-worktrees/cleanup.sh --auto "*"
# With main update
bash .claude/scripts/create-worktrees/cleanup.sh --auto tree2 --update-main
# List all worktrees
git worktree list
# Remove worktree manually
git worktree remove trees/tree2 --force
# Prune stale worktrees
git worktree prune
.claude/scripts/create-worktrees/create.sh header comments.claude/scripts/create-worktrees/cleanup.sh header comments