Wt

wt - Worktree Manager Skill

Manages isolated LlamaFarm development environments using git worktrees. Each worktree has its own services, ports, and data directories - enabling parallel agent sessions without conflicts.

Full Documentation

For complete documentation, architecture details, and advanced usage: @scripts/wt/README.md

---

Quick Reference

---

When to Use wt

Use wt when:

• Starting isolated work on a feature/task that needs running services
• Running parallel coding sessions (multiple agents or terminals)
• Testing changes without affecting the main development environment
• Avoiding port conflicts between concurrent LlamaFarm instances

---

Common Workflows

Starting a New Task

# Create isolated environment with services running
wt create --go feat/my-task

# Work in the worktree...
# Services are already running on auto-assigned ports

# Check status anytime
wt status

# View logs if needed
wt logs server

Checking What's Running

# List all worktrees with their port assignments
wt list

# Example output:
# NAME              STATUS    SERVER   DESIGNER  RUNTIME
# feat-my-task      running   8150     5150      11150
# fix-bug           stopped   8234     5234      11234

Cleaning Up

# Stop services and remove a worktree
wt delete feat-my-task

# Remove data for worktrees that no longer exist
wt gc

# Remove worktrees for branches merged to main
wt prune

Troubleshooting

# Diagnose common issues (ports, stale PIDs, missing tools)
wt doctor

# Restart stuck services
wt stop && wt start

# Force delete if normal delete fails
wt delete my-worktree --force

---

Service URLs

Each worktree gets unique ports. Check URLs with:

wt url
# Outputs:
#   Server:   http://localhost:8150
#   Designer: http://localhost:5150
#   Runtime:  http://localhost:11150

If the Caddy proxy is running, use port-free URLs:

http://server.feat-my-task.localhost
http://designer.feat-my-task.localhost

---

Key Environment Details

• Worktrees location: ~/worktrees/llamafarm/
• Data directories: ~/.llamafarm/worktrees/<name>/
• Port allocation: Deterministic hash of worktree name (14345+offset, 5000+offset, 11000+offset)
• Logs: ~/.llamafarm/worktrees/<name>/logs/

---

Notes for the Agent

1. Always use `wt create --go` when setting up a new task environment - it handles everything (branch, deps, build, services) 2. Check `wt list` first before creating a new worktree to see what already exists 3. Use `wt status` to verify services are healthy before running tests or making API calls 4. Run `wt doctor` when encountering unexplained service issues 5. Clean up with `wt delete` when a task is complete to free resources