Add GitHub Models provider (#989)

## Problem

FCC does not expose GitHub Models, so users with GitHub Models access
cannot route Claude, Codex, or messaging prompts through GitHub's hosted
model catalog.

## Changes

| Before | After |
| --- | --- |
| Provider catalog did not include GitHub Models. | Provider catalog
includes `github_models` with token, proxy, admin, smoke, and model
picker wiring. |
| Requests could not target GitHub Models inference. |
`providers/github_models` routes OpenAI-chat requests to
`https://models.github.ai/inference`. |
| Model discovery assumed provider `/models` compatibility. | GitHub
Models discovery uses the catalog API and advertises stream/tool-capable
models. |
| OpenAI-chat transport could not set provider default headers. |
OpenAI-chat transport accepts provider-owned default headers. |
| Docs and templates omitted GitHub Models setup. | README,
`.env.example`, and architecture docs document GitHub Models setup and
ownership. |

<!-- greptile_comment -->

<details open><summary><h3>Greptile Summary</h3></summary>

This PR adds GitHub Models as a new provider. The main changes are:

- New `github_models` provider runtime, catalog, settings, and admin
wiring.
- OpenAI-chat transport support for provider-owned default headers.
- GitHub Models catalog discovery filtered to streaming and tool-capable
models.
- Smoke configuration, environment template, docs, and tests for the new
provider.
- Package version and lockfile updates for the new feature.
</details>

<h3>Confidence Score: 5/5</h3>

Safe to merge with low risk.

The provider is wired through runtime creation, catalog metadata,
settings, admin fields, smoke config, docs, version metadata, and
focused tests. No blocking correctness or security issues were found in
the changed paths.

No files require special attention.

<details><summary><h3><a href="https://www.greptile.com/trex"><img
alt="T-Rex"
src="https://greptile-static-assets.s3.amazonaws.com/trex/trex_green.svg"
height="20" align="absmiddle"></a> T-Rex Logs</h3></summary>

**What T-Rex did**
- Before-change focused pytest run against HEAD^ showed no GitHub Models
provider tests were collected.
- After-change focused pytest run showed all 37 provider/runtime tests
passed.
- After-change harness output captured structured evidence for catalog
discovery and OpenAI-chat request routing, and the harness exited
successfully.
- A temporary harness Python script was generated to capture the mocked
request/response evidence.

<a
href="https://app.greptile.com/trex/runs/13317138/artifacts"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://greptile-static-assets.s3.amazonaws.com/badges/ViewAllArtifactsDark.svg?v=4"><source
media="(prefers-color-scheme: light)"
srcset="https://greptile-static-assets.s3.amazonaws.com/badges/ViewAllArtifacts.svg?v=4"><img
alt="View all artifacts"
src="https://greptile-static-assets.s3.amazonaws.com/badges/ViewAllArtifacts.svg?v=4"></picture></a>

_{<a href="https://www.greptile.com/trex"><img alt="T-Rex"
src="https://greptile-static-assets.s3.amazonaws.com/trex/trex_green.svg"
height="14" align="absmiddle"></a> Ran code and verified through
T-Rex}
</details>

<details open><summary><h3>Important Files Changed</h3></summary>

| Filename | Overview |
|----------|----------|
| providers/github_models/client.py | Implements GitHub Models
OpenAI-chat transport wiring, default GitHub headers, and catalog-based
stream/tool-capable model discovery. |
| providers/transports/openai_chat/transport.py | Allows OpenAI-chat
providers to pass default headers into the shared AsyncOpenAI client. |
| config/provider_catalog.py | Registers GitHub Models provider
metadata, default inference base URL, credential, proxy, and
capabilities. |
| config/settings.py | Adds settings bindings for `GITHUB_MODELS_TOKEN`
and `GITHUB_MODELS_PROXY`. |
| api/admin_config/provider_manifest.py | Adds GitHub Models token
labeling and description for generated admin provider fields. |
| smoke/lib/config.py | Adds GitHub Models smoke defaults and credential
detection. |
| tests/providers/test_github_models.py | Adds focused tests for GitHub
Models initialization, request conversion, catalog filtering, streaming,
tool calls, reasoning, and cleanup. |
| tests/providers/test_provider_runtime.py | Covers GitHub Models
descriptor, provider config construction, and runtime instantiation. |
| README.md | Adds GitHub Models setup documentation and updates
provider counts/numbering. |
| pyproject.toml | Bumps the package version to `3.2.0` for the new
provider feature. |

</details>

<details open><summary><h3>Sequence Diagram</h3></summary>

<a href="#gh-light-mode-only">

```mermaid
%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
participant User as Claude/Codex client
participant FCC as FCC proxy/router
participant Factory as Provider runtime factory
participant GH as GitHubModelsProvider
participant OpenAI as Shared OpenAI-chat transport
participant API as models.github.ai

User->>FCC: Request with model `github_models/...`
FCC->>Factory: create_provider(`github_models`, settings)
Factory->>GH: ProviderConfig(token, base_url, proxy)
GH->>OpenAI: Initialize with GitHub default headers
FCC->>GH: stream_response(MessagesRequest)
GH->>OpenAI: build OpenAI chat body
OpenAI->>API: "POST /inference/chat/completions (stream=true)"
API-->>OpenAI: OpenAI-compatible stream chunks
OpenAI-->>FCC: Anthropic SSE events
FCC-->>User: Streamed Anthropic response

FCC->>GH: list_model_infos()
GH->>API: GET /catalog/models
API-->>GH: Catalog entries with capabilities
GH-->>FCC: stream/tool-capable model ids
```

</a>
<a href="#gh-dark-mode-only">

```mermaid
%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
participant User as Claude/Codex client
participant FCC as FCC proxy/router
participant Factory as Provider runtime factory
participant GH as GitHubModelsProvider
participant OpenAI as Shared OpenAI-chat transport
participant API as models.github.ai

User->>FCC: Request with model `github_models/...`
FCC->>Factory: create_provider(`github_models`, settings)
Factory->>GH: ProviderConfig(token, base_url, proxy)
GH->>OpenAI: Initialize with GitHub default headers
FCC->>GH: stream_response(MessagesRequest)
GH->>OpenAI: build OpenAI chat body
OpenAI->>API: "POST /inference/chat/completions (stream=true)"
API-->>OpenAI: OpenAI-compatible stream chunks
OpenAI-->>FCC: Anthropic SSE events
FCC-->>User: Streamed Anthropic response

FCC->>GH: list_model_infos()
GH->>API: GET /catalog/models
API-->>GH: Catalog entries with capabilities
GH-->>FCC: stream/tool-capable model ids
```

</a>
</details>

_{Reviews (1): Last reviewed commit: ["Add GitHub Models
provider"](https://github.com/alishahryar1/free-claude-code/commit/736d3f9213f6a8d243d4001c5135b7fac402f143)
| [Re-trigger
Greptile](https://app.greptile.com/api/retrigger?id=41901295)}

<!-- /greptile_comment -->

.env.example

@@ -46,6 +46,10 @@ HUGGINGFACE_API_KEY=""
 COHERE_API_KEY=""
 
 
+# GitHub Models Config (OpenAI-compatible Chat Completions at models.github.ai/inference)
+GITHUB_MODELS_TOKEN=""
+
+
 # Z.ai Config (Anthropic-compatible Messages at api.z.ai/api/anthropic/v1)
 ZAI_API_KEY=""
 
@@ -85,7 +89,7 @@ OLLAMA_BASE_URL="http://localhost:11434"
 
 # All Claude model requests are mapped to these models, plain model is fallback
 # Format: provider_type/model/name
-# Valid providers: "nvidia_nim" | "open_router" | "gemini" | "deepseek" | "mistral" | "mistral_codestral" | "opencode" | "opencode_go" | "vercel" | "huggingface" | "cohere" | "wafer" | "kimi" | "minimax" | "cerebras" | "groq" | "fireworks" | "cloudflare" | "zai" | "lmstudio" | "llamacpp" | "ollama"
+# Valid providers: "nvidia_nim" | "open_router" | "gemini" | "deepseek" | "mistral" | "mistral_codestral" | "opencode" | "opencode_go" | "vercel" | "huggingface" | "cohere" | "github_models" | "wafer" | "kimi" | "minimax" | "cerebras" | "groq" | "fireworks" | "cloudflare" | "zai" | "lmstudio" | "llamacpp" | "ollama"
 MODEL_OPUS=
 MODEL_SONNET=
 MODEL_HAIKU=
@@ -110,6 +114,7 @@ FCC_SMOKE_MODEL_OPENCODE_GO=
 FCC_SMOKE_MODEL_VERCEL=
 FCC_SMOKE_MODEL_HUGGINGFACE=
 FCC_SMOKE_MODEL_COHERE=
+FCC_SMOKE_MODEL_GITHUB_MODELS=
 FCC_SMOKE_MODEL_ZAI=
 FCC_SMOKE_MODEL_FIREWORKS=
 FCC_SMOKE_MODEL_CLOUDFLARE=
@@ -147,6 +152,7 @@ OPENCODE_GO_PROXY=""
 VERCEL_AI_GATEWAY_PROXY=""
 HUGGINGFACE_PROXY=""
 COHERE_PROXY=""
+GITHUB_MODELS_PROXY=""
 ZAI_PROXY=""
 FIREWORKS_PROXY=""
 CLOUDFLARE_PROXY=""

ARCHITECTURE.md

@@ -371,11 +371,11 @@ where supported, and returning Anthropic SSE strings to the service layer.
 Provider-specific inputs that do not apply to other upstreams, such as
 Cloudflare's account ID, stay in that provider's factory/client instead of being
 added to shared `ProviderConfig`.
-Gateway providers such as Vercel AI Gateway, Hugging Face, and Cohere stay thin
-when their documented OpenAI-compatible Chat Completions behavior matches shared
-transport policy. Provider-specific gateway quirks, such as Cohere's supported
-`reasoning_effort` values and unsupported compatibility fields, stay in that
-provider package.
+Gateway providers such as Vercel AI Gateway, Hugging Face, Cohere, and GitHub
+Models stay thin when their documented OpenAI-compatible Chat Completions
+behavior matches shared transport policy. Provider-specific gateway quirks, such
+as Cohere's supported `reasoning_effort` values, GitHub's API headers/catalog
+filtering, and unsupported compatibility fields, stay in that provider package.
 
 ### Adding A Provider
 

README.md

@@ -57,7 +57,7 @@ Free Claude Code routes Anthropic Messages API traffic from Claude Code (CLI and
 - Drop-in proxy for Claude Code's Anthropic API calls (`/v1/messages`, `/v1/models`).
 - Drop-in proxy for Codex via the OpenAI Responses API (`/v1/responses`).
 - `fcc-claude` and `fcc-codex` launchers that read the current Admin UI port and auth token each time they start.
-- 22 provider backends: NVIDIA NIM, OpenRouter, Google AI Studio (Gemini), DeepSeek, Mistral La Plateforme, Mistral Codestral, OpenCode Zen, OpenCode Go, Vercel AI Gateway, Hugging Face Inference Providers, Cohere, Wafer, Kimi, MiniMax, Cerebras Inference, Groq, Fireworks AI, Cloudflare, Z.ai, LM Studio, llama.cpp, and Ollama.
+- 23 provider backends: NVIDIA NIM, OpenRouter, Google AI Studio (Gemini), DeepSeek, Mistral La Plateforme, Mistral Codestral, OpenCode Zen, OpenCode Go, Vercel AI Gateway, Hugging Face Inference Providers, Cohere, GitHub Models, Wafer, Kimi, MiniMax, Cerebras Inference, Groq, Fireworks AI, Cloudflare, Z.ai, LM Studio, llama.cpp, and Ollama.
 - Per-model routing for Claude Code: send Opus, Sonnet, Haiku, and fallback traffic to different providers.
 - Native Claude Code `/model` picker support through the proxy's `/v1/models` endpoint (see [Model Picker](#model-picker)).
 - Native Codex `/model` picker support when launched through `fcc-codex`, using a generated local model catalog.
@@ -285,7 +285,17 @@ Cohere routes through its OpenAI-compatible Compatibility API at `https://api.co
 
 Browse models at [Cohere models](https://docs.cohere.com/docs/models).
 
-### 12. [Wafer](https://wafer.ai/)
+### 12. [GitHub Models](https://github.com/marketplace?type=models)
+
+Create a GitHub personal access token with Models access, then paste it into `GITHUB_MODELS_TOKEN` in the Admin UI.
+
+Set `MODEL` to a GitHub Models slug such as `github_models/openai/gpt-4.1`.
+
+GitHub Models routes through the OpenAI-compatible inference endpoint at `https://models.github.ai/inference`. FCC keeps GitHub-specific API headers and catalog filtering in the GitHub Models provider; only catalog models that advertise streaming and tool-calling are shown through model discovery.
+
+Browse models at [GitHub Marketplace Models](https://github.com/marketplace?type=models).
+
+### 13. [Wafer](https://wafer.ai/)
 
 Get a key from [wafer.ai](https://wafer.ai). In the Admin UI, paste it into `WAFER_API_KEY`, then set `MODEL` to a Wafer Pass model such as `wafer/DeepSeek-V4-Pro`.
 
@@ -298,7 +308,7 @@ Popular examples:
 
 This provider uses Wafer's Anthropic-compatible endpoint at `https://pass.wafer.ai/v1/messages`.
 
-### 13. [Kimi](https://platform.moonshot.ai/)
+### 14. [Kimi](https://platform.moonshot.ai/)
 
 Get a key at [platform.moonshot.ai/console/api-keys](https://platform.moonshot.ai/console/api-keys).
 
@@ -308,7 +318,7 @@ This provider calls Kimi's **Anthropic-compatible** Messages API (`https://api.m
 
 Browse models at [platform.moonshot.ai](https://platform.moonshot.ai).
 
-### 14. [MiniMax](https://platform.minimax.io/)
+### 15. [MiniMax](https://platform.minimax.io/)
 
 Get a key from [MiniMax](https://platform.minimax.io/user-center/basic-information/interface-key).
 
@@ -316,7 +326,7 @@ In the Admin UI, paste it into `MINIMAX_API_KEY`, then set `MODEL` to a MiniMax
 
 This provider calls MiniMax's **Anthropic-compatible** Messages API (`https://api.minimax.io/anthropic/v1/messages`). `MiniMax-M3` is the recommended default because MiniMax documents controllable Anthropic thinking for that model; other MiniMax models remain discoverable through the provider model list.
 
-### 15. [Cerebras Inference](https://inference-docs.cerebras.ai/quickstart)
+### 16. [Cerebras Inference](https://inference-docs.cerebras.ai/quickstart)
 
 Sign up and create an API key in the [Cerebras Cloud Console](https://cloud.cerebras.ai) (see [Quickstart](https://inference-docs.cerebras.ai/quickstart)).
 
@@ -324,7 +334,7 @@ In the Admin UI, set `CEREBRAS_API_KEY`, then route with `MODEL` such as `cerebr
 
 Cerebras exposes an OpenAI-compatible API at `https://api.cerebras.ai/v1` ([OpenAI compatibility](https://inference-docs.cerebras.ai/resources/openai)). Non-standard request fields should go in `extra_body` when using the OpenAI client; see the same page. For reasoning models and parameters, see [Reasoning](https://inference-docs.cerebras.ai/capabilities/reasoning). This proxy follows other OpenAI-compat adapters for thinking via `reasoning_content` when Claude-style thinking is enabled.
 
-### 16. [Groq](https://console.groq.com/)
+### 17. [Groq](https://console.groq.com/)
 
 Get an API key at [console.groq.com/keys](https://console.groq.com/keys).
 
@@ -336,7 +346,7 @@ Reasoning-heavy models expose extra knobs documented under [Groq reasoning](http
 
 Browse models at [console.groq.com/docs/models](https://console.groq.com/docs/models).
 
-### 17. [Fireworks AI](https://fireworks.ai/)
+### 18. [Fireworks AI](https://fireworks.ai/)
 
 Get an API key at [fireworks.ai/account/api-keys](https://fireworks.ai/account/api-keys).
 
@@ -346,7 +356,7 @@ Fireworks exposes an **Anthropic-compatible** Messages API at `https://api.firew
 
 Browse models at [fireworks.ai/models](https://fireworks.ai/models).
 
-### 18. [Cloudflare](https://developers.cloudflare.com/workers-ai/)
+### 19. [Cloudflare](https://developers.cloudflare.com/workers-ai/)
 
 Create a Cloudflare API token and copy your account ID from the Cloudflare dashboard.
 
@@ -354,7 +364,7 @@ In the Admin UI, set `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID`, then se
 
 This provider calls Cloudflare's account-scoped **OpenAI-compatible** Chat Completions API at `https://api.cloudflare.com/client/v4/accounts/<account_id>/ai/v1/chat/completions`. Use literal Workers AI model IDs, including the `@cf/` prefix when the catalog model includes it.
 
-### 19. [Z.ai](https://z.ai/)
+### 20. [Z.ai](https://z.ai/)
 
 Get an API key at [Z.ai/manage-apikey/apikey-list](https://z.ai/manage-apikey/apikey-list).
 
@@ -369,13 +379,13 @@ Popular examples:
 
 Browse models at [Z.ai](https://z.ai).
 
-### 20. [LM Studio](https://lmstudio.ai/)
+### 21. [LM Studio](https://lmstudio.ai/)
 
 Start LM Studio's local server and load a model. In the Admin UI, keep or update `LM_STUDIO_BASE_URL`, then set `MODEL` to the model identifier shown by LM Studio, prefixed with `lmstudio/`.
 
 Prefer models with tool-use support for Claude Code workflows.
 
-### 21. [llama.cpp](https://github.com/ggml-org/llama.cpp)
+### 22. [llama.cpp](https://github.com/ggml-org/llama.cpp)
 
 Start `llama-server` with an Anthropic-compatible `/v1/messages` endpoint and enough context for Claude Code requests.
 
@@ -383,7 +393,7 @@ In the Admin UI, keep or update `LLAMACPP_BASE_URL`, then set `MODEL` to the loc
 
 For local coding models, context size matters. If llama.cpp returns HTTP 400 for normal Claude Code requests, increase `--ctx-size` and verify the model/server build supports the requested features.
 
-### 22. [Ollama](https://ollama.com/)
+### 23. [Ollama](https://ollama.com/)
 
 Run Ollama and pull a model:
 
@@ -396,7 +406,7 @@ In the Admin UI, keep or update `OLLAMA_BASE_URL`, then set `MODEL` to the same
 
 `OLLAMA_BASE_URL` is the Ollama server root; do not append `/v1`. Example model slugs include `ollama/llama3.1` and `ollama/llama3.1:8b`.
 
-### 23. Mix Providers By Model Tier
+### 24. Mix Providers By Model Tier
 
 Each model tier can use a different provider by setting `MODEL_OPUS`, `MODEL_SONNET`, and `MODEL_HAIKU` in the Admin UI. Leave a tier blank to inherit `MODEL`. These tier overrides apply to Claude model names that contain `opus`, `sonnet`, or `haiku`. Codex uses the Admin `MODEL` default through `fcc-codex` unless a session requests a provider-prefixed slug directly.
 
@@ -610,7 +620,7 @@ Important pieces:
 - Responses requests convert to Anthropic Messages internally, then share the same model router, normalizer, and provider adapters.
 - `fcc-codex` registers a custom `fcc` provider that points Codex at the local proxy's `/v1/responses` endpoint.
 - Model routing resolves Claude model names to `MODEL_OPUS`, `MODEL_SONNET`, `MODEL_HAIKU`, or `MODEL`.
-- NIM, Gemini, DeepSeek, Mistral, Codestral, OpenCode Zen, OpenCode Go, Vercel AI Gateway, Hugging Face, Cohere, Cerebras, Groq, and Cloudflare use OpenAI chat streaming translated into Anthropic SSE.
+- NIM, Gemini, DeepSeek, Mistral, Codestral, OpenCode Zen, OpenCode Go, Vercel AI Gateway, Hugging Face, Cohere, GitHub Models, Cerebras, Groq, and Cloudflare use OpenAI chat streaming translated into Anthropic SSE.
 - Wafer, OpenRouter, Kimi, MiniMax, Fireworks AI, Z.ai, LM Studio, llama.cpp, and Ollama use Anthropic Messages style transports where applicable (with provider-specific quirks and model-list URLs).
 - The proxy normalizes thinking blocks, tool calls, token usage metadata, and provider errors into the shape each client expects.
 - Request optimizations answer trivial Claude Code probes locally to save latency and quota.

api/admin_config/manifest.py

@@ -574,6 +574,12 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
         "smoke",
         advanced=True,
     ),
+    ConfigFieldSpec(
+        "FCC_SMOKE_MODEL_GITHUB_MODELS",
+        "Smoke GitHub Models Model",
+        "smoke",
+        advanced=True,
+    ),
     ConfigFieldSpec(
         "FCC_SMOKE_MODEL_ZAI",
         "Smoke Z.ai Model",

api/admin_config/provider_manifest.py

@@ -48,6 +48,13 @@ _PROVIDER_FIELD_OVERRIDES: dict[str, dict[str, Any]] = {
         "label": "Cohere API Key",
         "description": "Cohere API key for the OpenAI-compatible Compatibility API.",
     },
+    "GITHUB_MODELS_TOKEN": {
+        "label": "GitHub Models Token",
+        "description": (
+            "GitHub token with Models access for the OpenAI-compatible inference API "
+            "at models.github.ai."
+        ),
+    },
     "ZAI_API_KEY": {
         "label": "Z.ai API Key",
         "description": "Z.ai Coding Plan API key.",

config/provider_catalog.py

@@ -32,6 +32,7 @@ OPENCODE_GO_DEFAULT_BASE = "https://opencode.ai/zen/go/v1"
 VERCEL_AI_GATEWAY_DEFAULT_BASE = "https://ai-gateway.vercel.sh/v1"
 HUGGINGFACE_DEFAULT_BASE = "https://router.huggingface.co/v1"
 COHERE_DEFAULT_BASE = "https://api.cohere.ai/compatibility/v1"
+GITHUB_MODELS_DEFAULT_BASE = "https://models.github.ai/inference"
 # Z.ai Anthropic-compatible Messages API (not OpenAI Coding Plan chat completions).
 ZAI_DEFAULT_BASE = "https://api.z.ai/api/anthropic/v1"
 # Google AI Studio Gemini API OpenAI-compat layer (not Vertex AI).
@@ -178,6 +179,17 @@ PROVIDER_CATALOG: dict[str, ProviderDescriptor] = {
         proxy_attr="cohere_proxy",
         capabilities=("chat", "streaming", "tools", "thinking", "rate_limit"),
     ),
+    "github_models": ProviderDescriptor(
+        provider_id="github_models",
+        display_name="GitHub Models",
+        transport_type="openai_chat",
+        credential_env="GITHUB_MODELS_TOKEN",
+        credential_url="https://github.com/settings/tokens",
+        credential_attr="github_models_token",
+        default_base_url=GITHUB_MODELS_DEFAULT_BASE,
+        proxy_attr="github_models_proxy",
+        capabilities=("chat", "streaming", "tools", "thinking", "rate_limit"),
+    ),
     "wafer": ProviderDescriptor(
         provider_id="wafer",
         display_name="Wafer",
@@ -338,9 +350,10 @@ PROVIDER_CATALOG: dict[str, ProviderDescriptor] = {
 
 # Key order:
 # NVIDIA NIM first (README default), DeepSeek fourth, OpenCode gateways adjacent,
-# Vercel / Hugging Face / Cohere follow gateway-style remotes, then native Anthropic
-# remotes and locals per project plan (github.com/cheahjs/free-llm-api-resources
-# Free Providers TOC as rough guide beyond fixed slots).
+# Vercel / Hugging Face / Cohere / GitHub Models follow gateway-style remotes,
+# then native Anthropic remotes and locals per project plan
+# (github.com/cheahjs/free-llm-api-resources Free Providers TOC as rough guide
+# beyond fixed slots).
 # ``SUPPORTED_PROVIDER_IDS`` inherits this insertion order for UI and error-message listing.
 SUPPORTED_PROVIDER_IDS: tuple[str, ...] = tuple(PROVIDER_CATALOG.keys())
 

config/settings.py

@@ -55,6 +55,9 @@ class Settings(BaseSettings):
     # ==================== Cohere Compatibility API ====================
     cohere_api_key: str = Field(default="", validation_alias="COHERE_API_KEY")
 
+    # ==================== GitHub Models ====================
+    github_models_token: str = Field(default="", validation_alias="GITHUB_MODELS_TOKEN")
+
     # ==================== Z.ai Config ====================
     zai_api_key: str = Field(default="", validation_alias="ZAI_API_KEY")
 
@@ -139,6 +142,7 @@ class Settings(BaseSettings):
     )
     huggingface_proxy: str = Field(default="", validation_alias="HUGGINGFACE_PROXY")
     cohere_proxy: str = Field(default="", validation_alias="COHERE_PROXY")
+    github_models_proxy: str = Field(default="", validation_alias="GITHUB_MODELS_PROXY")
     zai_proxy: str = Field(default="", validation_alias="ZAI_PROXY")
     fireworks_proxy: str = Field(default="", validation_alias="FIREWORKS_PROXY")
     cloudflare_proxy: str = Field(default="", validation_alias="CLOUDFLARE_PROXY")

providers/defaults.py

@@ -7,6 +7,7 @@ from config.provider_catalog import (
     COHERE_DEFAULT_BASE,
     DEEPSEEK_DEFAULT_BASE,
     GEMINI_DEFAULT_BASE,
+    GITHUB_MODELS_DEFAULT_BASE,
     GROQ_DEFAULT_BASE,
     HUGGINGFACE_DEFAULT_BASE,
     KIMI_DEFAULT_BASE,
@@ -31,6 +32,7 @@ __all__ = (
     "COHERE_DEFAULT_BASE",
     "DEEPSEEK_DEFAULT_BASE",
     "GEMINI_DEFAULT_BASE",
+    "GITHUB_MODELS_DEFAULT_BASE",
     "GROQ_DEFAULT_BASE",
     "HUGGINGFACE_DEFAULT_BASE",
     "KIMI_DEFAULT_BASE",

providers/github_models/__init__.py

@@ -0,0 +1,7 @@
+"""GitHub Models provider."""
+
+from providers.defaults import GITHUB_MODELS_DEFAULT_BASE
+
+from .client import GitHubModelsProvider
+
+__all__ = ["GITHUB_MODELS_DEFAULT_BASE", "GitHubModelsProvider"]

providers/github_models/client.py

@@ -0,0 +1,142 @@
+"""GitHub Models provider using OpenAI-compatible chat completions."""
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+import httpx
+
+from providers.base import ProviderConfig
+from providers.defaults import GITHUB_MODELS_DEFAULT_BASE
+from providers.exceptions import ModelListResponseError
+from providers.model_listing import ProviderModelInfo, model_infos_from_ids
+from providers.transports.http import maybe_await_aclose
+from providers.transports.openai_chat import (
+    OpenAIChatRequestPolicy,
+    OpenAIChatTransport,
+    build_openai_chat_request_body,
+)
+
+GITHUB_MODELS_CATALOG_URL = "https://models.github.ai/catalog/models"
+GITHUB_MODELS_API_VERSION = "2026-03-10"
+
+_REQUEST_POLICY = OpenAIChatRequestPolicy(
+    provider_name="GITHUB_MODELS",
+)
+_REQUIRED_MODEL_CAPABILITIES = frozenset({"streaming", "tool-calling"})
+
+
+class GitHubModelsProvider(OpenAIChatTransport):
+    """GitHub Models OpenAI-compatible inference provider."""
+
+    def __init__(self, config: ProviderConfig):
+        self._catalog_url = GITHUB_MODELS_CATALOG_URL
+        self._model_list_client = httpx.AsyncClient(
+            proxy=config.proxy or None,
+            timeout=httpx.Timeout(
+                config.http_read_timeout,
+                connect=config.http_connect_timeout,
+                read=config.http_read_timeout,
+                write=config.http_write_timeout,
+            ),
+        )
+        super().__init__(
+            config,
+            provider_name="GITHUB_MODELS",
+            base_url=config.base_url or GITHUB_MODELS_DEFAULT_BASE,
+            api_key=config.api_key,
+            default_headers=_github_models_default_headers(),
+        )
+
+    async def cleanup(self) -> None:
+        """Release provider client resources."""
+        await super().cleanup()
+        await self._model_list_client.aclose()
+
+    async def list_model_ids(self) -> frozenset[str]:
+        """Return GitHub Models ids that support FCC's streaming tool workflow."""
+        return frozenset(info.model_id for info in await self.list_model_infos())
+
+    async def list_model_infos(self) -> frozenset[ProviderModelInfo]:
+        """Return stream/tool-capable GitHub Models catalog ids."""
+        response = await self._model_list_client.get(
+            self._catalog_url,
+            headers=self._model_list_headers(),
+        )
+        try:
+            response.raise_for_status()
+            try:
+                payload = response.json()
+            except ValueError as exc:
+                raise ModelListResponseError(
+                    "GITHUB_MODELS model-list response is malformed: invalid JSON"
+                ) from exc
+            return model_infos_from_ids(
+                _extract_supported_github_model_ids(payload),
+            )
+        finally:
+            await maybe_await_aclose(response)
+
+    def _build_request_body(
+        self, request: Any, thinking_enabled: bool | None = None
+    ) -> dict:
+        return build_openai_chat_request_body(
+            request,
+            thinking_enabled=self._is_thinking_enabled(request, thinking_enabled),
+            policy=_REQUEST_POLICY,
+        )
+
+    def _model_list_headers(self) -> dict[str, str]:
+        return _github_models_api_headers(self._api_key)
+
+
+def _github_models_default_headers() -> dict[str, str]:
+    return {
+        "Accept": "application/vnd.github+json",
+        "X-GitHub-Api-Version": GITHUB_MODELS_API_VERSION,
+    }
+
+
+def _github_models_api_headers(api_key: str) -> dict[str, str]:
+    return {
+        **_github_models_default_headers(),
+        "Authorization": f"Bearer {api_key}",
+    }
+
+
+def _extract_supported_github_model_ids(payload: Any) -> frozenset[str]:
+    """Extract stream/tool-capable model ids from GitHub's catalog array."""
+    if not _is_sequence(payload):
+        raise ModelListResponseError(
+            "GITHUB_MODELS model-list response is malformed: expected top-level array"
+        )
+
+    model_ids: set[str] = set()
+    for item in payload:
+        if not isinstance(item, Mapping):
+            raise ModelListResponseError(
+                "GITHUB_MODELS model-list response is malformed: expected every item to be an object"
+            )
+        model_id = item.get("id")
+        if not isinstance(model_id, str) or not model_id.strip():
+            raise ModelListResponseError(
+                "GITHUB_MODELS model-list response is malformed: expected every item to include id"
+            )
+        capabilities = item.get("capabilities")
+        if not _supports_streaming_tools(capabilities):
+            continue
+        model_ids.add(model_id)
+
+    return frozenset(model_ids)
+
+
+def _supports_streaming_tools(capabilities: Any) -> bool:
+    if not _is_sequence(capabilities):
+        return False
+    capability_names = {item for item in capabilities if isinstance(item, str)}
+    return capability_names >= _REQUIRED_MODEL_CAPABILITIES
+
+
+def _is_sequence(value: Any) -> bool:
+    return isinstance(value, Sequence) and not isinstance(
+        value, str | bytes | bytearray
+    )

providers/runtime/factory.py

@@ -113,6 +113,12 @@ def _create_cohere(config: ProviderConfig, _settings: Settings) -> BaseProvider:
     return CohereProvider(config)
 
 
+def _create_github_models(config: ProviderConfig, _settings: Settings) -> BaseProvider:
+    from providers.github_models import GitHubModelsProvider
+
+    return GitHubModelsProvider(config)
+
+
 def _create_zai(config: ProviderConfig, _settings: Settings) -> BaseProvider:
     from providers.zai import ZaiProvider
 
@@ -161,6 +167,7 @@ PROVIDER_FACTORIES: dict[str, ProviderFactory] = {
     "vercel": _create_vercel,
     "huggingface": _create_huggingface,
     "cohere": _create_cohere,
+    "github_models": _create_github_models,
     "wafer": _create_wafer,
     "kimi": _create_kimi,
     "minimax": _create_minimax,

providers/transports/openai_chat/transport.py

@@ -1,7 +1,7 @@
 """OpenAI-compatible chat transport base."""
 
 from abc import abstractmethod
-from collections.abc import AsyncIterator, Iterator
+from collections.abc import AsyncIterator, Iterator, Mapping
 from typing import Any
 
 import httpx
@@ -30,6 +30,7 @@ class OpenAIChatTransport(BaseProvider):
         provider_name: str,
         base_url: str,
         api_key: str,
+        default_headers: Mapping[str, str] | None = None,
     ):
         super().__init__(config)
         self._provider_name = provider_name
@@ -56,6 +57,7 @@ class OpenAIChatTransport(BaseProvider):
             api_key=self._api_key,
             base_url=self._base_url,
             max_retries=0,
+            default_headers=default_headers,
             timeout=httpx.Timeout(
                 config.http_read_timeout,
                 connect=config.http_connect_timeout,

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "free-claude-code"
-version = "3.1.0"
+version = "3.2.0"
 description = "Middleware between Claude Code CLI (Anthropic API) and NVIDIA NIM"
 readme = "README.md"
 requires-python = ">=3.14.0"

smoke/lib/config.py

@@ -56,6 +56,7 @@ PROVIDER_SMOKE_DEFAULT_MODELS: dict[str, str] = {
     "vercel": "vercel/openai/gpt-5.5",
     "huggingface": "huggingface/openai/gpt-oss-120b:fastest",
     "cohere": "cohere/command-a-plus-05-2026",
+    "github_models": "github_models/openai/gpt-4.1",
     "zai": "zai/glm-5.1",
     "gemini": "gemini/models/gemini-3.1-flash-lite",
     "groq": "groq/llama-3.3-70b-versatile",
@@ -261,6 +262,8 @@ class SmokeConfig:
             return bool(self.settings.huggingface_api_key.strip())
         if provider == "cohere":
             return bool(self.settings.cohere_api_key.strip())
+        if provider == "github_models":
+            return bool(self.settings.github_models_token.strip())
         if provider == "zai":
             return bool(self.settings.zai_api_key.strip())
         if provider == "gemini":

tests/api/test_admin.py

@@ -29,6 +29,7 @@ def _clear_process_config(monkeypatch) -> None:
         "FCC_ENV_FILE",
         "CLOUDFLARE_API_TOKEN",
         "CLOUDFLARE_ACCOUNT_ID",
+        "GITHUB_MODELS_TOKEN",
         "HOST",
         "PORT",
         "LOG_FILE",
@@ -105,6 +106,7 @@ def test_admin_config_masks_secrets_and_exposes_manifest(monkeypatch, tmp_path):
     assert "FIREWORKS_API_KEY" in keys
     assert "CLOUDFLARE_API_TOKEN" in keys
     assert "CLOUDFLARE_ACCOUNT_ID" in keys
+    assert "GITHUB_MODELS_TOKEN" in keys
     assert "GEMINI_API_KEY" in keys
     assert "GROQ_API_KEY" in keys
     assert "CEREBRAS_API_KEY" in keys
@@ -365,6 +367,33 @@ def test_admin_apply_writes_cohere_key_and_masks_preview(monkeypatch, tmp_path):
     assert "COHERE_API_KEY=cohere-secret" in text
 
 
+def test_admin_apply_writes_github_models_token_and_masks_preview(
+    monkeypatch, tmp_path
+):
+    _set_home(monkeypatch, tmp_path)
+    _clear_process_config(monkeypatch)
+    app = create_app(lifespan_enabled=False)
+
+    response = _local_client(app).post(
+        "/admin/api/config/apply",
+        json={
+            "values": {
+                "MODEL": "github_models/openai/gpt-4.1",
+                "GITHUB_MODELS_TOKEN": "github-secret",
+            }
+        },
+    )
+
+    assert response.status_code == 200
+    body = response.json()
+    assert body["applied"] is True
+    assert "GITHUB_MODELS_TOKEN=********" in body["env_preview"]
+    env_file = tmp_path / ".fcc" / ".env"
+    text = env_file.read_text(encoding="utf-8")
+    assert "MODEL=github_models/openai/gpt-4.1" in text
+    assert "GITHUB_MODELS_TOKEN=github-secret" in text
+
+
 def test_admin_apply_preserves_hidden_diagnostics_and_smoke_values(
     monkeypatch, tmp_path
 ):

tests/config/test_config.py

@@ -337,6 +337,16 @@ class TestSettings:
         assert settings.cohere_api_key == "cohere-key"
         assert settings.cohere_proxy == "http://proxy.test:8080"
 
+    def test_github_models_settings_from_env(self, monkeypatch):
+        """GitHub Models token and proxy env vars load into settings."""
+        from config.settings import Settings
+
+        monkeypatch.setenv("GITHUB_MODELS_TOKEN", "github-token")
+        monkeypatch.setenv("GITHUB_MODELS_PROXY", "http://proxy.test:8080")
+        settings = Settings()
+        assert settings.github_models_token == "github-token"
+        assert settings.github_models_proxy == "http://proxy.test:8080"
+
     def test_legacy_hf_token_env_is_ignored(self, monkeypatch):
         """HF_TOKEN is migrated by startup config migration, not read by Settings."""
         from config.settings import Settings
@@ -739,6 +749,11 @@ class TestPerModelMapping:
                 "cloudflare/@cf/moonshotai/kimi-k2.6",
                 None,
             ),
+            (
+                {"MODEL": "github_models/openai/gpt-4.1"},
+                "github_models/openai/gpt-4.1",
+                None,
+            ),
             ({"MODEL": "lmstudio/qwen2.5-7b"}, "lmstudio/qwen2.5-7b", None),
             ({"MODEL": "llamacpp/local-model"}, "llamacpp/local-model", None),
             ({"MODEL": "ollama/llama3.1"}, "ollama/llama3.1", None),
@@ -930,6 +945,7 @@ class TestPerModelMapping:
             == "huggingface"
         )
         assert parse_provider_type("cohere/command-a-plus-05-2026") == "cohere"
+        assert parse_provider_type("github_models/openai/gpt-4.1") == ("github_models")
         assert parse_provider_type("gemini/models/gemini-3.1-flash-lite") == "gemini"
         assert parse_provider_type("groq/llama-3.3-70b-versatile") == "groq"
         assert parse_provider_type("cerebras/llama3.1-8b") == "cerebras"
@@ -962,6 +978,7 @@ class TestPerModelMapping:
         assert parse_model_name("cohere/command-a-plus-05-2026") == (
             "command-a-plus-05-2026"
         )
+        assert parse_model_name("github_models/openai/gpt-4.1") == "openai/gpt-4.1"
         assert (
             parse_model_name("gemini/models/gemini-3.1-flash-lite")
             == "models/gemini-3.1-flash-lite"

tests/contracts/test_feature_manifest.py

@@ -10,6 +10,7 @@ from providers.cohere import CohereProvider
 from providers.deepseek import DeepSeekProvider
 from providers.fireworks import FireworksProvider
 from providers.gemini import GeminiProvider
+from providers.github_models import GitHubModelsProvider
 from providers.groq import GroqProvider
 from providers.huggingface import HuggingFaceProvider
 from providers.kimi import KimiProvider
@@ -98,6 +99,7 @@ def test_provider_and_platform_registries_include_advertised_builtins() -> None:
         "vercel": VercelProvider,
         "huggingface": HuggingFaceProvider,
         "cohere": CohereProvider,
+        "github_models": GitHubModelsProvider,
         "zai": ZaiProvider,
         "gemini": GeminiProvider,
         "groq": GroqProvider,

tests/contracts/test_provider_catalog_order.py

@@ -14,6 +14,7 @@ _EXPECTED_PROVIDER_ORDER: tuple[str, ...] = (
     "vercel",
     "huggingface",
     "cohere",
+    "github_models",
     "wafer",
     "kimi",
     "minimax",

tests/contracts/test_smoke_config.py

@@ -38,6 +38,7 @@ def _settings(**overrides):
         "vercel_ai_gateway_api_key": "",
         "huggingface_api_key": "",
         "cohere_api_key": "",
+        "github_models_token": "",
         "zai_api_key": "",
         "gemini_api_key": "",
         "groq_api_key": "",
@@ -243,6 +244,22 @@ def test_cohere_provider_configuration_uses_api_key(monkeypatch) -> None:
     assert models[0].full_model == PROVIDER_SMOKE_DEFAULT_MODELS["cohere"]
 
 
+def test_github_models_provider_configuration_uses_token(monkeypatch) -> None:
+    monkeypatch.delenv("FCC_SMOKE_MODEL_GITHUB_MODELS", raising=False)
+    config = _smoke_config(
+        settings=_settings(
+            model="ollama/llama3.1",
+            ollama_base_url="",
+            github_models_token="github-token",
+        )
+    )
+
+    assert config.has_provider_configuration("github_models")
+    models = config.provider_smoke_models()
+    assert models[0].provider == "github_models"
+    assert models[0].full_model == PROVIDER_SMOKE_DEFAULT_MODELS["github_models"]
+
+
 def test_provider_smoke_model_override_accepts_model_name_without_prefix(
     monkeypatch,
 ) -> None:

tests/providers/test_github_models.py

@@ -0,0 +1,329 @@
+"""Tests for GitHub Models OpenAI-compatible provider."""
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, patch
+
+import httpx
+import pytest
+
+from api.models.anthropic import Message, MessagesRequest
+from core.anthropic.stream_contracts import parse_sse_text
+from providers.base import ProviderConfig
+from providers.exceptions import ModelListResponseError
+from providers.github_models import GITHUB_MODELS_DEFAULT_BASE, GitHubModelsProvider
+from providers.github_models.client import GITHUB_MODELS_CATALOG_URL
+
+
+@pytest.fixture
+def github_models_config() -> ProviderConfig:
+    return ProviderConfig(
+        api_key="test-github-models-token",
+        base_url=GITHUB_MODELS_DEFAULT_BASE,
+        rate_limit=10,
+        rate_window=60,
+        enable_thinking=True,
+    )
+
+
+@pytest.fixture(autouse=True)
+def mock_rate_limiter():
+    @asynccontextmanager
+    async def _slot():
+        yield
+
+    with patch("providers.transports.openai_chat.transport.GlobalRateLimiter") as mock:
+        instance = mock.get_scoped_instance.return_value
+
+        async def _passthrough(fn, *args, **kwargs):
+            return await fn(*args, **kwargs)
+
+        instance.execute_with_retry = AsyncMock(side_effect=_passthrough)
+        instance.concurrency_slot.side_effect = _slot
+        yield instance
+
+
+@pytest.fixture
+def github_models_provider(
+    github_models_config: ProviderConfig,
+) -> GitHubModelsProvider:
+    return GitHubModelsProvider(github_models_config)
+
+
+def _request(model: str = "openai/gpt-4.1") -> MessagesRequest:
+    return MessagesRequest(
+        model=model,
+        max_tokens=100,
+        messages=[Message(role="user", content="hi")],
+    )
+
+
+def _chunk(delta: SimpleNamespace, *, finish_reason: str = "stop") -> SimpleNamespace:
+    return SimpleNamespace(
+        choices=[SimpleNamespace(delta=delta, finish_reason=finish_reason)],
+        usage=SimpleNamespace(completion_tokens=5, prompt_tokens=8),
+    )
+
+
+async def _stream(*chunks: SimpleNamespace) -> AsyncIterator[SimpleNamespace]:
+    for chunk in chunks:
+        yield chunk
+
+
+def _catalog_response(payload: object) -> httpx.Response:
+    return httpx.Response(
+        200,
+        json=payload,
+        request=httpx.Request("GET", GITHUB_MODELS_CATALOG_URL),
+    )
+
+
+def test_default_base_url_constant() -> None:
+    assert GITHUB_MODELS_DEFAULT_BASE == "https://models.github.ai/inference"
+
+
+def test_init_uses_default_base_url_api_key_and_github_headers(
+    github_models_config: ProviderConfig,
+) -> None:
+    with patch("providers.transports.openai_chat.transport.AsyncOpenAI") as mock_openai:
+        provider = GitHubModelsProvider(github_models_config)
+
+    assert provider._api_key == "test-github-models-token"
+    assert provider._base_url == GITHUB_MODELS_DEFAULT_BASE
+    assert provider._catalog_url == GITHUB_MODELS_CATALOG_URL
+    assert mock_openai.call_args.kwargs["base_url"] == GITHUB_MODELS_DEFAULT_BASE
+    assert mock_openai.call_args.kwargs["api_key"] == "test-github-models-token"
+    assert mock_openai.call_args.kwargs["default_headers"] == {
+        "Accept": "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2026-03-10",
+    }
+
+
+def test_init_strips_trailing_slash(github_models_config: ProviderConfig) -> None:
+    config = github_models_config.model_copy(
+        update={"base_url": f"{GITHUB_MODELS_DEFAULT_BASE}/"}
+    )
+
+    with patch("providers.transports.openai_chat.transport.AsyncOpenAI"):
+        provider = GitHubModelsProvider(config)
+
+    assert provider._base_url == GITHUB_MODELS_DEFAULT_BASE
+
+
+def test_model_list_headers_use_bearer_auth(
+    github_models_provider: GitHubModelsProvider,
+) -> None:
+    assert github_models_provider._model_list_headers() == {
+        "Accept": "application/vnd.github+json",
+        "Authorization": "Bearer test-github-models-token",
+        "X-GitHub-Api-Version": "2026-03-10",
+    }
+
+
+def test_build_request_body_uses_shared_openai_chat_policy(
+    github_models_provider: GitHubModelsProvider,
+) -> None:
+    request = _request()
+
+    body = github_models_provider._build_request_body(request, thinking_enabled=True)
+
+    assert body["model"] == "openai/gpt-4.1"
+    assert body["max_tokens"] == 100
+    assert "extra_body" not in body
+
+
+@pytest.mark.asyncio
+async def test_lists_stream_tool_capable_models_only(
+    github_models_provider: GitHubModelsProvider,
+) -> None:
+    with patch.object(
+        github_models_provider._model_list_client,
+        "get",
+        new_callable=AsyncMock,
+        return_value=_catalog_response(
+            [
+                {
+                    "id": "openai/gpt-4.1",
+                    "capabilities": ["streaming", "tool-calling"],
+                },
+                {
+                    "id": "openai/text-only",
+                    "capabilities": ["streaming"],
+                },
+                {
+                    "id": "openai/no-stream-tools",
+                    "capabilities": ["tool-calling"],
+                },
+            ]
+        ),
+    ) as mock_get:
+        assert await github_models_provider.list_model_ids() == frozenset(
+            {"openai/gpt-4.1"}
+        )
+
+    mock_get.assert_awaited_once_with(
+        GITHUB_MODELS_CATALOG_URL,
+        headers={
+            "Accept": "application/vnd.github+json",
+            "Authorization": "Bearer test-github-models-token",
+            "X-GitHub-Api-Version": "2026-03-10",
+        },
+    )
+
+
+@pytest.mark.asyncio
+async def test_model_list_rejects_malformed_payload(
+    github_models_provider: GitHubModelsProvider,
+) -> None:
+    with (
+        patch.object(
+            github_models_provider._model_list_client,
+            "get",
+            new_callable=AsyncMock,
+            return_value=_catalog_response({"data": []}),
+        ),
+        pytest.raises(ModelListResponseError, match="top-level array"),
+    ):
+        await github_models_provider.list_model_ids()
+
+
+@pytest.mark.asyncio
+async def test_model_list_returns_empty_set_when_no_models_support_streaming_tools(
+    github_models_provider: GitHubModelsProvider,
+) -> None:
+    with patch.object(
+        github_models_provider._model_list_client,
+        "get",
+        new_callable=AsyncMock,
+        return_value=_catalog_response(
+            [
+                {"id": "openai/text-only", "capabilities": ["streaming"]},
+                {"id": "openai/non-stream-tool", "capabilities": ["tool-calling"]},
+            ]
+        ),
+    ):
+        assert await github_models_provider.list_model_ids() == frozenset()
+
+
+@pytest.mark.asyncio
+async def test_stream_response_text(
+    github_models_provider: GitHubModelsProvider,
+) -> None:
+    delta = SimpleNamespace(
+        content="Hello from GitHub Models",
+        reasoning_content=None,
+        tool_calls=None,
+    )
+
+    with patch.object(
+        github_models_provider._client.chat.completions,
+        "create",
+        new_callable=AsyncMock,
+        return_value=_stream(_chunk(delta)),
+    ) as mock_create:
+        events = [
+            event async for event in github_models_provider.stream_response(_request())
+        ]
+
+    parsed = parse_sse_text("".join(events))
+    assert any(
+        event.event == "content_block_delta"
+        and event.data.get("delta", {}).get("text") == "Hello from GitHub Models"
+        for event in parsed
+    )
+    assert mock_create.call_args.kwargs["model"] == "openai/gpt-4.1"
+    assert mock_create.call_args.kwargs["stream"] is True
+
+
+@pytest.mark.asyncio
+async def test_stream_response_tool_call(
+    github_models_provider: GitHubModelsProvider,
+) -> None:
+    tool_call = SimpleNamespace(
+        index=0,
+        id="call_1",
+        function=SimpleNamespace(name="echo", arguments='{"value":"x"}'),
+    )
+    delta = SimpleNamespace(
+        content=None, reasoning_content=None, tool_calls=[tool_call]
+    )
+    request = MessagesRequest.model_validate(
+        {
+            "model": "openai/gpt-4.1",
+            "messages": [{"role": "user", "content": "Use the tool"}],
+            "tools": [
+                {
+                    "name": "echo",
+                    "description": "Echo a value",
+                    "input_schema": {
+                        "type": "object",
+                        "properties": {"value": {"type": "string"}},
+                        "required": ["value"],
+                    },
+                }
+            ],
+        }
+    )
+
+    with patch.object(
+        github_models_provider._client.chat.completions,
+        "create",
+        new_callable=AsyncMock,
+        return_value=_stream(_chunk(delta, finish_reason="tool_calls")),
+    ):
+        events = [
+            event async for event in github_models_provider.stream_response(request)
+        ]
+
+    parsed = parse_sse_text("".join(events))
+    assert any(
+        event.event == "content_block_start"
+        and event.data.get("content_block", {}).get("type") == "tool_use"
+        and event.data.get("content_block", {}).get("name") == "echo"
+        for event in parsed
+    )
+    assert any(
+        event.event == "content_block_delta"
+        and event.data.get("delta", {}).get("partial_json") == '{"value":"x"}'
+        for event in parsed
+    )
+
+
+@pytest.mark.asyncio
+async def test_stream_response_reasoning_content(
+    github_models_provider: GitHubModelsProvider,
+) -> None:
+    delta = SimpleNamespace(
+        content=None,
+        reasoning_content="Thinking via GitHub Models",
+        tool_calls=None,
+    )
+
+    with patch.object(
+        github_models_provider._client.chat.completions,
+        "create",
+        new_callable=AsyncMock,
+        return_value=_stream(_chunk(delta)),
+    ):
+        events = [
+            event async for event in github_models_provider.stream_response(_request())
+        ]
+
+    parsed = parse_sse_text("".join(events))
+    assert any(
+        event.event == "content_block_delta"
+        and event.data.get("delta", {}).get("thinking") == "Thinking via GitHub Models"
+        for event in parsed
+    )
+
+
+@pytest.mark.asyncio
+async def test_cleanup(github_models_provider: GitHubModelsProvider) -> None:
+    github_models_provider._client = AsyncMock()
+    github_models_provider._model_list_client = AsyncMock()
+
+    await github_models_provider.cleanup()
+
+    github_models_provider._client.close.assert_called_once()
+    github_models_provider._model_list_client.aclose.assert_called_once()

tests/providers/test_provider_runtime.py

@@ -7,6 +7,7 @@ import pytest
 from config.nim import NimSettings
 from config.provider_catalog import (
     COHERE_DEFAULT_BASE,
+    GITHUB_MODELS_DEFAULT_BASE,
     MINIMAX_DEFAULT_BASE,
     PROVIDER_CATALOG,
     ZAI_DEFAULT_BASE,
@@ -20,6 +21,7 @@ from providers.deepseek import DeepSeekProvider
 from providers.exceptions import UnknownProviderTypeError
 from providers.fireworks import FireworksProvider
 from providers.gemini import GeminiProvider
+from providers.github_models import GitHubModelsProvider
 from providers.groq import GroqProvider
 from providers.huggingface import HUGGINGFACE_DEFAULT_BASE, HuggingFaceProvider
 from providers.kimi import KimiProvider
@@ -54,6 +56,7 @@ def _make_settings(**overrides):
     mock.vercel_ai_gateway_api_key = "test_vercel_key"
     mock.huggingface_api_key = "test_huggingface_key"
     mock.cohere_api_key = "test_cohere_key"
+    mock.github_models_token = "test_github_models_token"
     mock.zai_api_key = "test_zai_key"
     mock.lm_studio_base_url = "http://localhost:1234/v1"
     mock.llamacpp_base_url = "http://localhost:8080/v1"
@@ -73,6 +76,7 @@ def _make_settings(**overrides):
     mock.vercel_ai_gateway_proxy = ""
     mock.huggingface_proxy = ""
     mock.cohere_proxy = ""
+    mock.github_models_proxy = ""
     mock.zai_proxy = ""
     mock.fireworks_proxy = ""
     mock.fireworks_api_key = "test_fireworks_key"
@@ -240,6 +244,16 @@ def test_cohere_descriptor_uses_openai_chat_compatibility_api() -> None:
     assert "thinking" in descriptor.capabilities
 
 
+def test_github_models_descriptor_uses_openai_chat_inference_api() -> None:
+    descriptor = PROVIDER_CATALOG["github_models"]
+
+    assert descriptor.transport_type == "openai_chat"
+    assert descriptor.default_base_url == GITHUB_MODELS_DEFAULT_BASE
+    assert descriptor.credential_env == "GITHUB_MODELS_TOKEN"
+    assert descriptor.proxy_attr == "github_models_proxy"
+    assert "thinking" in descriptor.capabilities
+
+
 def test_build_provider_config_vercel_uses_gateway_key_and_proxy() -> None:
     descriptor = PROVIDER_CATALOG["vercel"]
     settings = _make_settings(
@@ -279,6 +293,19 @@ def test_build_provider_config_cohere_uses_api_key_and_proxy() -> None:
     assert config.proxy == "http://proxy.test:8080"
 
 
+def test_build_provider_config_github_models_uses_token_and_proxy() -> None:
+    descriptor = PROVIDER_CATALOG["github_models"]
+    settings = _make_settings(
+        github_models_token="github-token",
+        github_models_proxy="http://proxy.test:8080",
+    )
+
+    config = build_provider_config(descriptor, settings)
+
+    assert config.api_key == "github-token"
+    assert config.proxy == "http://proxy.test:8080"
+
+
 def test_create_provider_uses_native_openrouter_by_default():
     with patch("httpx.AsyncClient"):
         provider = create_provider("open_router", _make_settings())
@@ -297,6 +324,7 @@ def test_create_provider_instantiates_each_builtin():
         vercel_ai_gateway_api_key="test_vercel_key",
         huggingface_api_key="test_huggingface_key",
         cohere_api_key="test_cohere_key",
+        github_models_token="test_github_models_token",
         kimi_api_key="test_kimi_key",
     )
     cases = {
@@ -317,6 +345,7 @@ def test_create_provider_instantiates_each_builtin():
         "vercel": VercelProvider,
         "huggingface": HuggingFaceProvider,
         "cohere": CohereProvider,
+        "github_models": GitHubModelsProvider,
         "zai": ZaiProvider,
         "gemini": GeminiProvider,
         "groq": GroqProvider,

uv.lock

@@ -561,7 +561,7 @@ wheels = [
 
 [[package]]
 name = "free-claude-code"
-version = "3.1.0"
+version = "3.2.0"
 source = { editable = "." }
 dependencies = [
     { name = "aiohttp" },