worktree
Skill4 starsChanged 57 days agoApache-2.0View on GitHub
Decide whether a unit of agent work needs its own git worktree, then create, use, and remove it with Rust build isolation. Use when starting work on an issue, running parallel agents, or cleaning up after a run.
60 other projects use a version of this.
Adopted by
Most recently taken up by
- oberemokis/skillstheir own version, first seen Nov 15, 2026
- kortix-ai/sunatheir own version, first seen Nov 15, 2026
- Significant-Gravitas/AutoGPTtheir own version, first seen Nov 14, 2026
- venhdev/skillstheir own version, first seen Nov 8, 2026
- domengabrovsek/agent-configtheir own version, first seen Nov 8, 2026
- domengabrovsek/claudetheir own version, first seen Nov 8, 2026
Used with
Projects with it also use worktree-merge, resolve-conflicts and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
leessjuSkillworktree-merge
Squash-merge the current worktree branch into the main branch (or a specified target). Analyzes git history and source code to craft a comprehensive commit message.
Also in 3 projects that use this
ralphkraussSkillresolve-conflicts
Resolve git merge conflicts or re-apply changes from a stale branch onto current main. Use when user says "resolve conflicts", "merge conflicts", "rebase branch", "branch is behind", "re-apply changes", "port branch", or a branch is too far behind main to merge cleanly.
Also in 5 projects that use this
SentrySkille2e
Run E2E tests for Sentry JavaScript SDK test applications
Also in 5 projects that use this
hdcolaSkillpr-comments
Fetch unresolved review comments from a GitHub PR or mark comments as resolved. Use this when managing PR review feedback, checking pending comments, or marking review threads as resolved. Supports GitHub URLs or explicit owner/repo/PR-number from anywhere, or PR number auto-detection from within a git repository.
Also in 3 projects that use this
Google CloudSkillcontributing
Guides the developer workflow for contributing to Race Condition. Use when setting up pre-commit hooks, running tests before a PR, understanding code style requirements, or preparing a contribution.
Also in 3 projects that use this
PydanticSkillcoverage
Fetch coverage diff from Codecov for the current branch or a specific PR. Shows uncovered lines, patch coverage, and overall coverage change.
Also in 3 projects that use this
Other versions60 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 60
- Significant-Gravitas/AutoGPT★ 188ksame name
- kortix-ai/CompanyOS★ 21ksame name
- kortix-ai/suna★ 21ksame name
- gitkraken/vscode-gitlens★ 10ksame name
- Zipstack/unstract★ 7.5ksame name
- mistralai/mistral-vibe★ 5.4ksame name
- nubjs/nub★ 4.4ksame name
- raine/workmux★ 3ksame name
- astashov/liftosaur★ 775same name
- nudgebee/nudgebee★ 525same name
50 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository14 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- commits-and-prsSkill
- decomposeSkill
- github-boardSkill
- implementSkill
- releaseSkill
- reviewSkill
- reviseSkill
- rubber-duckSkill
- specifySkill
- thunderstormSkill
- triageSkill
- writing-docsSkill
The file
We split this skill into the rules it gives an agent
3 rules. 0 are common, 1 is distinctive, and 2 are very specific to this project.
0
Common
Most of the 47 edited versions we read keep these.
1
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 70
Always outside the repository root.
- Distinctive: line 114
Never copy ignored files as a group.
- Very specific: line 133
Run the middle line once the pull request has merged.
“Common” is measured: kept by at least 6 in 10 of the 47 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Worktree
One unit of work gets one branch and one owner. Whether it also gets its own
worktree is decided under Who gets one, and this skill is the
only thing in the repository that makes one. check-isolation.py holds that in
CI.
Who gets one
What a worktree separates is one writer from the next, so the question is whether this work has a next writer.
| Writer | Tree |
| A dispatched subagent | Its own worktree, made before it is sent. |
| A local session, directly | Its own worktree. The checkout is the user's. |
| A cloud session, directly | A branch in the container checkout. |
A subagent always has one. The session that dispatched it still sits in the checkout, and it can send a second subagent while the first works. So a subagent is never the only writer, even when it is the only implementer.
Two of them in one checkout share one index and one HEAD, so neither can hold
a branch. The second to create its branch moves HEAD for both. The first's
staged work lands in the second's commit, its later commits land on the second's
branch, and its own branch never leaves origin/edge. Git refuses one branch in
two worktrees, but that refusal needs two worktrees to fire.
The run creates it before dispatching rather than leaving the subagent to. A subagent making its own would place it relative to whatever directory it started in, and that directory is recorded nowhere the run can read afterwards.
.claude/.gitignore keeps a worktree that lands at .claude/worktrees/ out of
the checkout's status, so one made by mistake does not also read as dirty.
Two things here are still rules a reader has to follow, because both are decided at runtime and recorded nowhere the tree can read:
- An
isolationargument on a dispatch. The check reads the text a dispatch would be copied from, so it catches the setting written into a definition or a code block. A run that passes the argument without that text existing anywhere gets the harness worktree and nothing notices. Pass noisolationon an Agent call, whatever a prompt asks for. - The directory a dispatched subagent writes into. It starts in the run's checkout and stays there unless it changes directory. Compare the paths the subagent reports touching against the directory the run handed it before believing the worktree was used.
A session working an issue itself on a development machine takes one too. The checkout there is the user's working tree and an agent is never its writer.
The one case with no worktree is a cloud session working an issue itself, where
the container checkout belongs to nobody else. A second tree there costs three
things and buys nothing. It is untracked inside the repository root, so the
checkout reads dirty. The stop hook then asks for a locked second checkout to be
committed. Cargo can reach the parent .cargo/config.toml and build into the
parent target/. That session still owns its branch: rename a harness-supplied
name to agent/<issue> before the first push.
A reviewer needs no worktree, only a tree that does not move while it reads,
which is a commit. The review skill owns how to read one.
Create
Always outside the repository root. A worktree created inside it inherits the
parent .cargo/config.toml, and Cargo can then build into the parent target/:
git fetch origin
git worktree add ../thndrs-worktrees/<issue> -b agent/<issue> origin/edgeBranch from origin/edge, not from whatever the user has checked out. The
baseline should match the branch the pull request will target.
Work with no issue behind it still branches under agent/, named for the work:
agent/git-hygiene. A worktree made here is born with the right name and needs
no rename.
Build isolation
Each worktree keeps its own target/. Do not set a shared CARGO_TARGET_DIR.
Cargo takes an exclusive lock on the build directory, so a shared one serializes
the builds it was supposed to parallelize, and differing feature resolution
across branches invalidates the shared incremental state.
Share compilation through a content-addressed cache instead, when it is installed:
command -v sccache >/dev/null && export RUSTC_WRAPPER=sccacheSymptoms of a shared-target misconfiguration look like compiler bugs: builds that restart from scratch, test binaries that vanish between runs, and errors that do not reproduce. Check target isolation before anything else.
Provisioning
Untracked files do not follow a worktree. Copy only what the build needs, by name:
for file in .thndrs/config.toml; do
test -f "$file" && install -D "$file" "../thndrs-worktrees/<issue>/$file"
doneNever copy ignored files as a group. That is how credentials end up in directories nobody is tracking.
Concurrency
Cap concurrent worktrees at 2 on a development machine. Parallel Rust builds, language servers, and test processes exhaust memory before they exhaust CPU. Raise the cap only after measuring.
Remove
Removal is part of the run, not cleanup for later:
git worktree remove ../thndrs-worktrees/<issue>
git branch -d agent/<issue> # a run that took no worktree runs this line alone
git worktree pruneRun the middle line once the pull request has merged. git worktree remove
fails with not a working tree where there was none, so a run working in a
container checkout skips the first and third.
remove refuses to discard uncommitted changes. Treat that refusal as an
escalation: inspect what is there and report it. Do not pass --force to get
past work the run never reported.
Inspect
git worktree listA worktree whose issue is no longer status:claimed is stale. Remove it after
confirming it holds nothing uncommitted.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

