@guanghechen/kit-copilot

GitHub Copilot proxy server for Claude, Codex, and Gemini compatible endpoints.

Environment Model

kit-copilot follows a strict environment flow:

CLI entry passes process.env to @guanghechen/commander/node.
Commander merges user envs with preset envs into ctx.envs.
Runtime logic consumes ctx.envs only.

There is no runtime fallback from business logic to global process.env for critical keys such as:

KIT_COPILOT_GITHUB_TOKEN
COPILOT_CODEX_EXPERIMENTAL_HEADERS_ENABLED
COPILOT_CODEX_BETA_FEATURES_ALLOWLIST
COPILOT_OPENAI_BETA_ALLOWLIST

Preset File (`preset.json`)

Config root:

$XDG_CONFIG_HOME/kit/copilot when XDG_CONFIG_HOME is set
~/.config/kit/copilot otherwise

Default preset file:

<config-root>/preset.json

Commander loads preset data from preset.json (preset.file) and merges selected profile into ctx.envs. If <config-root>/preset.json does not exist, command runs without preset envs.

Example preset.json:

{
  "version": 1,
  "defaults": { "profile": "default" },
  "profiles": {
    "default": {
      "envFile": ".env.local"
    }
  }
}

Token Persistence

kit-copilot auth persists KIT_COPILOT_GITHUB_TOKEN to preset env storage.

Persist target: <config-root>/.env.local
GH_COPILOT_TOKEN is not persisted

Note: .env.local is not auto-loaded by commander unless preset.json profile points to it (for example via envFile).

Examples

kit-copilot auth
kit-copilot start --port=4141

With preset env file:

KIT_COPILOT_GITHUB_TOKEN=ghu_xxx
# Optional: allow forwarding high-risk Codex beta/experimental headers
COPILOT_CODEX_EXPERIMENTAL_HEADERS_ENABLED=true
COPILOT_CODEX_BETA_FEATURES_ALLOWLIST=feature_a
COPILOT_OPENAI_BETA_ALLOWLIST=responses_websockets=2026-02-06

Realtime Voice (Codex)

kit-copilot supports Codex Realtime voice input via WebSocket handoff events.

Supported WS paths:

/api/codex
/api/codex/realtime
/api/codex/v1/realtime

Path matching is exact by design:

Trailing slash variants like /api/codex/ and /api/codex/realtime/ are rejected.

STT runtime envs (required):

KIT_STT_AZURE_API_KEY
KIT_STT_AZURE_API_ENDPOINT

Audio buffering policy:

Flush is triggered by either idle debounce (600ms) or max segment duration (4000ms).
Per-connection pending input audio has a hard cap of 20MB; overflow emits error with input_audio_buffer_overflow and drops pending buffered audio.
input_audio_buffer.append.audio must be canonical RFC4648 base64 (decode+re-encode must exactly match input).

Example:

KIT_STT_AZURE_API_KEY=... \
KIT_STT_AZURE_API_ENDPOINT=https://<resource>.openai.azure.com \
OPENAI_BASE_URL=http://127.0.0.1:4141/api/codex \
codex