[DOCS] Git worktree guide: dependency installation buried in Tips instead of main Steps

Resolved 💬 2 comments Opened Jan 26, 2026 by coygeek Closed Feb 28, 2026

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees

Section/Topic

"Run parallel Claude Code sessions with Git worktrees" section

Current Documentation

The main Steps guide users through:

  1. Understand Git worktrees
  2. Create a new worktree
  3. Run Claude Code in each worktree
  4. Run Claude in another worktree
  5. Manage your worktrees

Dependency installation is mentioned only in the Tips section at the end:

"Remember to initialize your development environment in each new worktree according to your project's setup. Depending on your stack, this might include: JavaScript projects: Running dependency installation (npm install, yarn)..."

What's Wrong or Missing?

The dependency installation guidance is easy to miss because:

  1. It's in the collapsible Tips section, not the numbered Steps
  2. Users following the Steps may run claude and immediately ask it to "run tests" or "build", which will fail in a fresh worktree without dependencies
  3. The Steps show cd ../project-feature-a && claude without any intermediate setup

While the information IS documented, its placement reduces discoverability for users who follow the Steps sequentially.

Suggested Improvement

Option A: Add to Steps (recommended)

Add a step between "Create a new worktree" and "Run Claude Code in each worktree":

<Step title="Initialize the worktree environment">
New worktrees don't include dependencies (e.g., `node_modules`). Install them before running Claude:

```bash
cd ../project-feature-a
npm install  # or yarn, pip install -r requirements.txt, etc.

</Step>


### Option B: Make Tips more prominent

Move the dependency note to the top of the Tips section and use a warning callout.

### Impact

Low - Minor confusion or inconvenience

### Additional Context


**Affected Pages:**
| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/common-workflows | 709-712 | Tips section mentions dependency installation |

**Total scope:** 1 page

**Related Issues:**
- #19938 covers environment file initialization (different aspect of worktree setup)
- This issue focuses on dependency installation discoverability

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