git-worktree-manager

What This Skill Does

The git-worktree-manager is a robust engineering tool designed to streamline parallel development by automating the Git worktree lifecycle. Instead of manually stashing changes or switching branches, which can lead to rebuilds and context loss, this skill allows you to maintain multiple independent directory trees for the same repository. It handles the heavy lifting of branch creation, environment synchronization, dependency installation, and, most importantly, automatic port allocation. By assigning non-conflicting ports to each worktree, it ensures that your services (like databases, Redis, or web servers) do not crash due to port binding collisions when running multiple instances simultaneously.

Installation

To integrate this into your workflow, execute the following command in your terminal: clawhub install openclaw/skills/skills/alirezarezvani/git-worktree-manager Ensure you have Python 3.x installed, as the utility leverages Python scripts for orchestrating Git commands and managing the port mapping registry.

Use Cases

• Parallel Feature Development: Simultaneously work on a feature branch, a hotfix, and a chore branch without interrupting local build states.
• PR Validation: Quickly spin up a pristine environment for a pull request to test changes without affecting your current primary work branch.
• Multi-Agent Orchestration: Ideal for team settings where multiple AI agents or developers need to operate within the same repository structure without interfering with each other's local environment configurations or service ports.
• Clean Lifecycle Management: Automated cleanup processes identify stale or merged branches to reclaim disk space and remove unused port allocations.

Example Prompts

1. "Create a new worktree named 'wt-login-fix' for branch 'fix/login-bug' based on main, and install all necessary dependencies."
2. "Cleanup all my stale worktrees that are older than 14 days and have already been merged into the main branch."
3. "List all active worktrees and show me the port mapping configuration for my current project."

Tips & Limitations

• Port Strategy: The tool defaults to a base + (index * stride) approach. Ensure your applications are configured to respect these dynamic port assignments, ideally via environment variables generated by the manager.
• Resource Usage: Remember that each worktree is a full directory instance. While they share the underlying Git object database, running multiple services (Docker containers, databases) can significantly consume CPU and RAM.
• Cleanup Safety: Always review the output of the cleanup command before proceeding. While it detects merged branches, it is wise to manually verify critical unmerged work before allowing the tool to force-delete directories.