chore: add worktree-isolated task list script for parallel development

[diegomrsantos]

Issue Addressed

Workaround for anthropics/claude-code#24754 — Claude Code's task list (TaskCreate/TodoWrite) leaks across git worktrees because worktrees share the same .git directory.

Proposed Changes

• Added scripts/claude-worktree.sh, a script that creates worktrees and launches Claude Code with isolated task lists in one command
• Documented the parallel development workflow in CLAUDE.md, including usage, cleanup, and troubleshooting

Usage

Create a new worktree and launch:

./scripts/claude-worktree.sh new feat/my-feature                  # from upstream/unstable
./scripts/claude-worktree.sh new fix/bug-123 origin/stable        # from specific base

Launch in an existing worktree:

./scripts/claude-worktree.sh              # interactive session
./scripts/claude-worktree.sh --resume     # with claude args

The script sets CLAUDE_CODE_TASK_LIST_ID to a unique value derived from the worktree directory name and a hash of its absolute path, ensuring each worktree gets its own task list. Works on both Linux (sha256sum) and macOS (shasum).

Additional Info

This is a lightweight workaround until Claude Code provides native worktree-level task isolation. The script requires no configuration and produces human-readable IDs with guaranteed uniqueness.

[claude-code-actions-sigp]

Claude finished @diegomrsantos's task in 1m 16s —— View job

---

Code Review Complete

• Read all changed files
• Review shell script implementation
• Review documentation changes
• Check if previous feedback was addressed
• Provide comprehensive review feedback

---

Summary

The PR successfully implements a workaround for task list isolation in git worktrees. The previous review feedback has been properly addressed, and the implementation is solid. I've identified a few minor improvements for robustness and clarity.

Code Quality

scripts/claude-worktree.sh:20-27 - Cross-platform hash handling is well-implemented with proper fallback logic for both Linux (sha256sum) and macOS (shasum). The error message is clear and actionable.

scripts/claude-worktree.sh:32-36 - Command validation before exec is a good safety check that prevents confusing error messages.

scripts/claude-worktree.sh:29 - The task list ID format ${WORKTREE_DIR}-${PATH_HASH} provides both human readability and uniqueness, which is excellent for debugging.

Security & Robustness

scripts/claude-worktree.sh:18 - The fallback from git rev-parse to pwd is good, but consider what happens if neither command works or returns an unexpected value:

# Current:
WORKTREE_PATH="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"

# Safer alternative:
WORKTREE_PATH="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
if [ -z "${WORKTREE_PATH}" ]; then
    echo "Error: Unable to determine working directory" >&2
    exit 1
fi

scripts/claude-worktree.sh:39 - Using exec is correct here as it replaces the shell process with claude, but it means any cleanup code after this line would never run. This is fine for the current implementation, but worth documenting if cleanup is ever needed.

scripts/claude-worktree.sh:21-23 - The hash generation uses echo, which adds a newline. While this is consistent and works fine, it's worth noting that different paths will always have consistent hashes due to the newline being part of the input. Consider using printf for more explicit control:

PATH_HASH="$(printf '%s' "${WORKTREE_PATH}" | sha256sum | cut -c1-8)"

Documentation

CLAUDE.md:484 - The note clarifying upstream vs origin remote naming is helpful. Consider adding a concrete example of the fork setup for complete clarity:

**Note**: Examples below use `upstream` as the remote pointing to `sigp/anchor` and `origin` as your fork, following the standard fork contribution workflow. Set up with:
```bash
git remote add upstream https://github.com/sigp/anchor.git

**CLAUDE.md:505-511** - The troubleshooting section is well-structured and addresses the most likely issues. Consider adding one more common scenario:

```markdown
**Task lists still shared**: Ensure you're launching through the script, not directly via the `claude` command.

**Permission denied**: The script needs execute permissions. Run `chmod +x scripts/claude-worktree.sh`

**Wrong directory hash**: If you move the worktree directory, the hash will change and you'll get a different task list ID.

Testing

Missing test coverage - While this is a simple script, consider adding a test that verifies:

1. The script generates consistent IDs for the same path
2. Different paths produce different IDs
3. The script handles missing git gracefully

This could be a simple bash test script or documented manual test procedure.

Minor Issues

scripts/claude-worktree.sh:14 - set -euo pipefail is excellent for catching errors, but -e will cause the script to exit if git rev-parse fails (line 18). This is actually fine because of the || pwd fallback, but it's worth noting that the error output from git (stderr) is hidden by 2>/dev/null.

.github/wordlist.txt - All new words are appropriate additions. The lowercase macOS follows Apple's current branding (they changed from MacOS to macOS in 2016).

Previous Review Feedback

All three items from the previous review have been properly addressed:

1. ✅ Task list ID collision risk - Fixed by using path hash
2. ✅ Missing command validation - Added command -v claude check
3. ✅ Remote name inconsistency - Clarified with note about fork workflow

Recommendations

1. Add empty path validation after line 18 (scripts/claude-worktree.sh:18)
2. Consider using printf instead of echo for hash generation (scripts/claude-worktree.sh:21-23)
3. Enhance troubleshooting section with additional common scenarios (CLAUDE.md:505-511)
4. Optional: Add test coverage for the script's core functionality

Overall Assessment

This is a well-implemented workaround for a real problem. The code is clean, properly documented, and handles edge cases thoughtfully. The cross-platform hash fallback and command validation demonstrate attention to detail. The minor suggestions above would further improve robustness, but the current implementation is production-ready.

---

[dknopik]

Does this need to be committed to the repo?

[diegomrsantos]

Does this need to be committed to the repo?

If we commit, the whole team can use it

[shane-moore]

could be useful

[shane-moore]

@diegomrsantos, @petarjuki7, @dknopik, we discussed briefly on anchor weekly call. i was thinking utility would be if you check out a couple branches at same time, one for feature building and the other for pr review, for example. concern is that this is kind of a work around for anthropic issue, so doesn't make as much sense to enshrine the logic in the codebase. just had the idea that we could do experiment: we can use these scripts locally if we want to do git worktree related tasks with claude. and then we can chat in like a month to see if we're actually using the feature. if at that point the anthropic issue isn't resolved on their end and we're finding this useful, then we merge this. wdyt?

[diegomrsantos]

I honestly can't understand what the issue with this PR is. It's just an isolated script and a few additions to claude.md. If the team prefers to close it, please let me know, and I can try to find a way to use it locally.