github-router CLAUDE.md

github-router

A reverse proxy that exposes GitHub Copilot as OpenAI and Anthropic compatible API endpoints.

Primary deployment target

The primary deployment target for this project is Windows 11. macOS and Linux are supported and tested, but Windows is the canonical user environment — every PR must pass the windows-latest CI job before merge. A Windows CI failure is treated as a merge blocker, not as flake. If Windows behavior diverges from POSIX, the Windows path is the authoritative one to fix; do not POSIX-skip a Windows failure to land a change.

The canonical end-user setup is Windows 11 + Claude Code (the CLI client) + a GitHub Copilot Enterprise license. The enterprise license is load-bearing for feature decisions: it unlocks catalog models gated restricted_to: ["enterprise"] and the 1M-context Opus variants — claude-opus-5 (the spawned-Claude-Code default, stand_in's Opus row, and opus_critic's model; the single base slug already advertises max_context_window_tokens: 1_000_000 — no -1m sibling needed). When choosing models or windows, assume the enterprise catalog is present (prefer the 1M variants), but always gate on the live catalog with a non-enterprise fallback so the proxy still works on lesser tiers.

Design docs

• docs/peer-mcp-design.md — current architecture and phased migration plan for the peer-model MCP integration (codex_critic gpt-5.6-sol, codex_reviewer gpt-5.3-codex, gemini_critic gemini-3.1-pro), plus the deployed-state section covering auto-invocation triggers, allowedEfforts, the latency-by-effort matrix, and the predictedTooLong cap. Read this before changing anything in src/routes/mcp/, src/lib/peer-mcp-personas.ts, or src/lib/codex-mcp-config.ts.
• docs/first-mate-design.md — shipped --agents first-mate design: deterministic controller, dual-token GitHub write auth, durable ledgers/decisions, cloud-agent service layer, the deny-by-default GH_ROUTER_FM_SCAFFOLD_REPOS write allowlist for scaffold_repo, and human-bound merge gate. Read before touching src/lib/first-mate/, src/lib/agent/, or the agents MCP gate.
• docs/research/peer-mcp-investigation.md — multi-stage adversarial-review log behind the design: GitHub-issue refs (#50289 etc.), peer-critic verdicts at each iteration, the 7-batch sweep that proved decomposition works, and the concurrency-cap investigation. Read this when you want to know why a particular Phase ordering or specific value (cap=8, retention=30min, partial-buffer cap=1MB) was chosen.
• docs/research/stage-c-perf-spikes.md — measured request-prologue and startup-path spikes. Read before proposing a /v1/messages prologue optimization or moving startup work off the pre-listen path: the current verdict is defer/reclassify pending shutdown body-size percentiles and a readiness-safe split.
• docs/research/shim-prompt-fidelity.md — measured A/B of Claude Code's verbatim system prompt against gpt-5.6-sol and gemini-3.1-pro-preview through the shim, with FILE_TOOL_GUIDANCE on vs off. Records which task shapes discriminate (appending to a file; the read/grep cases do not), that the steering block is what stops both models writing files through the shell, the residual gemini wc -l preference, and the gpt identity-capture artifact. Read before adding per-model prompt steering — the evidence says don't.
• docs/publishing.md — npm/Docker release flow (OIDC trusted publishing), upgrade procedure for a running proxy, and the UPSTREAM_FETCH_TIMEOUT_MS / UPSTREAM_INACTIVITY_TIMEOUT_MS tunables.
• docs/beta-headers.md — anthropic-beta allowlist (3 stealth vs 20 leverage prefixes), the EXPLICITLY_STRIPPED_BETA_PREFIXES deny-list, body-field strips (budget, output_config.schema, betas, eager_input_streaming), and the stealth-vs-leverage policy rationale.
• docs/gateway-error-contract.md — Claude Code's capability_rejected: <class> gateway contract: how the proxy tells the client WHY an upstream 400/413 happened so the client runs its own recovery instead of stranding. Covers the two classes emitted today (prompt_too_long, max_tokens_context_overflow), the verified dual matcher (IZ(e) = wording || token), why Copilot's "exceeds the context window" wording on a 400 used to classify as nothing and brick a long session, and the classes we still hand-roll. Read before changing forwardError / classifyOverflow in src/lib/error.ts.
• docs/claude-env-injection.md — the five experimental CLAUDE_CODE_* env vars github-router claude auto-enables (presence-based guard), per-feature opt-out, the catalog-derived CLAUDE_CODE_AUTO_COMPACT_WINDOW integer (all profiles), and how CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY is now CONDITIONALLY enabled (cache-seeded) while its network-fetch path stays closed.
• docs/anthropic-translation-shim.md — the /v1/messages translation shim that runs Claude Code's main loop on non-Claude Copilot models (gpt-5.5, gpt-5.3-codex via /responses; gemini-3.5-flash, gemini-3.1-pro-preview via /chat/completions): the classifier routing table + fail-closed Claude guard, the shared provider-neutral IR, the Responses vs Chat egress, the C1 buffer-tools-emit-atomically streaming model (and the parallel-tool-args-lost bug it fixes), the stream-ordering contract dependency + Phase 5 E2E backstop, the stop/parallel_tool_calls field forwarding, the inherent Copilot model gaps, and the Phase 3 gateway-cache-seed native-selection mechanism. Read before touching src/lib/anthropic-translate/, the /v1/messages branch in src/routes/messages/handler.ts, or the Phase 3 helpers in src/lib/server-setup.ts.
• docs/multimodal.md — how images reach a model (producers → MCP text|image result union → the tool-result follow-up message → the single outbound vision preflight), the measured token cost of getting it wrong (base64 is ~1.46 chars/token, so a 200 KB screenshot is ~187k tokens versus ~1.5k as a native image block), the image-level replacement policy for malformed or unsupported inputs, upstream-ceiling prune-and-learn retry behaviour, peer imagePaths and why it takes paths rather than base64, the per-result image byte budget, and the capability register + scheduled drift alert that catch the next advertised-but-unplumbed capability. Read this before touching src/lib/attachments.ts, src/lib/vision-preflight.ts, src/lib/peer-attachments.ts, or src/lib/catalog-capability-register.ts.
• docs/unsupported-features.md — Files API 404, ADVISOR Phase I server-side wiring, mcp_servers fail-fast 400, Bridge/CCR strip, and other Anthropic surfaces with no Copilot equivalent.
• docs/default-models.md — claude → claude-opus-5 (Anthropic dashed slug, NOT the Copilot dotted slug — /model UI registry mismatch), codex → gpt-5.6-sol, fallback chain led by gpt-5.5, the dual-signal [1m] detector (sibling-slug regex OR base-slug max_context_window_tokens), and the ANTHROPIC_SMALL_FAST_MODEL default. Fast profile (shipped in this change): a Luna-led -m fast launch profile distinct from budget mode, three Luna effort aliases, a replaced 4-row gateway picker (Sol/Luna/Gemini 3.7 Flash/Grok 4.6), Grok's conservative context accounting, and a Gemini 3.7 Flash Advisor that remains primary-lead-only across every fixed /model selection — see the "Fast launch profile" section of that doc. Context-window safety (all profiles): Claude Code's [1m] budgets against the advertised TOTAL window while Copilot enforces a smaller max_prompt_tokens (Luna 922K, Opus 5 936K), putting the client's own compaction threshold ABOVE the ceiling; every launch now injects a catalog-derived decimal-integer CLAUDE_CODE_AUTO_COMPACT_WINDOW, minimizing floor(prompt*0.85)+min(output,20_000)+13_000 across every reachable [1m] lead/tier/custom/gateway model (deriveAutoCompactWindowTokens in src/lib/grok-context.ts). /model cannot mutate it; Claude Code applies min(locallyRecognizedModelWindow, launchValue), and native subagents inherit the same env. It MUST be an integer — that env path is parseInt-based, so "1m" becomes 1, floors to 100,000, and compacts a 1M session every ~52K tokens.
• docs/auth-isolation.md — STRIPPED_PARENT_ENV_KEYS parent-env sanitize, CLAUDE_CONFIG_DIR snapshot mirror (ISOLATED / SHARED / MIRRORED policy), synthetic claudeAiOauth credential schema, synthetic .claude.json onboarding-skip injection (hasCompletedOnboarding / bypassPermissionsModeAccepted / synthetic oauthAccount — required so fresh-machine launches don't trigger Claude Code's first-launch OAuth wizard), keychain isolation, no-401 invariant, agent-teams fix, and trade-offs.
• docs/web-search.md — Copilot /mcp wire flow with X-MCP-Toolsets: web_search, GitHub PAT auth, model-agnostic out-of-band fulfilment, and the COPILOT_HOST_ALLOWLIST PAT-exfiltration safeguard.
• docs/pi-vendor-sync.md — vendor-sync protocol for src/vendor/pi/ (Pi agent runtime backing worker_explore / worker_implement): how to refresh from upstream, which files MUST stay in sync, which slices were deliberately omitted, and the MIT-attribution invariant.
• docs/browser-mcp-design.md — architecture for the --browse flag's browser_* tool suite (15 tools driving Chrome/Edge via a from-scratch MV3 extension + native-messaging bridge). Covers the install-detection / auto-install / install_required flow, the dual-layer navigation block, the stable extension ID derivation, per-OS NMH paths (registry on Windows, file on POSIX), Bun-vs-Node bridge-runtime gotcha, and the Playwright E2E harness gated on GH_ROUTER_RUN_BROWSER_E2E=1. Read this before touching src/lib/browser-mcp/, src/browser-bridge/, or src/browser-ext/.
• docs/semantic-search.md + docs/research/colbert-sidecar-design.md — ColBERT/PLAID semantic search (the default mode: "semantic" of the unified code MCP tool, via the router-managed colgrep sidecar; there is no standalone semantic_search tool). Covers the on-by-default provision + background-index, the availability-based colbertSearchEnabled() leaf (which semanticSearchEnabled() delegates to), the contract split (the runner stays no-lexical-fallback; the merged code tool's semantic mode DOES fall back to lexical and labels source), the git freshness verdict (the staleness correctness guard), the CLI-per-invocation lifecycle (PID ledger + tree-kill + boot sweep), and the SHA-pinned supply chain that closes colgrep's unverified ORT/model downloads. Read before touching src/lib/colbert/ or src/lib/unified-code-search.ts.
• docs/process-teardown.md — deterministic child-process teardown for the launched CLI: the canonical killChildProcessTree helper, the extension-conditioned Windows spawn (windowsLaunchNeedsShell — real .exe spawned direct, only .cmd/.bat keep cmd.exe), POSIX detached:true + SIGINT/SIGTERM forwarding, and the crash-safe net: on Windows the runtime's KILL_ON_JOB_CLOSE Job Object already reaps the tree (a startProcessGuard no-op there, asserted by a regression canary), on POSIX a detached start-time-verified node -e reaper in src/lib/process-guard/ (inherited-pipe-EOF parent-death signal, skip-when-uncertain). Documents which exit paths are deterministic vs best-effort. Read before touching cleanup() in src/lib/launch.ts or src/lib/process-guard/.
• docs/serve-control-plane.md — the github-router serve browser control plane: launches CloudCLI (@cloudcli-ai/cloudcli, AGPL) as a separate arm's-length process and reverse-proxies it under github-router's own origin with zero-login (localStorage['auth-token'] HTML injection). Covers the Option-B reverse-proxy architecture (src/lib/serve/), the security model (loopback bind, proxy-side Origin enforcement CloudCLI lacks, filtered child env stripping GITHUB_TOKEN/ANTHROPIC_AUTH_TOKEN/etc., JWT-on not VITE_IS_PLATFORM), the pinned router-owned install (never global/@latest), and the MIT-vs-AGPL mere-aggregation stance (NOTICE + scripts/check-pack-no-agpl.mjs release guard). Read before touching src/serve.ts or src/lib/serve/.