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:

[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:

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:

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):

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:

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:

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:

zeph worktree clean

If the directory still exists on disk but git doesn’t know about it, remove it manually:

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 — full sub-agent system documentation
• Configuration Reference — all worktree config options