View app screens

What This Is

Claude Code Provider Gateway, or CCPG, is a desktop app that starts a local gateway on your machine. Claude Code talks to the Anthropic-compatible proxy surface, while external tools can use the OpenAI-compatible /v1 surface. The gateway routes each request to the provider and model you configured, translates protocols when needed, and streams the result back in the caller's expected format.

Claude Code -> CCPG desktop app -> local proxy -> your selected LLM provider

You keep Claude Code's agent loop, tool use, project context, custom commands, hooks, MCP servers, and IDE workflow. You choose the model backend.

CCPG is not an npm package for end users. It has two official runtime modes: the Tauri desktop app for a native local experience, and a Docker/Web mode for users who want to run the same daemon and panel in a browser without installing a desktop app.

Why It Exists

Claude Code is one of the best AI coding tools available, but the default experience keeps you tied to one provider, one model catalog, and one pricing model.

CCPG gives you the missing control layer:

• Use cheaper models for routine edits.
• Use stronger reasoning models when the task deserves it.
• Run local models for sensitive code.
• Use Copilot or OpenAI Account auth from a desktop UI.
• See what Claude Code is actually sending in the background.

Everything runs locally. There is no hosted CCPG service, no telemetry, no account system, and no gateway markup. The app is MIT licensed, open source, and designed to run locally.

TL;DR

1. Download the desktop installer for your OS, or run the Docker/Web mode.
2. Open CCPG. The daemon starts automatically.
3. Add one built-in or custom provider in Providers and click Test.
4. Install the ccpg shell command from Dashboard -> Terminal Integration.
5. Launch Claude Code:

ccpg --<provider>

[!WARNING] If your .claude/settings.json or .claude/settings.local.json has an env block with ANTHROPIC_AUTH_TOKEN or ANTHROPIC_BASE_URL, remove those entries before launching via ccpg. Those env vars override the gateway endpoint and prevent CCPG from routing requests correctly.

After that, switch providers per session:

ccpg --OpenRouter
ccpg --OpenAIAccount
ccpg --Copilot
ccpg --Ollama
ccpg --all
ccpg --ModelChain
ccpg --my-chain

Docker/Web Quick Start

To run CCPG in a browser with Docker Compose:

docker compose up -d --build

Then open:

• Panel UI: http://localhost:6767
• Anthropic/OpenAI-compatible gateway: http://localhost:49250/v1

Docker/Web state is persisted in the ccpg_data volume. For port mapping, environment variables, Terminal Integration, reverse proxy setup, backups, and Docker troubleshooting, see the Docker/Web Guide.

Status

CCPG is an early release, feedback is welcome, and it is already usable for testing.

v0.1 is available now with desktop installers for macOS, Linux, and Windows. Expect rough edges, but the core flow is ready:

install app → add provider → test connection → run Claude Code through CCPG.

The primary packaged path is the desktop app: users should not need Node.js, npm, Rust, Bun, or hand-edited terminal config. Docker/Web is also supported for users who prefer a containerized browser UI.

The official documentation is at ccpg.live/docs. The repo also keeps the full Markdown docs in docs/ if you prefer reading them here:

• Getting Started
• Docker/Web Guide
• Providers
• Configuration
• Architecture
• API Reference
• Development
• Troubleshooting

Features

