ghc-tunnel

GitHub Copilot API Proxy — exposes standard OpenAI and Anthropic compatible endpoints so tools can use GitHub Copilot models.

This TypeScript implementation references the Python project at https://github.com/sxwxs/ghc-api, adding more convenient functions and easier configuration for code agents such as Claude Code and Coded.

Quick Start

# Run directly (Node.js 18+ required)
npx ghc-tunnel

# Or install globally
npm install -g ghc-tunnel
ghc-tunnel

# Interactive setup (configures models and local settings)
ghc-tunnel --setup

# Update Claude Code settings only
ghc-tunnel --setup --claudecode

On first run the proxy initiates GitHub Device Flow authentication if no GITHUB_TOKEN is set.

Features

• OpenAI-compatible /v1/chat/completions and /v1/responses endpoints (with Codex adapters: apply_patch tool, X-Initiator, context compaction)
• Anthropic-compatible /v1/messages endpoint (direct or translated)
• Codex config auto-repair — fills missing keys in ~/.codex/config.toml on startup
• Automatic model name translation via configurable mappings
• Streaming support (SSE) for all endpoints
• Disk-backed request history with paged metadata and on-demand body viewing
• Retry with backoff for upstream connection errors
• Content filtering (system prompt manipulation, tool result cleaning)
• Token management with automatic refresh

CLI Options

ghc-tunnel [options]

  -s, --setup             Interactive setup wizard (configure models and local settings)
      --claudecode        Update Claude Code settings only (use with --setup)
  -d, --default           Use defaults for setup and Codex config prompts
  -p, --port <port>       Port to listen on (default: 8314)
  -a, --address <addr>    Address to listen on (default: 127.0.0.1)
  -c, --config            Generate default config file
  -v, --version           Show version
  -h, --help              Show help

Configuration

Config file: ~/.ghc-tunnel/config.yaml (generated on first run or with --config).

See docs/configuration.md for full reference.

Token Usage Logging

Every 5 minutes, ghc-tunnel writes token usage delta (if non-zero) to:

• ~/.ghc-tunnel/token_usage.jl

Also flushes pending usage on shutdown (Ctrl+C/termination/normal exit).

Each JSONL line includes:

• timestamp (unix seconds)
• models list with:
  • model
  • request_count
  • input_tokens
  • output_tokens
  • total_tokens

Request History Storage

ghc-tunnel always stores completed request metadata and request/response bodies under ~/.ghc-tunnel/requests/. The dashboard reads metadata in pages and loads a body only when a request is opened, so history does not remain resident in the Node.js heap.

• The newest 10,000 completed requests are retained across restarts.
• Each request or response body is capped at 50 MB and marked when truncated.
• Streaming responses are written to disk incrementally while being forwarded.
• The dashboard initially loads a 64 KB body preview; full stored content is fetched only when requested.
• Bodies are formatted as JSON in the dashboard; streaming responses show raw events and reconstructed response content separately.

There is no total disk-size cap. Remove ~/.ghc-tunnel/requests/ while the service is stopped if you want to clear all stored history.

API Endpoints

| Endpoint | Description | |----------|-------------| | POST /v1/chat/completions | OpenAI chat completions | | POST /v1/responses | OpenAI responses API | | GET /v1/models | List available models | | POST /v1/messages | Anthropic messages API | | GET / | Web dashboard | | GET /requests | Request browser |

Example Usage

OpenAI SDK

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:8314/v1",
    api_key="not-needed"
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}]
)

Anthropic SDK

import anthropic

client = anthropic.Anthropic(
    base_url="http://127.0.0.1:8314",
    api_key="not-needed"
)

message = client.messages.create(
    model="claude-sonnet-4",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}]
)

cURL

curl http://127.0.0.1:8314/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello!"}]}'

Documentation

• Architecture — system design and data flow
• API Reference — all HTTP endpoints
• Configuration — config file, env vars, CLI options

License

MIT