Parallel Execution & Worktrees
Shep runs many AI agents at once without them stepping on each other or on your working directory. The mechanism is a long-standing git feature called worktrees.
What’s a worktree?
A worktree is a second checkout of the same repo, sharing the same .git directory. It has its own working files and its own current branch — but objects, history, refs and config are shared.
Two consequences:
- Worktrees are cheap. They share the object database, so they cost little extra disk space.
- Worktrees are isolated. Edits in one worktree never touch another.
What Shep does with them
For every feature, Shep:
- Syncs
mainfrom the remote (skip with--no-rebase). - Creates a worktree at
~/.shep/repos/<repo-hash>/wt/<branch-slug>on a new branch such asfeat/add-dark-mode. If you setSHEP_HOME, it lives under that folder instead. - Runs the agent inside that directory.
- Commits, pushes and opens a PR — all from that worktree’s branch.
Your main checkout never changes. You stay on whatever branch you were on and keep working.
If a plain git worktree add isn’t enough — a monorepo that needs node_modules symlinked, config files copied, caches warmed — you can replace or extend that step with your own commands: shep settings worktree --post-create-command '…'. See Worktree provisioning.
Why this matters for parallelism
Without worktrees, running multiple agents on the same repo means:
- They share the working directory → file conflicts.
- They share the current branch → checkout conflicts.
- One agent’s stash breaks the others.
With worktrees, every agent has its own copy:
shep feat new "add stripe checkout" --pr
shep feat new "add dark mode" --pr
shep feat new "refactor auth middleware" --pr
shep feat new "fix login redirect bug" --pr
shep feat new "add /health endpoint" --prFive agents, five worktrees, five branches, five draft PRs.

Capping concurrency
The bottlenecks aren’t the worktrees — they’re your agent’s rate limits, your CPU and RAM, and your CI capacity. By default Shep runs every feature at once. To cap it:
shep settings workflow --max-parallel 3 # at most 3 features running an agent
shep settings workflow --max-parallel 0 # no limit (the default)Or set Max parallel features in Settings → Workflow. Over the limit, new features wait as Pending and start in order as slots free up. shep feat start <id> --force or shep feat resume <id> --force runs one anyway.
You can also pause the whole queue (shep fleet pause) and see what’s running, queued, waiting on you or failed with shep fleet status. See Fleet management.
When features touch the same files
Worktrees keep features from colliding while they run, but two features can still change the same files and conflict at merge time. The opt-in Agent coordination flag lets an agent decide whether an overlapping feature should wait for the other one or run alongside it:
shep settings flags enable agentCoordinationshep feat show <id> then lists what a feature waits for, what it runs alongside, and the shared files.
Checkpoints live in the same repo
After every step that changes files, Shep snapshots the worktree as a hidden git ref under refs/shep/checkpoints/<featureId>/. These refs live in the shared ref store, are never pushed, and don’t touch your branches. Use them to see what a step changed or roll a feature back — see Git checkpoints.
Cleaning up
shep feat del <id>After you confirm, Shep removes the worktree, the local branch and the remote branch, and closes the feature’s open PR. Opt out of parts of that with --no-cleanup (keep the worktree and branches) or --no-close-pr (leave the PR open). --force skips the prompts.
Inspecting a worktree directly
To look at the agent’s work in progress yourself:
shep ide <id> # open the worktree in your configured editor
shep ide <id> --vscode # or pick one: --cursor, --vscode, --windsurf, --zed, --antigravity
shep feat show <id> # prints the worktree pathIn the web UI, the feature drawer has buttons to open the worktree in your IDE, a shell or your file manager. In shep tui, press t to open a shell pane in the selected feature’s worktree (T for a new window).
The directory is a normal git checkout. If you want to take over from the agent, commit and push from there.
What’s next
- Fleet management — limits, the queue, triage and bulk approvals.
- Worktree provisioning — custom create and post-create commands.
- Git checkpoints — diff and restore any step.