• Desktop app, not a terminal science project - Tauri app for macOS, Windows, and Linux with provider setup, connection tests, routing, logs, and history in one UI.
• Built-in and custom provider cards - OAuth, API key, cloud, local, and coming-soon providers out of the box, plus user-created OpenAI-compatible and Anthropic-compatible providers with custom slugs and logos.
• Anthropic-compatible local proxy - Claude Code sends Anthropic Messages API requests to 127.0.0.1; CCPG translates and routes them.
• OpenAI-compatible local gateway - Tools such as Cursor, Codex, OpenAI SDK clients, and other OpenAI-compatible apps can point at http://127.0.0.1:49250/v1 and use /v1/models plus /v1/chat/completions with the same enabled providers.
• Full streaming - provider responses stream back as Anthropic-style SSE events, with upstream cancellation when the client disconnects.
• Model routing - map Claude tiers like opus, sonnet, and haiku to different providers and models.
• All-providers mode - aggregate enabled providers into one model catalog and choose by model in Claude Code.
• Model Chains - create custom fallback chains from active provider models. A chain tries models in priority order, retries transient failures, and moves to the next model when an upstream provider fails, rate limits, idles before emitting useful content, or returns an empty/malformed stream.
• Built-in OAuth - OpenAI Account uses PKCE OAuth. GitHub Copilot and Kilo Code use Device Flow. Cline uses browser authorization. Tokens refresh automatically where supported.
• Provider management UI - search providers, filter active/inactive cards, add custom OpenAI/Anthropic-compatible providers, favorite and reorder frequently used providers, edit runtime limits/manual model lists, and hide noisy discovered models.
• Model Chain timeout controls - tune request, first-token, and total stream limits per chain from Advanced Settings. Defaults are 30s to first useful token and 60s total stream.
• Token savers - Optional RTK-style tool-result compression and Caveman terse-response mode from Settings.
• Outbound proxy support - Configure an HTTP/HTTPS proxy in Settings so the daemon routes external requests (OAuth, provider API calls) through your network proxy. Required for users in regions where providers restrict direct access.
• Local model support - Ollama, LM Studio, and llama.cpp run through the same Claude Code flow.
• Request history - see model, provider, human-readable prompt, sanitized provider request preview, response preview, warnings, input tokens, latency, errors, and session totals.
• Parallel terminal sessions - launch multiple ccpg --<provider> terminals at once; each session keeps its own provider/model mode, primary model memory, heartbeat, and live request log.
• Provider safeguards - per-provider concurrency/rate limits are enforced by the daemon before dispatch, and canceled Claude Code requests abort in-flight upstream calls.
• Encrypted secrets - API keys, OAuth tokens, and gateway auth token are split out of config and stored with AES-256-GCM.
• No telemetry - no cloud service, no database server, no analytics, no account.

The Hidden Prompt Viewer

Ever wonder what Claude Code is actually sending to the API?

CCPG logs each request Claude Code sends through the gateway, including background calls that do not appear as normal chat messages. In the History UI you can inspect:

• the requested model and routed provider model
• the human-readable serialized prompt, including the first request's system prompt
• the sanitized provider request preview after routing, token savers, and provider conversion
• tool-use traffic that appears in the message stream
• input token count
• latency to first byte
• provider errors
• conversion warnings for provider-specific feature drops/translations
• captured response text preview

This is useful for debugging cost, understanding why a model behaved a certain way, and seeing background housekeeping calls that otherwise feel invisible.

Token Savers

CCPG includes two optional local token-saving features in Settings -> Token Savers:

RTK does not change normal chat messages or errored tool results. If a request has no large tool output, there may be nothing to compress. When RTK does compress something, the daemon log records a line with bytes saved and the filter used.

Caveman is different: it does not reduce input tokens. It asks the model to answer more tersely, with levels lite, full, and ultra.

How ccpg --all Works

ccpg --all is not round-robin and it does not randomly pick a provider.

When you launch with --all, CCPG enables model discovery across every provider you turned on in the app. Claude Code's model picker sees gateway-prefixed model IDs such as:

anthropic/openrouter/anthropic/claude-sonnet-4.5
anthropic/deepseek/deepseek-chat
anthropic/ollama/qwen2.5-coder

When Claude Code sends a request for one of those models, CCPG reads the provider prefix and routes the request to that provider and model. If Claude Code later sends background requests using hardcoded Claude tier names, CCPG remembers the primary provider-prefixed model selected in the session and routes those background calls there too.

Use --all when you want to choose models from multiple providers inside one Claude Code session. Use ccpg --DeepSeek, ccpg --OpenRouter, or another single-provider flag when you want a simpler model list.

How Model Chains Work

Model Chains let you create user-defined gateway models from the panel. Open Model Chains, create a chain with a name and chain-slug, then add models from active providers and enabled model lists. The order in the chain is the runtime priority.

Claude Code sees each chain as a single custom model:

{Chain Name} · Gateway:custom-model (Defined by user)

Internally, the daemon exposes the model as anthropic/chain/<slug>. When a request hits that chain, CCPG calls the first target model. If the provider returns an API error, rate limit, credit/quota failure, network failure, or a 200 response whose stream ends, idles, errors, or parses without useful Anthropic content before any answer content is emitted, CCPG retries that target and then moves to the next target in the chain. Once useful content has been emitted, CCPG keeps the stream attached to that provider and does not rewind partial answers. If the upstream stream fails after content has started, CCPG closes open content blocks and emits a terminal Anthropic-compatible error frame before stopping the message. The session stays attached to the chain, so Claude Code background tier calls continue through the same chain instead of leaking back to the first provider.

