Skip to main content
skill CX Codex

using-git-worktrees · osmontero — Claude Code skill for isolated work

The using-git-worktrees Claude Code skill sets up a separate Git worktree for a task. It kicks in before feature work or an implementation plan when the current checkout should stay untouched.

MIT 103 installs ★ 18 updated 2026-10-23

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add osmontero/opencode-skills --skill using-git-worktrees -a claude-code
Open on GitHub

What using-git-worktrees does

The skill creates an isolated checkout and moves the session into it. OpenCode v2 uses its built-in worktree tools; Claude Code, Codex, and a plain terminal use the git worktree add fallback.

A new worktree starts at detached HEAD, so the skill creates a branch inside it with git checkout -b. It runs the project’s baseline tests and reports failures. Dependencies are not shared with the main checkout, so project setup runs again based on files such as package.json or requirements.txt.

For a worktree placed inside the repository, its directory must be ignored by Git before creation. In OpenCode, the session switches with session_move, not shell cd; manually created worktrees are not tracked by OpenCode’s management tools.

What it helps with

  • isolate feature work from the main checkout
  • start an implementation plan without switching the primary workspace
  • create a branch inside a fresh worktree
  • run baseline tests in a clean checkout

Example prompts for the agent

  • Create a separate worktree for the authentication feature and move the session into it.
  • Set up an isolated checkout for the database migration plan.
  • Create a worktree for the login timeout fix and run the baseline tests.

How to install using-git-worktrees

1Skills CLI (Vercel)

npx skills add osmontero/opencode-skills --skill using-git-worktrees -a claude-code

2Manually: put the files in place

~/.claude/skills/using-git-worktrees/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/using-git-worktrees/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about using-git-worktrees

How do I install using-git-worktrees in Claude Code?

Run npx skills add osmontero/opencode-skills --skill using-git-worktrees -a claude-code. The skill file is at ~/.claude/skills/using-git-worktrees/SKILL.md.

What does using-git-worktrees do?

It creates a separate Git worktree and moves the session there, keeping the task apart from the main checkout. It also runs the project’s baseline tests.

Why does the worktree need a branch?

The new worktree is created at detached HEAD. The skill creates a branch inside it with git checkout -b <branch-name>.

Source text

SKILL.md · MIT
---
name: using-git-worktrees
description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates an isolated git worktree (via the native opencode v2 worktree tools) and moves the session into it
compatibility: opencode
---

# Using Git Worktrees

## Overview

Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.

**Core principle:** In opencode v2, worktrees are created with the native `worktree_*` tools, and the *session* moves into the worktree — not just the shell. This keeps opencode's tracking (list/remove), project config, and AGENTS.md discovery pointing at the right place.

**Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."

## Default Path: Native Worktree Tools

Use this when running inside opencode v2 (the normal case). The tools are `worktree_create`, `worktree_list`, `worktree_remove` (Code Mode namespace `opencode`), plus `session_move`.

### 1. Create the worktree

Call `worktree_create` with a `name` — use the feature/branch name (e.g. `auth`, `fix-login-timeout`). It returns `{ directory }`.

Where the worktree lands is decided by the `worktree.directory` setting in the project's opencode config, not by the skill:

- **Not set (default):** opencode's data directory, `worktree/<project-id prefix>/<name>` — outside the repo, so nothing to gitignore.
- **Set** (e.g. `"worktree": { "directory": ".worktrees" }`): relative paths resolve against the project's canonical checkout. If the directory is *inside* the repo, it must be gitignored (see below).

Do not hand-roll the location with `git worktree add` — opencode only records and manages worktrees it created itself, so manual ones are invisible to `worktree_list` / `worktree_remove`.

If the user wants a non-default location, the v2-idiomatic move is to set `worktree.directory` in the config (and note it in AGENTS.md or memory) — not to pick a path per session.

### 2. Create the branch

`worktree_create` does not take a branch name: the new worktree is at a **detached HEAD** on the repo's current commit. Create the branch from inside the worktree:

```bash
git checkout -b "<branch-name>"
```

(`git checkout main` would fail — main is already checked out in the primary worktree; that is expected and not an error.)

### 3. Move the session into the worktree

Call `session_move` with the worktree directory as `directory`. The move takes effect at a safe boundary, so destination-dependent work (reads, edits, setup commands) belongs in the next call.

