---
description: "Internal  -  interactive account picker for multi-agent."
---

# _account-picker  -  Account Selection

First step of every `multi-agent` flow **that touches a remote provider**.

> **Skip rule (local-only flow)**: When the input is `freetext` AND the user's
> repo selection will end up being entirely local (no github/bitbucket account
> needed for any selected primary), this step is **skipped entirely**  -  no
> question, no token lookup. Detection: `freetext` flow first fetches local
> repos (`repo-cache.sh local "$HOME"`); if the picker resolves to local-only
> repos, account-picker is bypassed and the state file's `accountId` is left
> `null` with `tokens={}`. Phases 6/7 read these as "local-only" signals.

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

## Steps

1. **Fetch account inventory**:
   ```bash
   ~/.claude/lib/account-resolver.sh > /tmp/multi-agent-accounts.json
   ```
2. **Filter** when needed:
   - Jira-based flow → `--providers jira`
   - GitHub-based flow → `--providers github`
   - Bitbucket-based flow → `--providers bitbucket`

3. **Picker UI**  -  show via AskUserQuestion (single-select):
   - Breadcrumb (per `$HOME/.claude/multi-agent-refs/picker-contract.md` Step narration): before the question, print the narrator line `<localized: "Step 1/N: account selection">` (`N` = total Phase 0 steps for the active flow).
   - `header`: "Account" (English chip)
   - `question`: `<localized: "Which account should this run use?">`
   - one option per account: `label` = account label (English), `description` = providers in `outputLanguage`
   ```
   [1/N] {question}
     > {label}   ({providers})
       ...
   ```
   - Single account → auto-select, show info only (still print the breadcrumb line)
   - Multiple → multiSelect=false picker

4. **Persist selection to state**:
   - `accountId`, `accountPrefix`, `tokens.{github,jira,bitbucket,confluence}`,
     `jiraHost`, `bitbucketHost`, `isWork`

## Autopilot Behavior

When `MULTI_AGENT_AUTOPILOT=1`:
- Single account → auto-select
- Multiple → default selection priority:
  1. account whose remote matches the cwd repo
  2. `prefs.global.recentAccounts[0]` (most recently used)
  3. first account with `isWork=true`
  4. first account in the list
- Selection logged: `auto-selected account: {label}`

## Recent-accounts write

After confirmation (interactive) or auto-selection (autopilot), update
`prefs.global.recentAccounts[]` LRU-style:

1. If selected `id` already in `recentAccounts`, increment its `count`,
   refresh `lastUsed` (ISO 8601 UTC), and move it to position 0.
2. Otherwise prepend `{id, prefix, lastUsed, count: 1}` and trim to 10 entries.
3. Atomic write via `prefs.json.tmp` + rename.

This is what makes priority rule #2 work  -  the picker remembers which account
was used last and surfaces it first on the next autopilot invocation.

## Error Cases

- No accounts → if the input is `freetext` and at least one local repo exists,
  fall through to local-only flow (skip this step). Otherwise prompt user to
  run `setup` and halt.
- Filter unmet → "No matching account for this flow ({provider} token required)" → halt.

## Output (example)

```json
{
  "accountId": "my-account",
  "accountPrefix": "${USER}",
  "tokens": {
    "github": "${USER}_Github_Access_Token",
    "jira": "${USER}_Jira_Access_Token",
    "bitbucket": "${USER}_Bitbucket_Access_Token",
    "confluence": "${USER}_Confluence_Access_Token"
  },
  "jiraHost": "jira.example.com",
  "bitbucketHost": "bitbucket.example.com",
  "isWork": true
}
```