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
npx skills add osmontero/opencode-skills --skill using-git-worktrees -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/using-git-worktrees/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/using-git-worktrees/
1Skills CLI (Vercel)
npx skills add osmontero/opencode-skills --skill using-git-worktrees -a codex2Manually: put the files in place
.agents/skills/using-git-worktrees/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add osmontero/opencode-skills --skill using-git-worktrees -a cursor2Manually: put the files in place
.cursor/skills/using-git-worktrees/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install osmontero/opencode-skills skills/using-git-worktrees2Manually: put the files in place
.github/skills/using-git-worktrees/SKILL.md1Skills CLI (Vercel)
npx skills add osmontero/opencode-skills --skill using-git-worktrees -a gemini-cli2Platform CLI
gemini skills install https://github.com/osmontero/opencode-skills --path skills/using-git-worktreesManually: put the files in place
.devin/skills/using-git-worktrees/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add osmontero/opencode-skills --skill using-git-worktrees -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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.