Skip to content

oprogramadorreal/optimus-claude / skills/worktree

worktree

Verified

Creates 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.

FileKindSize
README.mdmarkdown2.9 KB
SKILL.mdskill md3.1 KB
agents/openai.yamlconfig198 B
references/worktree-setup.mdmarkdown3.5 KB
# 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)
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall