Give custom subagents isolation: worktree for safe parallel edits

MCP / Agents·14 hours ago·verified 14 hours ago·medium·~15 min setup·verified

Define custom subagents with `isolation: worktree` so delegated edits happen on a temporary branch checkout.

#subagents #worktrees #isolation #agents

The problem

Subagents that edit files in the main checkout can conflict with your foreground work.

The hack

Add `isolation: worktree` to `.claude/agents/*.md` frontmatter so the subagent gets an isolated copy of the repo.

Why it works

Official subagent docs: worktree isolation branches from the default branch and cleans up if nothing changed.

Setup

1. Create `.claude/agents/verifier.md` (or similar) with YAML frontmatter. 2. Set `isolation: worktree` plus a focused tool allowlist. 3. Ask the main session to delegate verification or a side implementation to that agent. 4. Review any leftover worktree changes before cleanup.

Code

---
name: verifier
description: Verifies changes against the spec without touching the main checkout
isolation: worktree
---
Verify the implementation against the linked spec. Report gaps only.

Additional details

You can also ask Claude to "use worktrees for your agents" without a custom file.