The Model Chain page also includes an Economy/Local preset. It builds a Haiku -> DeepSeek -> Ollama-style waterfall from the providers and models you already have enabled/configured, skipping unavailable entries instead of requiring Anthropic-native Claude.

Each chain has optional Advanced Settings for fallback timing. Request timeout controls how long CCPG waits for response headers, first-token timeout controls how long a target may stall before useful Anthropic content, and total stream timeout caps one chain attempt. Empty fields use the defaults: 60s request, 30s first token, and 60s total stream.

Launch modes:

Use a single chain-slug when you want one controlled fallback path. Use --ModelChain when you want Claude Code's model picker to show every enabled chain.

Supported Providers

OAuth

API Key Cloud

Local

Anthropic Passthrough

CCPG can also pass native Claude requests through to Anthropic when credentials are available. This is useful when you want Claude models and non-Anthropic models in the same gateway workflow.

See docs/PROVIDERS.md for the complete provider ID list, CLI flags, auth behavior, and contributor notes.

System Requirements

For Users

You also need Claude Code installed and able to run from your shell as claude.

For Source Development

Source development needs Node.js, npm workspaces, Bun, Rust, and Tauri system dependencies. See docs/DEVELOPMENT.md.

Install

Download the latest desktop build from:

ccpg.live/download — or directly from GitHub Releases

Then:

1. Open the app.
2. Add or log into at least one provider.
3. Test the provider connection.
4. Install the ccpg shell command from Dashboard -> Terminal Integration.
5. Relaunch your shell.
6. Start Claude Code through CCPG.

ccpg --DeepSeek # Or other configured provider

[!WARNING] If your .claude/settings.json or .claude/settings.local.json has an env block containing ANTHROPIC_AUTH_TOKEN or ANTHROPIC_BASE_URL, remove those entries. They override the gateway endpoint and prevent CCPG from intercepting Claude Code's requests.

Any arguments after the provider flag are passed to Claude Code:

ccpg --DeepSeek --resume <session-id>
ccpg --OpenRouter --dangerously-skip-permissions
ccpg --Ollama --continue

Provider Flags

Flags are case-insensitive in the Terminal Integration flow.

Pricing

CCPG is free, open source, and runs locally.

There is no hosted CCPG bill. You only pay whatever your selected upstream provider charges, or nothing when you use a local provider. CCPG does not add a per-request fee and does not proxy traffic through a hosted CCPG server.

Comparison

This table is about product focus, not a claim that other projects are bad. Terminal-first routers are great for technical users. CCPG is trying to make provider switching feel like a desktop product.

How It Works

┌────────────────┐     ┌───────────────────────────────────┐     ┌─────────────────┐
│  Claude Code   │     │   Claude Code Provider Gateway    │     │  OpenRouter     │
│                │────▶│  ┌─────────────────────────────┐  │────▶│  DeepSeek       │
│                │◀────│  │ Proxy :49250                │  │◀────│  OpenAI Account │
│  Anthropic     │ SSE │  │ /v1/messages -> translate   │  │     │  Copilot        │
│  Messages API  │     │  │ /v1/chat/completions         │  │     │  Ollama         │
│  or OpenAI API │     │  │ /v1/models   -> aggregate   │  │     │                 │
└────────────────┘     │  └─────────────────────────────┘  │     │  ...            │
                       │  ┌─────────────────────────────┐  │     └─────────────────┘
                       │  │ Desktop Management UI       │  │
                       │  │ Providers · Routing          │  │
                       │  │ Model Chain · OpenAI Gateway │  │
                       │  │ History · Logs · Terminal Int. │  │
                       │  └─────────────────────────────┘  │
                       └───────────────────────────────────┘

Every request goes through the same basic flow:

1. Claude Code sends POST /v1/messages to CCPG's local proxy.
2. CCPG authenticates the local request with its generated gateway token.
3. CCPG resolves the target provider and model from the selected launch mode, model prefix, or routing rules.
4. CCPG applies enabled token savers to the request.
5. CCPG converts Anthropic Messages to the provider's native format when needed.
6. CCPG streams the response back as Anthropic-compatible SSE.
7. CCPG records session metadata and request details locally.

Runtime Storage

Runtime files live in:

• Linux/macOS: ~/.config/claude-code-provider-gateway/
• Windows: %APPDATA%/claude-code-provider-gateway/

Documentation

The full documentation is available at ccpg.live/docs. The Markdown sources are also kept in this repo under docs/ as a local alternative.

License

MIT © Daniel Luiz Alves 🇧🇷