**Why this instead of `cd`:** a shell `cd` only changes one command's working directory; `session_move` re-roots the session's Location, so tool calls, config discovery, and instruction files all resolve against the worktree checkout.

### 4. Project-local location safety (only if inside the repo)

When `worktree.directory` places worktrees inside the checkout (`.worktrees/`, `worktrees/`, …), verify the directory is ignored **before** creating the worktree:

```bash
git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
```

If not ignored: add it to `.gitignore`, commit, then create. This prevents worktree contents from polluting `git status` or being accidentally committed.

### 5. Run project setup

The worktree is a fresh checkout — dependencies are not shared with the main worktree. Auto-detect and run setup:

```bash
# Node.js
[ -f package.json ] && npm install

# Rust
[ -f Cargo.toml ] && cargo build

# Python
[ -f requirements.txt ] && pip install -r requirements.txt
[ -f pyproject.toml ] && poetry install

# Go
[ -f go.mod ] && go mod download
```

### 6. Verify clean baseline and report

Run the project's tests to confirm the worktree starts green:

```bash
# project-appropriate: npm test / cargo test / pytest / go test ./...
```

**If tests fail:** report the failures and ask whether to proceed or investigate. **If they pass:** report ready.

```
Worktree ready at <full-path> (branch <name>)
Session moved. Tests passing (<N> tests, 0 failures)
Ready to implement <feature-name>
```

## Cleanup

Pairs with **finishing-a-development-branch** after the work is done:

- `worktree_remove` with the worktree `directory` removes a worktree opencode recorded for the project. It uses the `edit` permission on that directory; set `force: true` only to discard uncommitted changes.
- Never remove a worktree with unpushed, unmerged commits without explicit confirmation — that deletes the work.
- A worktree created manually with raw git (fallback below) is not recorded by opencode; remove it with `git worktree remove <path>` instead.

## Fallback: Raw Git

Use `git worktree add` directly only when:

- Running in a harness without the native tools (Claude Code, Codex, plain terminal).
- The worktree needs a base other than the current HEAD (`git worktree add <path> -b <branch> <base-commit>`).
- The user explicitly asks for a manual worktree.

The same safety rules apply: gitignore check for project-local paths, setup, baseline tests, and announce the location.

## Quick Reference

| Situation | Action |
|-----------|--------|
| In opencode v2 | `worktree_create` → `git checkout -b` → `session_move` → setup → baseline |
| Non-default location wanted | Set `worktree.directory` in opencode config |
| Location inside repo | `git check-ignore` first; add to `.gitignore` + commit if not |
| Needs a base other than HEAD | Fallback: `git worktree add <path> -b <branch> <base>` |
| Tests fail during baseline | Report failures + ask |
| Work done | finishing-a-development-branch → `worktree_remove` |

## Common Mistakes

**Assuming `worktree_create` makes a branch**
- **Problem:** It leaves a detached HEAD; commits land nowhere a branch points at.
- **Fix:** `git checkout -b <branch>` inside the worktree immediately after creation.

**`cd`-ing into the worktree instead of `session_move`**
- **Problem:** Only the shell's CWD changes; the session, config, and instruction discovery still point at the old location.
- **Fix:** Call `session_move`; put dependent work in the next turn.

**Hand-rolling `git worktree add` in opencode**
- **Problem:** opencode doesn't record manual worktrees, so `worktree_list`/`worktree_remove` can't see them, and the location ignores `worktree.directory`.
- **Fix:** Use the native tools in v2; raw git is the fallback above.

**Proceeding with failing baseline tests**
- **Problem:** Can't distinguish new bugs from pre-existing issues.
- **Fix:** Report failures, get explicit permission to proceed.

## Red Flags

**Never:**
- Commit on the detached HEAD (create the branch first)
- Remove a worktree with unpushed/unmerged work without confirmation
- Skip baseline test verification
- Assume the default location when the user has a project-local preference — check/set `worktree.directory`

**Always:**
- Use native tools in opencode v2, raw git only in the fallback cases
- Move the session with `session_move` after creation
- Verify gitignore for in-repo locations
- Auto-detect and run project setup, then a clean test baseline

## Example Workflow

