Skip to content

docs: add uv cache lock contention handling to worktree skill #500

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Aureliolo merged 3 commits into from
Mar 16, 2026
Merged

docs: add uv cache lock contention handling to worktree skill #500

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
af873fa
docs: add uv cache lock contention handling to worktree skill
Aureliolo Mar 16, 2026
9f532e8
Merge branch 'main' into chore/update-worktree-skill
Aureliolo Mar 16, 2026
be95333
fix: address PR review feedback on worktree skill
Aureliolo Mar 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .claude/skills/worktree/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -137,6 +137,14 @@ Directory suffix is auto-derived from the branch name:
for f in .claude/*.local.*; do test -f "$f" && cp "$f" "<dir-path>/.claude/$(basename "$f")"; done
```

d. **Pre-sync the venv** to prevent uv cache lock contention when multiple Claude Code instances run concurrently. `uv` uses a global cache lock (`$LOCALAPPDATA/uv/cache/.lock` on Windows, `$HOME/.cache/uv/.lock` on Linux, `~/Library/Caches/uv/.lock` on macOS) — if multiple worktrees run `uv run`/`uv sync` simultaneously, they serialize on this lock and all appear to hang. Pre-syncing sequentially here avoids this:

```bash
cd <dir-path> && uv sync; cd -
```

Run these **sequentially** (one per worktree, not in parallel) to avoid cache lock contention during setup itself.

4. **Verify all worktrees created:**

```bash
Expand Down Expand Up @@ -450,6 +458,7 @@ Update all worktrees to latest main. Pulls main first, then rebases clean worktr
- Owner/repo (from `git remote`): must match `^[a-zA-Z0-9._-]+/[a-zA-Z0-9._-]+$`
- Directory paths: must not contain shell metacharacters (`;`, `|`, `&`, `$`, `` ` ``, `(`, `)`)
- Reject and warn if any value fails validation — do not execute the command.
- **uv cache lock contention:** `uv` uses a global cache lock file (`$LOCALAPPDATA/uv/cache/.lock` on Windows, `$HOME/.cache/uv/.lock` on Linux, `~/Library/Caches/uv/.lock` on macOS). When multiple worktrees run `uv run` or `uv sync` concurrently, they serialize on this lock, causing all instances to appear stuck. The `setup` command pre-syncs each worktree's venv sequentially to avoid this. If users report all instances hanging on python/uv commands, first verify no `uv` processes are still running (`ps aux | grep uv` or Task Manager), then remove the stale lock: `rm -f "$LOCALAPPDATA/uv/cache/.lock"` (Windows), `rm -f ~/.cache/uv/.lock` (Linux), or `rm -f ~/Library/Caches/uv/.lock` (macOS).
- If `$ARGUMENTS` is empty or doesn't match a command, show a brief usage guide:

```text
Expand Down
Loading