Skip to Content
GuidesMulti-Repo

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" --pr

Point at it without cd:

shep feat new "add /health endpoint" --repo ~/projects/backend --pr

Clone one from GitHub:

shep repo add --url myorg/data-pipeline # clones into ~/repos by default shep repo add --url myorg/data-pipeline --dest ~/work

Import 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 prompts

From 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 tui shows every feature from every repo (--repo <path> narrows it to one).
  • shep feat ls lists 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 --pr

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

  1. Create the backend feature: shep feat new "add payments API" --repo ./backend --pr
  2. Wait for the API to be merged (or close enough).
  3. Create the frontend feature with --attach pointing at the backend’s API spec.
shep feat new "add checkout UI using the new payments API" \ --repo ./frontend \ --attach ./backend/openapi.yaml \ --pr

The 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 repo command.