---
description: "Internal  -  multi-select repo picker for multi-agent."
---

# _repo-picker  -  Repo Selection (Multi-Select)

Used by `picker-issue`, `picker-jira`, `gh-num`, and `freetext` flows.

> **Language**: see `picker-contract.md` + `rules.md` Language Application matrix.

## Steps

1. **Fetch repo list** per provider/account, then optionally merge local checkouts:
   ```bash
   # GitHub (only when an account was selected  -  see _account-picker)
   ~/.claude/lib/repo-cache.sh github "$ACCOUNT_GH_OWNER"

   # Bitbucket (work  -  only when an account was selected)
   BB_TOKEN_KEY="$ACCOUNT_BB_TOKEN_KEY" \
   BB_USER_KEY="$ACCOUNT_BB_USER_KEY" \
   BB_HOST="$ACCOUNT_BB_HOST" \
     ~/.claude/lib/repo-cache.sh bitbucket "$BB_PROJECT_KEY"

   # Local  -  for freetext/no-tracker flows, scan $HOME for .git checkouts so a
   # user with no provider account can still pick a repo and run the pipeline.
   ~/.claude/lib/repo-cache.sh local "$HOME"
   ```
   Provider sources are concatenated into one picker list; each row carries a
   `(github)` / `(bitbucket)` / `(local)` suffix so the choice is unambiguous.
   Local rows expose `localPath` (filesystem path) and a redacted `remoteUrl`
   (credentials stripped at cache time).

2. **Show list** via AskUserQuestion (multiSelect=true). Print the breadcrumb narrator line first (per `$HOME/.claude/multi-agent-refs/picker-contract.md` Step narration): `<localized: "Step 2/N: repo selection">`.
   ```
   [2/N] Select repos (multi):
     [ ] <repo-a>      (github)
     [ ] <repo-b>      (bitbucket)
     [ ] <repo-c>      (local)
     ...
   ```
   - cwd repo, when present, defaults to `[x]`
   - forks fall to the bottom
   - local-only rows show `(local)` and the trimmed `$HOME`-relative path

3. **Single-repo mode**  -  used for `gh-num`/`freetext` (multiSelect=false)

4. **All-local selection**  -  when every selected repo has `provider="local"`,
   downstream phases switch to local-only behavior: no remote push, no PR, no
   Jira/Wiki/Confluence channels. Mixed selections (some local, some provider)
   apply per-repo: the local repos stay offline, the provider repos use their
   normal remote flow.

## Output

```json
{
  "selectedRepos": [
    {"fullName":"<owner>/<repo-a>","name":"<repo-a>","provider":"github"},
    {"fullName":"<owner>/<repo-b>","name":"<repo-b>","provider":"github"},
    {"fullName":"local/<repo-c>","name":"<repo-c>","provider":"local","localPath":"<absolute-path>"}
  ]
}
```

## Autopilot Behavior

When `MULTI_AGENT_AUTOPILOT=1`:
- **Multi-select mode** (issue picker flow): pick **only** cwd repo if present; otherwise fall back to most-recent repo from `prefs.projects[*].lastUsed`
- **Single-select mode** (gh-num/freetext): pick cwd repo automatically; if none, halt with error (autopilot can't prompt)
- Selection logged: `auto-selected repos: [name1, name2]`

## Error Cases

- No repos for the account: prompt user for manual `owner/repo`
- Cache fails (gh CLI missing): prompt user manually
- Autopilot + no cwd repo: halt with "autopilot single-repo mode requires cwd to be a git repository"