github-router: Instructions file for Claude Code

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.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-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 the profile-specific modelPicker settings injected into the per-launch mirror after Claude Code 2.1.260 made gateway-cache seeding non-authoritative.
• 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 modelPicker native-selection mechanism. Read before touching src/lib/anthropic-translate/, the /v1/messages branch in src/routes/messages/handler.ts, or src/lib/model-picker-settings.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.5 (Anthropic dashed slug, NOT the Copilot dotted slug — /model UI registry mismatch), codex → gpt-5.6-sol, fallback chain led by gpt-6-sol, the dual-signal [1m] detector (sibling-slug regex OR base-slug max_context_window_tokens), and the ANTHROPIC_SMALL_FAST_MODEL default. Fast profile: a Gemini 3.8 Flash-led -m fast launch profile distinct from budget mode, Sonnet 5 1M xhigh reviewer, four-row curated picker (Sol/Luna/Gemini 3.8 Flash/Grok 4.6), Grok's conservative context accounting, and a GPT-6 Sol 1M high Advisor that remains primary-lead-only across every fixed /model selection — see the "Fast launch profile" section of that doc. Cheapest/balanced families: -m cheapest2 derives from -m cheapest (Luna/max lead, Luna Explore/GP/reviewer, Oracle-only peers, 200K, three natives) with only gpt-6.1-sol as Advisor/Oracle and the Advisor raised to high; -m balanced2 derives from -m balanced (Luna Explore/GP, 200K, advisor-free, reviewer→Explore) with gpt-6.1-sol for lead/reviewer and the Oracle moved to grok-4.7 at medium. Both are contract spreads in src/lib/{cheapest2,balanced2}-profile-contract.ts consumed through src/lib/profile-family.ts, so a cheapest/balanced check written with the family helpers covers its -2 sibling by construction. Max profile: a Sol-led -m max profile with Opus 5 1M high brainstorm, Sonnet 5 1M xhigh repository-aware reviewer, and cold-start cross-family peers (gemini-reviewer, codex-reviewer / sonnet-reviewer fallback, grok-reviewer). Its prompt architecture keeps decision policy in the system digest, one compact native roster in the resident awareness summary, the gate-aware inventory in mirrored CLAUDE.md, routing boundaries in Agent/MCP descriptions, and execution contracts in role prompts. Independent non-overlapping work may batch; dependencies and conflicting side effects stay sequential. The coordinator chooses the smallest sufficient set of distinct peer lenses and never substitutes votes for verification. 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/settings-picker 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. Pinned-200K profiles (cheap, cheapest/cheapest2, balanced/balanced2) instead seed CLAUDE_CODE_DISABLE_1M_CONTEXT=1 — bare ids alone don't hold 200K because every behavesAs target is native-1M in the client catalog (verified: bare gpt-6-luna reports contextWindow: 1000000 on Claude Code 2.1.288) — carry no decorated picker rows, and therefore omit the bound.
• 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/azure-mcp.md — the two Azure MCP groups. ado: the public remote server at https://mcp.dev.azure.com/{organization} (audience 2a72489c-aab2-4b65-b93a-a91edccf33b8), read-only by default via X-MCP-Readonly: true (measured: 20 tools read-only vs 31 without, 26 vs 43 across all toolsets — the header IS the filter), the curated repos,wit,pipelines,wiki toolset default, and the dynamic tool listing that forwards upstream tools/list instead of freezing entries upstream can rename (name-uniqueness still checked at snapshot time; boot assertion sees the static registry only). kusto: an in-repo client over POST {cluster}/v1/rest/{query,mgmt} (body field is csl, not query), five read-only tools whose cluster is named per call (--kusto alone registers the group; --kusto-cluster is only a default for calls that omit one, and a call-named cluster is held to a Kusto-shaped https origin with no allowlist, the data boundary being the identity's own RBAC), and read-only enforced by the service (x-ms-readonly: true + properties.Options.request_readonly_hardline: true, neither liftable by a set statement) rather than by inspecting KQL text. Also the auto-enable rule (an Azure DevOps git remote turns Bluebird + ado + kusto on, the last since the cluster became a per-call argument; discovery turns the group on but never supplies a cluster), its four trust bounds, the shared az account get-access-token plumbing, and the testing policy. Read this before touching src/lib/ado-client.ts, src/lib/ado-tools.ts, src/lib/kusto-client.ts, src/lib/kusto-tools.ts, or src/lib/azure-mcp-flags.ts.
• 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 opt-in (--search) provision + background-index, the opt-in + 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 + serve-while-stale labels (freshness/stale_files on small content deltas; engine/suspect stale still refuses), 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/.