Setup Aliases

setup-aliases

State-aware orchestration for VibeProxy aliases. This skill owns exactly two surfaces:

1. the vibeproxy-kit managed block in ~/.zshrc
2. the oauth-model-alias entries in ~/.cli-proxy-api/config.yaml that it created

Everything else — unrelated YAML keys, unrelated shell aliases, user-authored alias entries — is preserved. The skill coordinates discovery, a guided per-backend probe cycle, writes, a VibeProxy restart gate, live validation, and transactional rollback on failure.

All five scripts in ${CLAUDE_PLUGIN_ROOT}/skills/setup-aliases/scripts/ emit JSON to stdout. Your job is to chain them together, surface decisions to the user via AskUserQuestion, and persist state to ${CLAUDE_PLUGIN_DATA}/config.json before any write.

Phase 1 — Discover

Run the read-only inspector and parse its JSON:

bash ${CLAUDE_PLUGIN_ROOT}/skills/setup-aliases/scripts/discover.sh > /tmp/vibeproxy_discover.json

Then read /tmp/vibeproxy_discover.json. Key fields:

• vibeproxy_installed, vibeproxy_reachable — see Onboarding gates below if either is false
• user_overlay_exists, state_file_present — determines whether we are first-run or rerun
• authenticated_backends — array of {token, config_key, display_name, auth_files}; see Onboarding gates below if empty or missing backends the user wants
• claude_code_channel — {connected, account_count}; see Claude Code channel note below
• managed_shell_aliases, managed_model_aliases, managed_payload_overrides, shortcut_shell_aliases — what the skill currently owns
• backend_catalogs, partial_probe — cached probe results and any aborted probe cycle
• conflicts — pre-existing cc-* entries that are not tracked in state (potential clashes); includes manual-shell-alias, manual-config-alias:, and manual-payload-override: sources

Present a compact summary back to the user (do not dump raw JSON):

VibeProxy: installed ✓ | reachable ✓
Authenticated backends: codex, copilot, gravity, gemini (4/4)
Claude Code channel: not connected
Currently managed: 3 model aliases, 4 shell aliases, 1 shortcut
Manual conflicts detected: 0
State file: present (last probe 2 days ago)

If partial_probe is non-null, tell the user a previous run aborted mid-cycle and offer to resume or restart.

Claude Code channel note

If claude_code_channel.connected is false, append the following informational note after the summary. This is not a gate — setup continues regardless.

> ℹ Claude Code channel is not connected in VibeProxy. > Alias models work normally for main conversations. However, when ANTHROPIC_BASE_URL points to the proxy, Claude Code's internal requests also go through it — session title generation, /advisor, and sub-agents with model: haiku/sonnet all use raw Anthropic model IDs that have no matching provider in the proxy. > > Without the Claude Code channel, these internal calls will fail silently. Main conversations using alias models are not affected. > > VibeProxy's documentation notes that routing requests through OAuth tokens may carry account risk. Review their documentation before connecting any provider: https://github.com/automazeio/vibeproxy > > Note: The OAuth login flow uses port 3000 for the callback — if a dev server is running on that port, the login will fail silently.

If claude_code_channel.connected is true, show Claude Code channel: connected (N accounts) in the summary and skip the note.

Onboarding gates

These gates run before Phase 2. If the user is fully set up (VibeProxy installed, running, and at least one backend authenticated), skip straight to Phase 2.

Gate 1 — VibeProxy not installed (vibeproxy_installed: false)

Tell the user:

> VibeProxy is not installed. It's a local HTTP proxy that lets Claude Code use models from Codex, GitHub Copilot, Antigravity, Gemini, Qwen, and Z.AI GLM through a unified endpoint. > > Install it from: https://github.com/automazeio/vibeproxy (macOS only) > > After installing, launch VibeProxy from /Applications/VibeProxy.app and come back here.

Stop here. Do not proceed to Phase 2.

Gate 2 — VibeProxy not reachable (vibeproxy_installed: true, vibeproxy_reachable: false)

Tell the user:

> VibeProxy is installed but not running. Launch it from the Applications folder or menu bar, then re-run /setup-aliases.

Stop here.

Gate 3 — No authenticated backends (authenticated_backends is empty)

Tell the user which backends are available and how to authenticate each one. Instruct them to authenticate all backends they subscribe to before coming back — not just one. The probe cycle configures backends one at a time, but authentication should be done upfront for all of them so the user doesn't have to re-run the skill each time they want to add another backend.

