Multi-Repo
Shep manages features across as many repos as you want, from one web UI and one terminal console. Useful when a change spans frontend and backend, or when you switch between projects during the day.
Adding repos
Start a feature in it. The first time Shep runs in a repo, it starts tracking it:
cd ~/projects/backend
shep feat new "add /health endpoint" --prPoint at it without cd:
shep feat new "add /health endpoint" --repo ~/projects/backend --prClone one from GitHub:
shep repo add --url myorg/data-pipeline # clones into ~/repos by default
shep repo add --url myorg/data-pipeline --dest ~/workImport a whole folder of repos at once:
shep repo import ~/projects # pick which subfolders to import
shep repo import ~/projects --all --git-only # every git repo, no promptsFrom the web UI: use the round + button on the Control Center — Local Folder, Folder of repos, or From GitHub (search your GitHub repos, or paste owner/repo or a URL to clone it).
Have a local folder that isn’t on GitHub yet? shep repo init-remote creates a GitHub repository for it (private by default; --public, --org <name>).
Listing tracked repos
shep repo ls # ID, name, number of features, path, when it was added
shep repo show <id> # details for one repo (ID or prefix)Working across repos
There’s no repo switcher: every repo is visible at once.
- The Control Center canvas shows each repo with its features, and the session tree beside it lists repositories → features → agent sessions.
- Inventory lists every app, repository and feature, grouped and filterable.
shep tuishows every feature from every repo (--repo <path>narrows it to one).shep feat lslists everything;shep feat ls -r <path>filters to one repo.
Run features in two repos in parallel:
shep feat new "add payments API" --repo ~/projects/backend --pr
shep feat new "add checkout UI" --repo ~/projects/frontend --prTwo worktrees, two branches, two draft PRs — one in each repo.
To group related repos (with their own GitHub and agent logins, git identity and rules), put them in a space. To track work across repos, use Projects.
Working on a repo you don’t have locally
shep feat new "explore using polars instead of pandas" \
--remote https://github.com/myorg/data-pipeline \
--pr--remote takes a GitHub URL or owner/repo. Shep clones the repo into your clone directory (~/repos by default), creates the feature there and opens the PR. If you don’t have push access, Shep forks the repo first and opens the PR against the upstream project; the feature then shows as AwaitingUpstream. --remote can’t be combined with --repo.
Cross-repo workflows
Shep doesn’t coordinate features across repos automatically — each feature is independent. But you can sequence them yourself:
- Create the backend feature:
shep feat new "add payments API" --repo ./backend --pr - Wait for the API to be merged (or close enough).
- Create the frontend feature with
--attachpointing at the backend’s API spec.
shep feat new "add checkout UI using the new payments API" \
--repo ./frontend \
--attach ./backend/openapi.yaml \
--prThe frontend agent gets the API contract as context.
Removing a repo
In the web UI, open the repository’s menu on the Control Center and choose Remove repository. That removes the repo and all its features from Shep; tick Also delete the repository folder from disk only if you want the files gone too. There’s no CLI command for this.
To wipe everything instead, stop Shep and delete ~/.shep/. That removes all features, settings, history and every worktree under ~/.shep/repos/.
What’s next
- Web Dashboard — the Control Center, session tree and Inventory.
- Spaces — group repos with their own logins and rules.
- CLI Reference — every
shep repocommand.