# Worktree Isolation for Sub-Agents
Zeph can automatically create isolated git worktrees for background sub-agents to prevent file system conflicts and mutations when multiple agents work on the same repository simultaneously.
## Why Worktree Isolation?
When you spawn multiple sub-agents in parallel (e.g., one fixing bugs while another adds features), they both need to work on the codebase without interfering with each other. Without isolation:
- Both agents modify the same working directory
- Changes from one agent can be overwritten by another
- File locks and git state conflicts cause failures
- Test results are unpredictable
Worktree isolation solves this by giving each sub-agent its own independent checkout via git worktrees. Each worktree can have its own branch, uncommitted changes, and build artifacts.
## Setup
### 1. Enable in Configuration
Add the `[worktree]` section to your config:
```toml
[worktree]
enabled = true # Enable worktree isolation
bg_isolation = "worktree" # Isolation mode: "none" or "worktree"
base_ref = "head" # Worktree base ref: "head" or "fresh"
git_timeout_secs = 30 # Git operation timeout
```
Or during `zeph init` wizard:
```bash
zeph init
# ... follow the prompts until "Worktree Isolation" step
```
### 2. Understand the Modes
**`bg_isolation = "none"` (default):** Sub-agents operate in the same directory as the main agent. No isolation.
**`bg_isolation = "worktree"`:** Each sub-agent gets its own git worktree cloned from the repository. This requires:
- A git repository at the current working directory (or ancestor)
- Git version 2.7.0 or later
- Sufficient disk space for shallow clones
### 3. Choose a Base Reference
When creating worktrees, Zeph uses one of two strategies:
**`base_ref = "head"` (default):** Clone from the current working tree's HEAD commit. Sub-agents see the exact state of your repository at spawn time.
- **Pros**: Includes all your uncommitted changes and local branches
- **Cons**: If your working tree has broken tests or build errors, sub-agents inherit them
**`base_ref = "fresh"`:** Clone from the main/master branch on the remote. Sub-agents start with a clean, build-ready state.
- **Pros**: Sub-agents always start from a known-good state
- **Cons**: Local changes are not visible to sub-agents; they may be out-of-sync with your working tree
Choose based on your workflow:
- **Development flow**: Use `head` so sub-agents can see your in-progress work
- **CI/release flow**: Use `fresh` so sub-agents always test against the main branch
### 4. Manage Worktrees
List active worktrees:
```bash
zeph worktree list
```
Output example:
```
Active Worktrees:
/home/user/repo/.git/worktrees/zeph-agent-a1b2c3d4 (created 2 minutes ago)
/home/user/repo/.git/worktrees/zeph-agent-e5f6g7h8 (created 1 minute ago)
```
Clean up stale worktrees (those no longer tracked by active sub-agents):
```bash
zeph worktree clean
```
This is safe to run anytime — it only removes worktrees that are no longer in use.
## Spawning Sub-Agents with Isolation
Once worktree isolation is enabled, background sub-agents automatically use isolated worktrees:
```
> /agent spawn code-reviewer Review the auth module
Code reviewer is working in isolated worktree at .git/worktrees/zeph-a1b2c3d4
```
Sub-agents can:
- Read and modify files without affecting your main working tree
- Create branches and commits
- Run tests and builds
- Check out different commits
## Override Base Reference
At runtime, override the base ref for a specific sub-agent spawn:
```bash
zeph --worktree-base-ref fresh
> /agent spawn validator Check main branch
```
This is useful for one-off runs where you want a different base than your config default.
## Performance Considerations
Worktree creation incurs a git clone operation:
- **Shallow clones**: Zeph uses `--depth=1` to minimize download time
- **Time**: Typically 1-10 seconds depending on repository size
- **Disk space**: Shallow clones use ~20-30% of a full clone
Example timings:
| Small (< 100 MB) | 1-2s | 20-30 MB |
| Medium (100-500 MB) | 3-5s | 60-150 MB |
| Large (> 500 MB) | 10-30s | 200+ MB |
If worktree creation is slow on your system:
1. **Increase timeout**: `git_timeout_secs = 60` (default: 30)
2. **Verify network**: Shallow clones fetch from the remote; slow network slows clones
3. **Check disk**: Low disk space can slow git operations
4. **Use `head` mode**: Avoids a remote fetch; only copies the local worktree
## Troubleshooting
### "Git operation timed out"
The git command to create or remove the worktree exceeded `git_timeout_secs`. Solutions:
1. Increase timeout in config: `git_timeout_secs = 60`
2. Check your network connection
3. Verify the repository is healthy: `git gc`, `git fsck`
### "Worktree already exists"
A previous sub-agent's worktree wasn't cleaned up. Run:
```bash
zeph worktree clean
```
If the directory still exists on disk but git doesn't know about it, remove it manually:
```bash
rm -rf .git/worktrees/zeph-*
```
### Sub-agent fails in worktree
Sub-agents run inside the worktree. If a sub-agent fails:
1. Check the logs: `zeph --debug-dump`
2. Inspect the worktree: `cd .git/worktrees/zeph-<id> && git log --oneline`
3. File an issue with the worktree path and sub-agent logs
### No worktrees listed, but sub-agents are spawning
Worktree listing shows only **created** worktrees. Worktrees are removed automatically when:
- The sub-agent completes and is not being resumed
- You manually run `zeph worktree clean`
If you want to inspect a completed sub-agent's changes before cleanup, resume the sub-agent or manually check the worktree directory before cleaning.
## Next Steps
- [Sub-Agent Orchestration](../advanced/sub-agents.md) — full sub-agent system documentation
- [Configuration Reference](../reference/configuration.md) — all worktree config options