oprogramadorreal/optimus-claude / skills/worktree
worktree
VerifiedCreates a git worktree for isolated parallel development — new branch in a separate directory with project setup and test baseline. Enables multiple Claude Code sessions on different tasks simultaneously. May append .worktrees/ to .gitignore (left unstaged); never commits or pushes. Multi-repo aware. Use when you need to work on something else without disturbing current work.
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 2.9 KB |
| SKILL.md | skill md | 3.1 KB |
| agents/openai.yaml | config | 198 B |
| references/worktree-setup.md | markdown | 3.5 KB |
README.md
View on GitHub# optimus:worktree
A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) skill that creates a git worktree for isolated parallel development — a new branch in a separate directory (`.worktrees/`) with project setup and a test baseline. The main workspace stays on its original branch, so each worktree can host an independent Claude Code session.
## Features
- **Isolated parallel development** — each worktree is a separate directory with its own branch
- **Automatic project setup** — detects and runs the project's setup command (npm install, pip install, etc.) inside the new worktree
- **Test baseline** — runs the test suite in the worktree; pre-existing failures are reported, never blocking
- **Conventional branch naming** — `<type>/<slugified-description>`, consistent with other optimus skills
- **Recursive worktree guard** — refuses to create a worktree from inside another worktree
- **Multi-repo workspace support** — targets a specific repo in multi-repo setups
VSCode 1.103+ discovers worktrees natively: open one from the Source Control panel (right-click → "Open Worktree in New Window") or with `code .worktrees/<worktree-dir>`.
## Quick Start
This skill is part of the [optimus](https://github.com/oprogramadorreal/optimus-claude) plugin. See the [main README](../../README.md) for installation instructions.
## Usage
- `/optimus:worktree` — asks what you will work on, then creates the worktree
- `/optimus:worktree "fix login timeout"` — uses the provided description directly
Example:
```
> /optimus:worktree "fix login timeout"
## Worktree Created
Working directory: `.worktrees/fix-login-timeout`
Branch: `fix/login-timeout` (from `main`)
Main workspace: `main` (unchanged)
Tests: passing
Open it: `code .worktrees/fix-login-timeout` (VSCode), or start a new session of the current coding agent in that directory.
Cleanup when done: `git worktree remove .worktrees/fix-login-timeout`
```
## When to Use
- Parallel Claude Code sessions on different tasks
- An urgent fix without stashing or disturbing work in progress
- Reviewing or experimenting in isolation — delete the worktree when done
## When NOT to Use
- **Just need a branch** — use `/optimus:commit branch` for a quick branch without a separate directory or setup
- **Starting TDD** — `/optimus:tdd` offers worktree isolation as part of its workflow
- **Single-task work** — a regular branch is simpler
## Skill Structure
| File | Purpose |
|---|---|
| `SKILL.md` | Skill definition |
| `references/worktree-setup.md` | Shared setup, failure handling, and cleanup procedure (also consumed by `tdd`) |
| *(shared)* `init/references/multi-repo-detection.md` | Multi-repo workspace detection |
| *(shared)* `commit/references/branch-naming.md` | Branch naming convention |
## Requirements
- Optimus installed in a [supported host](../../README.md#supported-hosts-and-versions)
- Git 2.5+ (worktree support)
## License
[MIT](../../LICENSE)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |