copilot-relay

Use Claude Code with the models available through your GitHub Copilot subscription.

Features

• Claude Code, familiar workflow — Messages API compatibility, streaming responses, and tool calls.
• WebSearch that fits the conversation — relay-managed search, followed by an answer that can still use your tools.
• Your models, your settings — configurable GPT/Opus routes and reasoning effort; existing selections survive upgrades.
• Use the advertised capacity — discovered context/output limits, without silently shortening your input.
• Use advertised chat models — catalog-driven endpoint selection, optional effort support, and clear opt-in per-model deep checks.
• Choose Claude's upstream protocol — claudeUpstreamApi: chat-completions stays the default; opt into auto or messages for native Claude transport.
• Diagnose offline — debug mode captures full observed bodies for copilot-relay replay; captures contain unredacted prompts and must never be shared wholesale.
• Run it your way — foreground CLI or background service on macOS, Windows, and Linux; set apiKey to require a client key before binding beyond loopback.

Quick start

You need Node.js 22+, Claude Code, and a GitHub account with Copilot access to the models you select.

npm install -g copilot-relay
copilot-relay auth
copilot-relay start

Follow the device-login prompt. Keep the relay running in this terminal; by default, startup configures Claude Code's connection in ~/.claude/settings.json. Open a second terminal and run:

claude

Configuration lives in ~/.copilot-relay/config.yaml. Model access depends on your account and organization policy; if startup rejects a model, choose an available one using the configuration guide. Behind a proxy, set upstreamProxy in config.yaml to its URL, or env, before copilot-relay auth.

Discover models, find the config value for one, and optionally test it:

copilot-relay models
copilot-relay models sol fast    # prints the exact gptModel or opusModel line
copilot-relay models --deep --model claude-opus-5.5

Deep checks consume Copilot usage and test an isolated relay pipeline, not the running daemon. Add --details for safe failure evidence and private replay hints. Use copilot-relay status --deep for daemon health, and copilot-relay stop when finished.

Check how well prompt caching works per model and upstream route. The report reads only local logs and shows a hit rate below the goal, 95% by default, in red:

copilot-relay cache                  # last 24 hours
copilot-relay cache --hourly         # or --daily; narrow with --since 6h or --model opus
copilot-relay cache --json

Check your Copilot plan and quota with copilot-relay usage; add --json for scripts. It asks GitHub with the stored token, so no relay needs to run.

Go further

Open the Wiki · English / 中文

• Configure models and deep checks · 中文
• Run at login: macOS · Windows · Linux
• Commands · Prompt caching · Troubleshoot · Understand the architecture · Contribute

Unofficial research project; not affiliated with GitHub or Anthropic. Upstream services and compatibility can change. Model and tool support are not guaranteed; see the Wiki for known limitations. MIT licensed.