```
You: I'm using the using-git-worktrees skill to set up an isolated workspace.

[worktree_create name="auth" -> C:\Users\osmon\.local\share\opencode\worktree\c3488b\auth]
[git checkout -b feature/auth]
[session_move directory=<worktree dir>]
[npm install, npm test - 47 passing]

Worktree ready at C:\Users\osmon\.local\share\opencode\worktree\c3488b\auth (branch feature/auth)
Session moved. Tests passing (47 tests, 0 failures)
Ready to implement auth feature
```

## Integration

**Called by:**
- **subagent-driven-development** - REQUIRED before executing any tasks
- **executing-plans** - REQUIRED before executing any tasks
- Any skill needing an isolated workspace

**Pairs with:**
- **finishing-a-development-branch** - REQUIRED for cleanup after work complete

© osmontero · MIT · osmontero/opencode-skills

Similar skills

All skills for Git and GitHub →

using-git-worktrees by other authors comes first.

using-git-worktrees Jesse Vincent using-git-worktrees prepares an isolated workspace before feature work or plan execution. It checks the repository first, then uses native worktree support or Git. CX Codex +1 217,153installs using-git-worktrees julianobarbosa using-git-worktrees creates a git worktree under .claude/worktrees/, opens it in a tmux window of the current session and sends the task there. CX Codex +1 106installs using-git-worktrees GanyuanRan using-git-worktrees — a Claude Code skill that decides whether a git worktree is actually needed before creating one. It checks repository state and only adds a checkout when a concrete conflict exists. CX Codex +1 ★ 1,450repo stars git-worktrees jamesrochabrun git-worktrees is a Claude Code skill for running parallel sessions on separate branches without conflicts. It provides scripts to create, manage, and clean up isolated worktrees. CX Codex +1 135installs parallel-worktrees Rohit Ghumare parallel-worktrees — a skill for Claude Code that creates isolated git worktrees for parallel coding sessions. While tests or builds run in one window, start a new task in another without waiting or switching context. CX Codex +1 ★ 2,966repo stars create-worktrees davila7 create-worktrees — a command for Claude Code fetches all open PRs through GitHub CLI and creates a git worktree for each branch in ./tree/<BRANCH_NAME>. Multiple PRs can be reviewed or worked on in parallel, each in its own directory. CX Codex +1 351installs git-workflow-and-versioning addyosmani git-workflow-and-versioning — a skill that structures git discipline: atomic commits, short-lived branches, messages that explain why. It activates whenever the agent prepares any code change for commit. CX Codex +1 75,700installs git-worktree-isolation sentimony git-worktree-isolation evaluates code change risks and picks a safe workspace before editing files. It prevents overwriting user progress during multi-file edits or parallel runs. CX Codex +1 2,300installs git-merge-expert-worktree ulpi-io git-merge-expert-worktree — a Claude Code skill that runs merges and conflict resolution inside a dedicated git worktree. The main tree stays clean, and the skill handles its own cleanup when the operation finishes. CX Codex +1 159installs

From the same set11

The whole set →
reviewing-interface-quality reviewing-interface-quality audits an existing interface with screenshots, browser data, and CSS values. Use it before shipping or when a page feels unfinished. CX Codex +1 451installs testing-webapps testing-webapps lets an agent test your local web app in a real browser: it writes a Python Playwright script, starts the servers, and reports what the page actually does. CX Codex +1 192installs reviewing-security The reviewing-security skill reviews code before a merge or release by tracing attacker-controlled input to the operation and impact it can reach. CX Codex +1 185installs investigating-performance investigating-performance stops coding agents from guessing at performance bottlenecks by enforcing strict baselines, target metrics, and dimensioned profiling before touching code. CX Codex +1 146installs applying-themes applying-themes puts one palette of eight semantic tokens on a deck, report or HTML page, then verifies the contrast with a bundled script. CX Codex +1 139installs evolving-apis-and-schemas The evolving-apis-and-schemas Claude Code skill assesses changes to APIs and data schemas. It activates when other services, clients, or stored data depend on the shape being changed. CX Codex +1 115installs executing-plans The executing-plans Claude Code skill carries out a written implementation plan in stages, with checks between batches. It activates when subagents cannot be used or tasks are too coupled to split up. CX Codex +1 107installs creating-skills The creating-skills Claude Code skill helps create and revise other skills, then test how they perform. It activates for requests to draft a skill, evaluate its results, or adjust its trigger description. CX Codex +1 101installs

Project sponsors

Companies that keep this analytics open