worktree

Worktree Manager

Disclaimer: This software is provided "as is", without warranty of any kind. See LICENSE for full terms.

For AI Agents: Setting up worktree-manager for a new project? See SKILL.md for comprehensive AI-friendly setup guidance with configuration wizards and decision trees.

Motivation

A CLI tool for managing multiple git worktrees with coordinated Docker environments and dynamic port allocation.

This is not a replacement of your setup of Git worktrees, OpenClaw or Vibe-Kanban. It is meant to extend it.

Keep your main .git repo for hotfixes and code reviews. Configure, run and develop 1-N features separately with your preferred tooling in git worktrees. It is meant for humans when you want develop N features/fixes simultaneously, but it can be used as tool for agents.

How it works

Simply configure your needs, wrapping git worktrees, allocating ports, setting correct ENVironment and executing pre-command, command, post-command to manage multiple git worktrees environments.

Quick Start

For AI Agents: See SKILL.md for step-by-step configuration wizard and decision trees.

For Humans:

1. Install

Option 1: Go Install (Recommended)

go install github.com/braunmar/worktree@latest

Option 2: Download Release

Download the latest binary from GitHub Releases.

Option 3: Build from Source

make build
make install

2. Create Configuration

Create a .worktree.yml file in your project root. See .worktree.example.yml for a complete example or real project configuration .worktree.example-real.yml.

3. Create Your First Feature

worktree new-feature feature/my-feature

That's it! The tool will create worktrees, allocate ports, and start services.

Common Commands

worktree list                    # List all features
worktree start <feature-name>    # Start a feature
worktree stop <feature-name>     # Stop a feature
worktree remove <feature-name>   # Remove a feature
worktree doctor                  # Check health

Documentation

Getting Started

New to worktree-manager? Start with a hands-on example:

• Fullstack Docker Guide - Frontend + Backend with Docker Compose ⭐ Most Common
  • Learn the ${APP_PORT:-8080} pattern
  • Set up multi-repo structure
  • Run multiple instances without port conflicts
• All Examples - Browse all examples (minimal → production)

Configuration Reference

• Docker Port Patterns - How to integrate with Docker Compose ⭐
• Complete Config - All options documented
• Real Project Config - Production setup

Guides

• Migration Guide - From hardcoded ports to dynamic allocation

Developer Reference

• Architecture - For contributors and AI agents
• AI Agent Setup - Configuration wizard for AI agents

Installing as a Claude Code Skill

You can expose this SKILL.md as a /worktree slash command in Claude Code so any session can trigger the setup wizard or debug workflow without manually loading this file.

Install the skill:

# Create skill directory in your project's .claude folder
mkdir -p .claude/skills/worktree
# Copy the companion skill wrapper from the worktree-manager repo
curl -fsSL "https://raw.githubusercontent.com/braunmar/worktree/main/.claude/skills/worktree/SKILL.md" \
  -o .claude/skills/worktree/SKILL.md

After a restart Claude Code will auto-discover the skill and make /worktree available as a tab-completable slash command in the session.

Usage after installation:

# Initial setup — wizard asks questions and writes .worktree.yml
/worktree

# Debug a specific problem — routes to Section 7 diagnostics
/worktree "I think docker @example-project/docker-compose.yml is not correct"
/worktree "port 8081 is already in use when I run new-feature"
/worktree "worktree list shows stale entries after I deleted the branch"

TODO

Simple agents workflow configuration is on the roadmap, it is meant to run simple agents for simple needs like housekeeping jobs (npm audit, security audit, code coverage, ...). This feature MAY or MAY NOT be separated in the future. You can experiment and help to evolve it.

• Battletest simple agents setup
• Review Github actions
• Review SKILL.md, its very helpfull, but not good enought

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

Security

To report a vulnerability, see SECURITY.md. Do not open public issues for security problems.

Code of Conduct

This project follows the Code of Conduct. By participating, you agree to uphold it.

License

MIT License — see LICENSE.