> No backends are authenticated yet. VibeProxy supports these providers — each requires a paid subscription: > > | Backend | How to authenticate | > |---------|---------------------| > | Codex | Settings → Codex → Connect (OAuth) | > | GitHub Copilot | Settings → GitHub Copilot → Connect (OAuth) | > | Antigravity | Settings → Antigravity → Connect (OAuth) | > | Gemini | CLI login required (see below) | > | Qwen | Settings → Qwen → Connect (OAuth) | > | Z.AI GLM | Settings → Z.AI GLM → Add Account (API key) | > > Open VibeProxy Settings from the menu bar icon and authenticate every backend you subscribe to, then re-run /setup-aliases. > > Gemini OAuth workaround: The VibeProxy GUI cannot complete Gemini authentication — the OAuth flow succeeds in the browser but the account silently fails to register (GitHub #286, #242). Use the CLI instead: > > ``bash > /Applications/VibeProxy.app/Contents/Resources/cli-proxy-api-plus \ > -login --config /Applications/VibeProxy.app/Contents/Resources/config.yaml > `` > > When prompted for login mode, choose 1 (Code Assist) for GCP projects or 2 (Google One) for personal Google One AI Premium subscriptions. After CLI login completes, VibeProxy will detect the new auth file automatically.

Stop here.

Gate 4 — Missing backends the user wants (some backends authenticated, user asks about others)

If the user mentions a specific backend that is not in authenticated_backends, tell them:

> ` is not authenticated yet. Open the VibeProxy menu bar → → Sign in. Once authenticated, re-run /setup-aliases` and it will appear in the backend list.

This gate does not block — continue to Phase 2 with the backends that are available, but surface the gap so the user knows.

Phase 2 — Warn, then pick a mode

Before asking for the mode, note that the probe cycle will temporarily toggle backends in the VibeProxy menu bar. Active claude sessions may route through a different provider while backends are toggled. Recommend running this skill when they are not mid-work.

Then ask via AskUserQuestion:

• Keep — inspect and report, no changes
• Merge update — preserve current setup, apply incremental changes (may reuse cached catalogs ≤ 30 days old)
• Add model — add a single model to an already-probed backend without re-probing (requires cached catalog)
• Remove model — remove a single managed alias without re-probing
• Reset and reconfigure — remove only skill-managed aliases and shell block, rebuild from scratch (always re-probes)

If the user chooses Keep, print the summary in more detail (including the currently managed canonical aliases and their models) and stop. No writes.

If the user chooses Add model, skip to Phase 5 using the cached catalog for the selected backend. No probe cycle needed — the user picks from cached models. If no catalog exists for the requested backend, fall back to a full probe for that backend only.

If the user chooses Remove model, show the current managed aliases and let the user pick which to remove. Skip Phases 3-5 entirely — go straight to Phase 7 (confirm) → Phase 8 (write) with the alias removed from state, config.yaml, and zshrc. No probe, no restart gate, no validation needed.

Phase 3 — Backend selection

From authenticated_backends, ask the user via AskUserQuestion which backends they want to configure this run. Multi-select. Skip any backend that has no auth file — those are unreachable even if the user picks them.

Phase 4 — Probe cycle

This is the most interaction-heavy phase. For each selected backend, in sequence:

1. Reuse cache? In Merge mode, if backend_catalogs[].probed_at is within 30 days, offer the user the option to reuse instead of re-probing. Reset mode always re-probes. The user may override with "force refresh". When reusing a cached catalog, highlight models that were not in the previous catalog (new since last probe) by comparing against the prior state's backend_catalogs.
2. Toggle prompt. Use AskUserQuestion to tell the user: *"In the VibeProxy menu bar, disable all backends except `. Click done when only is active."* Wait for explicit confirmation. **Do not** require a full quit-and-relaunch upfront — a menu bar toggle is sufficient in most cases. If the verify step (step 5) returns reject` due to stale state, escalate to a full restart (see step 5).
3. Probe. Run bash ${CLAUDE_PLUGIN_ROOT}/skills/setup-aliases/scripts/probe_backend.sh > /tmp/vibeproxy_probe_.json
4. Verify. Run python3 ${CLAUDE_PLUGIN_ROOT}/skills/setup-aliases/scripts/verify_probe.py --claimed --claimed-channel-key --all-channel-keys --probe-output /tmp/vibeproxy_probe_.json > /tmp/vibeproxy_verify_.json
5. Act on verdict.

• pass — accept this backend's catalog
• warn — Layer 2 saw unknown_signatures; surface the specific model IDs to the user and ask whether to trust them before accepting
• reject — show the reason from the verify output verbatim. On first rejection, escalate to a full restart: "The menu bar toggle didn't refresh the registry. Quit VibeProxy completely, then relaunch with only `` enabled." Wait for confirmation, then loop back to step 3 (re-probe). Do not accept a rejected probe under any circumstance.

1. Persist partial probe on abort. If the user aborts the cycle, write any completed backend catalogs into ${CLAUDE_PLUGIN_DATA}/config.json under partial_probe with a timestamp, then exit cleanly. The next invocation will offer to resume.

After all selected backends are probed, tell the user: "Probing complete. Re-enable all the backends you just probed — turn every toggle back on in the VibeProxy menu bar." Wait for confirmation before continuing to model selection.

Phase 5 — Model, effort, and shortcut selection

Read ${CLAUDE_PLUGIN_ROOT}/skills/setup-aliases/references/model-selection.md for the full model selection procedure: model family filtering, effort variant detection, canonical alias naming, protocol mapping, and shortcut generation.

Key rules (always in scope):

• Filter out embedding models, router models, legacy models, and self-referential cc-* aliases from prior runs
• Check references/effort-levels.md for effort levels; budget-based models get no effort variants
• Canonical format: cc--[-]; shortcuts: cc--[-]
• request_model = alias name (not upstream name); append (level) suffix for effort variants
• payload.override only for codex/copilot backends; gravity/gemini/qwen/zai get shell-suffix only

Phase 6 — Conflict resolution and migration

First-run migration

When state_file_present is false and conflicts is non-empty, the user has pre-existing manual cc-* aliases that predate this skill. Before treating them as conflicts, offer a migration path:

1. Analyze each conflict entry — extract the model name and effort level from the existing alias definition in the zshrc backup (the old ANTHROPIC_MODEL=... value).
2. Present a summary: "You have N existing manual cc-* aliases. Would you like to migrate them into skill management? Migrated aliases will be recreated as shortcuts pointing to the new canonical names."
3. For each manual alias the user wants to migrate, create a shortcut alias mapping the old name to the new canonical name (e.g., cc-codex-high → cc-codex-gpt54-high). The old manual definition will be replaced by the managed block.
4. Manual aliases the user does NOT want to migrate remain as conflicts — handle per the conflict resolution below.

Conflict resolution

From Phase 1's conflicts array (minus any migrated aliases) plus any new name collisions you can predict against the computed canonical aliases, ask the user per conflict via AskUserQuestion:

• Replace the pre-existing entry with the skill-managed version
• Rename the canonical alias to avoid the collision
• Skip this backend/model combination

Never silently overwrite a conflict.

Phase 7 — Final review and confirm

Show the user a complete change summary before any write:

• canonical aliases to add (channel, model name, alias)
• shortcut aliases to add
• skill-managed entries to remove (from prior state)
• manual entries that will be preserved untouched
• backup paths that will be created under ${CLAUDE_PLUGIN_DATA}/backups/

Wait for explicit "yes, apply" via AskUserQuestion. Any other answer is a no-op exit.

Phase 8 — Persist state, then write files

Read ${CLAUDE_PLUGIN_ROOT}/skills/setup-aliases/references/write-guide.md for the full state schema, field meanings, and write order with script invocation examples.

Key rules (always in scope):

• Write state file first, then config.yaml, then zshrc — crash between steps must leave consistent state
• Pass discover.managed_model_aliases directly as prior_managed_aliases — same shape, no transform
• name = upstream model ID, alias = routable cc-* name — reversing them silently corrupts the merge
• If write_user_config.py returns ok: false, stop — no further writes
• If write_zshrc.sh fails, rollback config.yaml from its backup path

Phase 9 — Restart gate

~/.cli-proxy-api/merged-config.yaml is regenerated only when VibeProxy launches. Validation before the restart will read a stale routing table and produce false negatives. Use AskUserQuestion with these exact steps:

1. Quit VibeProxy completely from the menu bar
2. Relaunch VibeProxy
3. Enable all the backends you configured aliases for — turn every toggle on
4. Click done when all configured backends are active

Do not skip this step. Do not proceed to validation before the user confirms.

Phase 10 — Per-alias validation

Each validation call sends a real (billable) inference request. If the user has many aliases, warn them about the per-alias cost before proceeding.

Critical: use the request_model value — the same model name the shell alias sends. With fork: false (default), the original upstream model name is replaced by the alias name in VibeProxy's registry. The alias name is the only routable name — sending the original upstream name (e.g., claude-opus-4-6-thinking or gpt-5.4) will fail with "unknown provider". For effort-suffix models, the shell alias sends the alias name with the effort suffix appended (e.g., cc-codex-gpt54-med(medium)), and VibeProxy parses the suffix at request time.

For each canonical alias, use its request_model field (the value that goes into ANTHROPIC_MODEL):

curl -s -o /tmp/vp_val.json -w '%{http_code}\n' \
  -X POST http://localhost:8318/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

Where ` is the requestmodel field from canonicalaliases — always alias-based (e.g., cc-gravity-opus46 for base models, cc-codex-gpt54-med(medium)` for effort models).

Use max_tokens:16 — many models enforce a minimum of 16 tokens and rejec

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: LeeJuOh
• Source: LeeJuOh/claude-code-zero
• License: MIT

Install and usage instructions live in the source repository linked above.