CLI Agent Hopper
CLI Agent Hopper is a VS Code extension for people who have more than one account for Claude Code, Gemini CLI, OpenAI Codex CLI, or GitHub Copilot CLI (e.g. a personal and a work subscription) and want to hop between them from a sidebar panel the moment one hits its usage limit or rate limit — instead of waiting for the reset window or manually logging out/in.
It manages CLI logins (the OAuth sessions each CLI stores locally) — not raw API keys.
Supported CLIs
| CLI |
How switching works |
| Claude Code |
Swaps ~/.claude/.credentials.json (backed up first), and syncs the cached email/org/usage display in ~/.claude.json so it doesn't keep showing the previous account. |
| Gemini CLI |
Swaps ~/.gemini/oauth_creds.json (backed up first). |
| OpenAI Codex CLI |
Swaps ~/.codex/auth.json (backed up first). Only works if Codex is using its default file-based credential storage — if you've configured cli_auth_credentials_store = "keyring" in ~/.codex/config.toml, this extension can't reach those credentials. |
| GitHub Copilot CLI |
Different mechanism entirely: Copilot CLI already has its own built-in multi-account switching (/user switch, /user list). This extension just sends /user switch <name> into a terminal that's actively running copilot — there's no credential file to back up, and you must have already logged into that account yourself via copilot login. |
How it works
- CLI Agent Hopper panel — a dedicated icon in the Activity Bar (left-hand icon rail) opens a sidebar with a live list of every saved account, grouped by CLI, with email/plan shown and a checkmark on whichever is active for that CLI (each CLI tracks its own active account independently — you can have a Claude account and a Gemini account both active at the same time). At the bottom, pick a CLI from the dropdown, type a name, and click "Add Current Account as Profile" — the name entry and any free-tier/error message appear inline in the panel itself, not as a popup or notification. Each account row has Switch / Rename / Remove buttons.
- Switch to Profile... / the status bar item are Command Palette equivalents of the same thing, if you'd rather not open the sidebar (the Command Palette's "Add Current Account as Profile" prompts for a CLI and a name via popups, as a keyboard-only fallback).
- For Claude/Gemini/Codex, the extension backs up the current credentials file before overwriting it, then writes the target profile's credentials in. After a switch, reopen your terminal and run the CLI again — it reads credentials at startup, so it won't pick up the change in an already-running session.
- The extension also watches terminals running any of the four CLIs for rate-limit/usage-limit wording and can prompt you — or, if
claudeSwitcher.autoSwitch is enabled, automatically switch — to the next saved account for that same CLI when one is seen.
- Switch to Next Account Now always works as a manual override, regardless of whether detection fires (it'll ask which CLI if you have profiles for more than one).
- Free tier: up to 2 saved accounts total, shared across all CLIs. Trying to add a 3rd shows a message instead of saving it — support for more is planned for a future update.
- Duplicate detection: trying to add an account that's already saved (same Claude account UUID, same Google account for Gemini, same Codex account id, or same Copilot account name) doesn't create a second profile — instead you get a message naming the existing profile plus a Switch to it now button (in the panel) or a Switch Now action (from the Command Palette).
Settings
| Setting |
Purpose |
claudeSwitcher.limitPhrases |
Claude Code only: phrases/regex to watch for in terminal output that suggest a limit was hit. Other CLIs use built-in defaults for now. |
claudeSwitcher.matchMode |
substring (default) or regex matching for the above. |
claudeSwitcher.autoSwitch |
Switch automatically instead of asking first. Off by default. |
claudeSwitcher.rotationOrder |
Explicit profile-ID rotation order; defaults to insertion order. |
claudeSwitcher.credentialsPath |
Claude Code only: override the credentials file path (default: ~/.claude/.credentials.json). |
claudeSwitcher.claudeConfigPath |
Claude Code only: override the main config file path (default: ~/.claude.json). |
claudeSwitcher.refreshExpiryWarningDays |
Claude Code only: warn before switching to a profile whose session is close to expiring. |
Known limitations
- Credential file formats are internal and undocumented for Claude Code, Gemini CLI, and Codex CLI alike. They could change between CLI versions. The extension validates each file's shape before reading or writing it and refuses to act if it doesn't recognize the structure, rather than guessing.
- Codex CLI support requires file-based credential storage (the default). If
cli_auth_credentials_store is set to keyring in ~/.codex/config.toml, switching won't work.
- Copilot CLI support has no validation or backup - unlike the other three, there's no credential file for this extension to check or protect. It's just sending the same
/user switch <name> text you could type yourself, into whichever terminal is running copilot.
- Limit detection is wording-based and fragile. If a CLI changes its message text, automatic detection may silently stop firing. The manual "Switch to Next Account Now" command and the status bar control don't depend on detection, so switching always works even if detection doesn't.
- This tool is meant for switching between accounts you personally own or control (e.g. a personal and a work subscription), not for evading a single account's usage limits in a way that would violate a provider's Terms of Service.
Installation
This extension isn't published to the Marketplace — install it locally using one of the two methods below.
Option A: Try it without installing (Extension Development Host)
Good for testing before committing to a real install.
- Open this folder (
claude-extention) in VS Code.
- Run
npm install and npm run compile in a terminal (only needed once, or after editing source).
- Press
F5 (or Run → Start Debugging). A second VS Code window opens — titled "Extension Development Host" — with the extension already active.
- Use it in that window. Closing it unloads the extension; press
F5 again next time you want it.
Option B: Package and install for real (persists across restarts)
- In this folder, install dependencies and build the package:
npm install
npx @vscode/vsce package
This produces claude-account-hopper-<version>.vsix in the project root (the version comes from package.json). (First run downloads the small vsce packaging tool via npx — that's expected.)
- Install the
.vsix into VS Code, either:
- Reload VS Code if prompted. You should see an account status bar item in the bottom-left, a new CLI Agent Hopper icon in the Activity Bar (left icon rail), and the five
CLI Agent Hopper: ... commands in the Command Palette (Ctrl+Shift+P).
To upgrade after changing source: bump the version in package.json, re-run the two commands in step 1, and reinstall the new .vsix (VS Code will offer to update/reload).
First-time setup after installing
- Make sure you're logged into your first account for whichever CLI you use (e.g.
claude login, gemini and sign in, codex login, or copilot login).
- Open the CLI Agent Hopper panel, pick that CLI from the dropdown, type a name (e.g.
personal), and click "Add Current Account as Profile".
- Log into your second account for that CLI (or a different CLI entirely), and repeat step 2 with a different name (e.g.
work).
- From then on, use the Switch button on the account you want (in the panel or via CLI Agent Hopper: Switch to Profile... / Switch to Next Account Now) to swap — no more manual logout/login each time.
Manual test plan
- Log in with account A for a given CLI, then add it as a profile from the panel.
- Log in with account B (same CLI), add it as a second profile.
- Start a session in an integrated terminal for that CLI and trigger (or simulate) a limit message.
- Confirm the prompt (or auto-switch, if enabled) swaps the right credentials file, takes a backup first, and updates the status bar.
- Confirm "Switch to Next Account Now" works on its own.
- For Claude Code specifically: confirm switching to a profile with a near-expired refresh token shows the expiry warning.
- Open the panel; confirm profiles are grouped by CLI, the active one per CLI is checkmarked, the Switch button on an inactive one switches to it, and Rename/Remove work and update the panel immediately.
- In the panel's form, pick a CLI, type a name, and click "Add Current Account as Profile"; confirm the new profile appears in the list and a confirmation message shows inline in the panel (not a popup or notification).
- With 2 profiles saved (any mix of CLIs), try adding a 3rd from the panel and confirm the free-tier message appears inline in the panel instead of a notification.
- For Copilot specifically: with a terminal running
copilot, add a profile using the exact account name Copilot's own /user list shows, then switch to it and confirm /user switch <name> gets sent into that terminal.
- With account A already saved, try adding it again (same CLI, same account, any label) and confirm it's rejected with a message naming the existing profile and a working "Switch to it now" / "Switch Now" action, instead of creating a duplicate.
| |
