{"id":29247737,"url":"https://github.com/agenttools/worktree","last_synced_at":"2025-08-31T10:32:38.490Z","repository":{"id":301964469,"uuid":"1010796547","full_name":"agenttools/worktree","owner":"agenttools","description":"CLI tool for managing Git worktrees with GitHub issues and Claude Code integration","archived":false,"fork":false,"pushed_at":"2025-06-29T21:15:10.000Z","size":72,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-29T05:51:48.789Z","etag":null,"topics":["claude","cli","developer-tools","git","github","productivity","tmux","worktree"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@agenttools/worktree","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/agenttools.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-29T20:22:26.000Z","updated_at":"2025-07-25T12:16:41.000Z","dependencies_parsed_at":null,"dependency_job_id":"2d8ed149-f144-4d4e-aa42-46c35075592d","html_url":"https://github.com/agenttools/worktree","commit_stats":null,"previous_names":["agenttools/worktree"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/agenttools/worktree","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agenttools%2Fworktree","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agenttools%2Fworktree/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agenttools%2Fworktree/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agenttools%2Fworktree/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agenttools","download_url":"https://codeload.github.com/agenttools/worktree/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agenttools%2Fworktree/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272971379,"owners_count":25024092,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-31T02:00:09.071Z","response_time":79,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude","cli","developer-tools","git","github","productivity","tmux","worktree"],"created_at":"2025-07-04T00:01:41.887Z","updated_at":"2025-08-31T10:32:38.483Z","avatar_url":"https://github.com/agenttools.png","language":"TypeScript","readme":"# Worktree CLI\n\nA powerful CLI tool for managing Git worktrees with GitHub issues and Claude Code integration. Create isolated workspaces for each issue with automatic context loading, tmux session management, and support for multiple Claude workers collaborating on the same issue.\n\n## Features\n\n- 🌳 **Git Worktree Management** - Create isolated branches and directories per issue\n- 🐙 **GitHub Integration** - Fetch issue details automatically\n- 🤖 **Claude Code Integration** - Auto-launch Claude with issue context\n- 🖥️ **tmux Session Management** - Organized windows and panes per issue\n- 📝 **Contextual Documentation** - Auto-generated CLAUDE.md with project info\n- ⚡ **Smart Commands** - Quick access to development commands\n- 👁️ **Progress Monitoring** - Optional overseer worker that tracks progress\n- 🎭 **Coding Agent Archetypes** - Assign specialized roles to multiple workers\n\n## Prerequisites\n\n- Git\n- tmux\n- iTerm2 (macOS)\n- GitHub CLI (`gh`) - Install with `brew install gh`\n- Claude Code CLI (`claude`)\n\n## Installation\n\n```bash\nnpm install -g @agenttools/worktree\n```\n\nOr clone and link locally:\n\n```bash\ngit clone https://github.com/agenttools/worktree\ncd worktree-cli\nnpm install\nnpm run build\nnpm link\n```\n\n## Usage\n\n### Initialize Configuration\n\nIn your Git repository:\n\n```bash\nworktree init\n```\n\nThis creates `.worktree.yml` with auto-detected project settings.\n\n### Create/Open Worktree\n\n```bash\n# Create worktree for issue #123\nworktree open 123\n\n# With description for better branch naming\nworktree open 123 \"add-authentication\"\n# Creates branch: issue-123-add-authentication\n\n# With multiple Claude workers (2-5)\nworktree open 123 -w 3\n# Spawns 3 Claude instances with coordination\n\n# With an overseer worker\nworktree open 123 --watcher\n# Adds an overseer that monitors progress every 60 seconds\n\n# Combine multiple workers with overseer\nworktree open 123 -w 3 --watcher\n# 3 workers + 1 overseer monitoring them\n```\n\n### Split Pane\n\nWhen you need additional Claude instances for the same issue:\n\n```bash\n# Split horizontally (default)\nworktree split 123\n\n# Split vertically\nworktree split 123 -v\n```\n\n**Note:** Consider using `worktree open -w \u003cnumber\u003e` for coordinated multi-worker setups.\n\n### List Worktrees\n\n```bash\nworktree list\n```\n\nShows all worktrees with:\n- Issue number and branch name\n- tmux window status\n- Last modified time\n- Number of panes\n\n### Remove Worktree\n\n```bash\nworktree remove 123\n# or\nworktree rm 123\n```\n\nCloses tmux window and removes Git worktree.\n\n## Configuration\n\nEdit `.worktree.yml` in your repository:\n\n```yaml\nname: \"My Project\"\nsession: \"myproject_workers\"\nclaude_context: |\n  This is a Next.js app with TypeScript.\n  Key areas:\n  - src/app - App router pages\n  - src/lib - Utilities and actions\n  \ncommands:\n  dev: npm run dev\n  test: npm test\n  lint: npm run lint\n  typecheck: npm run typecheck\n  \nsetup_commands:\n  - npm install\n```\n\n## How It Works\n\n1. **Validates GitHub issue** - Ensures issue exists before creating worktree\n2. **Creates Git worktree** - Isolated directory with new branch\n3. **Fetches GitHub issue** - Gets title, body, labels via `gh` CLI\n4. **Generates context files**:\n   - **CLAUDE.md** - Issue details and project context for all workers\n   - **WORKTREE_COORDINATION.md** - Task coordination for multi-worker setups\n   - **OVERSEER.md** - Progress tracking and recommendations (when --watcher used)\n5. **Launches Claude Code** - In tmux window/pane with working directory set\n6. **Auto-sends prompts**:\n   - Single worker: \"Solve the issue described in CLAUDE.md\"\n   - Multiple workers: Role-specific prompts for coordination\n\n## tmux Commands\n\n- **List windows**: `Ctrl+B, w`\n- **Switch window**: `Ctrl+B, [0-9]`\n- **Detach session**: `Ctrl+B, d`\n- **Reattach**: `tmux attach -t \u003csession-name\u003e`\n\n## Example Workflows\n\n### Single Worker\n```bash\n# Start working on issue #42\nworktree open 42 \"fix-login-bug\"\n\n# Claude opens and starts working...\n# Need to check something else? Split the pane\nworktree split 42\n\n# See all your worktrees\nworktree list\n\n# Done with the issue?\nworktree rm 42\n```\n\n### Multiple Workers\n```bash\n# Complex issue requiring collaboration\nworktree open 78 \"refactor-api\" -w 3\n\n# Skip archetype wizard and use defaults\nworktree open 78 \"refactor-api\" -w 3 --no-wizard\n\n# Creates 3 Claude instances:\n# - Worker 1: Coordinator, creates task breakdown\n# - Worker 2: Select archetype via wizard (or default: Detective)\n# - Worker 3: Select archetype via wizard (or default: Craftsman)\n\n# Workers coordinate through WORKTREE_COORDINATION.md\n```\n\n## Agent Archetypes\n\nWhen using multiple workers, you can assign specialized roles:\n\n- 🏗️ **The Architect** - System design \u0026 architecture patterns\n- 🔍 **The Detective** - Debugging, edge cases \u0026 security\n- 🛠️ **The Craftsman** - Code quality \u0026 best practices\n- 🚀 **The Explorer** - Innovation \u0026 alternative approaches\n- 🎨 **The Aesthete** - Elegant solutions \u0026 simplicity\n\n### Interactive Wizard Example\n\n```bash\n$ worktree open 123 -w 3\n\nCreating worktree for issue #123...\n✓ Worker 1 (Coordinator) assigned\n\nSelect archetype for Worker 2:\n1) 🏗️  The Architect - System design \u0026 architecture\n2) 🔍  The Detective - Debugging \u0026 edge cases\n3) 🛠️  The Craftsman - Code quality \u0026 best practices\n4) 🚀  The Explorer - Innovation \u0026 alternatives\n5) 🎨  The Aesthete - Elegant solutions \u0026 simplicity\nChoice (1-5): 2\n\n✓ Worker 2 assigned as The Detective\n\nSelect archetype for Worker 3:\n...\n```\n\n## Tips\n\n- Run `worktree init` in each repository to customize settings\n- Use descriptive names with `worktree open` for better branch names\n- For complex issues, use `-w` flag to spawn coordinated workers\n- Choose complementary archetypes for better problem-solving coverage\n- Use `--no-wizard` to skip archetype selection and use defaults\n- Multiple Claude instances can work on different aspects of the same issue\n- Both CLAUDE.md and WORKTREE_COORDINATION.md are automatically added to .gitignore\n- Workers communicate through the coordination document to avoid conflicts\n- Add `--watcher` for an overseer that monitors progress\n\n## License\n\nMIT","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagenttools%2Fworktree","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagenttools%2Fworktree","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagenttools%2Fworktree/lists"}