Problem

• Claude provider workflows can only reference built-in Claude model names directly.
• Teams routing Claude Code through Anthropic-compatible gateways need stable friendly aliases, provider-specific base URLs, credentials, and optional headers without hardcoding long model IDs in every workflow.
• This comes up for users who run multiple Claude-compatible gateways or local providers and want behavior similar to Pi agent custom model aliases.

Proposed Solution

Add a Claude custom model registry loaded from ~/.archon/claude-models.json. The registry maps provider/name aliases to provider model IDs and injects Claude Code environment variables for the selected provider.

Supported non-sensitive config shape:

{
  "providers": {
    "gateway": {
      "baseUrl": "https://llm-gateway.example.com",
      "apiKey": "YOUR_GATEWAY_API_KEY",
      "headers": {
        "X-Team": "platform"
      },
      "models": [
        { "id": "openai/gpt-5.4", "name": "gpt" }
      ]
    }
  }
}

User Flow

Before (current)

User            Archon Claude provider            Claude Code
────            ──────────────────────            ───────────
sets model ───▶ passes model string directly ───▶ uses default Claude endpoint
[!] gateway base URL, credentials, and aliases must be handled outside Archon

After (proposed)

User            Archon Claude provider                         Claude Code
────            ──────────────────────                         ───────────
defines ~/.archon/claude-models.json
uses gateway/gpt ───────────────▶ resolves alias to model ID
                                [injects provider env] ───────▶ calls gateway endpoint

Alternatives Considered

Scope

• Package(s) likely affected: providers, docs, tests
• Breaking change? No
• Database changes needed? No
• New external dependencies? No

Security Considerations

• New permissions/capabilities? No
• New external network calls? No
• Secrets/tokens handling? Yes

The feature reads credentials from a user-owned global config file and injects them only into the Claude Code subprocess for matched custom models. Documentation and example files must use placeholders only and must not include real keys or URLs.

Definition of Done

• Claude provider resolves provider/name aliases from ~/.archon/claude-models.json
• Provider-specific ANTHROPIC_BASE_URL, ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN, and optional ANTHROPIC_CUSTOM_HEADERS are passed to Claude Code
• Built-in Claude model behavior remains pass-through
• Tests cover registry parsing, alias resolution, env injection, and provider SDK options
• Documentation and non-sensitive example file are added