Your Claude Code Worktree Subagent Can't See Your Feature Branch. Set baseRef to head A developer documented that Claude Code subagents configured with `isolation: worktree` branch from the repository's remote default branch (usually `origin/main`) rather than the parent session's HEAD, so a subagent asked to test a function on a local feature branch reports the function doesn't exist. The fix is setting `baseRef` to `head` in the subagent's frontmatter, after committing work and adding `.claude/worktrees/` to `.gitignore`; the walkthrough is assembled from Claude Code and git documentation rather than hands-on testing. You wrote refund an hour ago. It's committed on feature/refund . You hand it to a subagent: "add tests for refund in src/orders.js ." The subagent comes back and tells you there is no refund in that file. It isn't wrong. In the checkout it was given, the function doesn't exist. Claude Code https://code.claude.com/docs/en/sub-agents lets a custom subagent run in its own git worktree with one frontmatter line, isolation: worktree . The subagent docs say that worktree is "branched by default from your default branch rather than the parent session's HEAD ." The worktree docs https://code.claude.com/docs/en/worktrees are more precise: the default base is the repository's default branch on the remote , usually origin/main . Your feature branch isn't in it. Neither are commits on your local main that you haven't pushed. The fix is one setting. Checking that you need it takes a few git commands. I haven't run this walkthrough myself: it's built from the current Claude Code and git docs, so if a step behaves differently on your version, the worktree docs https://code.claude.com/docs/en/worktrees are the source of truth. You need a repo with an origin remote. That part matters. When no remote is configured, or origin/HEAD isn't cached and can't be fetched, Claude Code falls back to your local HEAD . A throwaway repo with no remote won't reproduce the problem. Take a small Node project "type": "module" in package.json whose main is pushed. Cut a branch and add a function: // src/orders.js added on feature/refund export function refund order { if order.status == "paid" { throw new Error "only paid orders can be refunded" ; } return { ...order, status: "refunded" }; } git switch -c feature/refund git add src/orders.js git commit -m "Add refund for paid orders" Commit before you delegate. A new git worktree https://git-scm.com/docs/git-worktree is checked out from a commit, so edits you haven't committed stay in your checkout whatever the base setting is. While you're here, add .claude/worktrees/ to .gitignore . That's where Claude Code creates worktrees, and you don't want them showing up as untracked files in your main checkout. Project subagents live in .claude/agents/ . Save this as .claude/agents/test-writer.md : --- name: test-writer description: Writes node:test tests for code named in the request tools: Read, Write, Edit, Bash, Grep, Glob isolation: worktree --- First run git log --oneline -3 and git branch --show-current and include both outputs in your reply. If the function you were asked to test does not exist in this checkout, say so and stop without changing any file. Otherwise write tests under test/ with node:test, run node --test , and commit the tests on your current branch. Reply with the branch name and the commit hash. name and description are the two required fields. isolation: worktree is the line that matters here. Spell it exactly: the frontmatter reference https://code.claude.com/docs/en/sub-agents says Claude Code ignores a field it doesn't recognize without reporting an error, so a typo gives you a subagent that quietly edits your main checkout. Claude Code picks up edits to .claude/agents/ within seconds, except the first agent file in a new agents directory: restart Claude Code once to load it. Start Claude Code on feature/refund and call the subagent by name so Claude doesn't pick a different one. You can type @agent-