@guanghechen/kit-copilot

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

Environment Model

kit-copilot follows a strict environment flow:

1. CLI entry passes process.env to @guanghechen/commander/node.
2. Commander merges user envs with preset envs into ctx.envs.
3. 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 resolution: variant.envFile > profile.envFile > <config-root>/.env.local
• Persist target path is resolved from commander public preset metadata (meta.file/profile/variant) and preset profile envFile
• GH_COPILOT_TOKEN is not persisted

Note: persist target is selected from the active preset profile/variant; default fallback is <config-root>/.env.local when no envFile is configured or path resolution fails.

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