CC Model Router

Lightweight CLI and Web UI for managing model providers, syncing Agent configs, and launching Agent tools with local secret injection.

This MVP focuses on reliable local configuration management:

• Provider add/list/remove/use/status
• API keys stored outside YAML through the system keyring
• Agent config sync with dry-run diffs
• Automatic backups and restore
• Manifest-first Agent platform registry
• Built-in platforms: Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw, Hermes
• Route decision debugging with cc-router route
• Phase 2 OpenAI-compatible non-streaming proxy
• Phase 3 retryable fallback and proxy cost tracking
• Streaming proxy passthrough for OpenAI-compatible SSE responses
• Monthly budget alert status
• Safe hook shims under ~/.cc-model-router/shims
• Responsive local Web UI for provider setup, status, sync dry-runs, and one-click launch
• English and Chinese Web UI language toggle
• Legacy model gateway commands preserved under cc-router legacy

Install

python -m venv .venv
.venv/bin/python -m pip install -e ".[dev]"

Quick Start

cc-router init

cc-router provider add openai \
  --type openai \
  --api-key "$OPENAI_API_KEY" \
  --base-url https://api.openai.com/v1 \
  --models gpt-4o,gpt-4o-mini \
  --default-model gpt-4o-mini

cc-router provider list
cc-router agent list
cc-router sync codex --provider openai --dry-run
cc-router sync codex --provider openai --yes
cc-router status

# Explain route decisions
cc-router route "quick answer" --strategy cost-first --format json

# Start the local OpenAI-compatible proxy
cc-router proxy start --port 3456

# View proxy token/cost summaries
cc-router cost today
cc-router cost provider --period week
cc-router cost budget

# Install safe shims without editing your shell files.
# This covers launch-capable Agent platforms from the manifest registry.
cc-router hook install
cc-router hook status
cc-router hook uninstall

# Start the local Web UI
cc-router ui start

Provider rules:

• Cloud providers normally require an API key.
• Disabled cloud providers can be pre-configured without a key.
• Disabled providers cannot be selected as the default provider.
• If the current default provider is later disabled, cc-router clears the default selection.

Web UI

The local Web UI is available at http://127.0.0.1:3457 by default:

cc-router ui start

It supports English and Chinese. The language switch is in the dashboard header, and the selected language is saved in browser local storage.

The Web UI covers the normal zero-setup flow:

1. Save a provider API key.
2. Sync an Agent config, such as OpenCode.
3. Install launchers.
4. Launch the Agent from the page.

Notes

Provider YAML stores only key references, not plaintext API keys. Some Agent tools can read keys only from environment variables. OpenCode's openai provider expects OPENAI_API_KEY; other OpenCode providers generated by cc-router use names such as CC_ROUTER_OPENROUTER_API_KEY.

The default provider is the one used by sync, hook, and launch flows when you do not pass --provider explicitly. Only enabled providers can be used as the default.

Agent platform support is manifest-first. Built-in manifests live in cc_model_router/agent_manifests, and user manifests can be installed under ~/.cc-model-router/agents:

cc-router agent list
cc-router agent status opencode
cc-router agent validate-manifest ./my-agent.yaml
cc-router agent install-manifest ./my-agent.yaml

The Phase 2 proxy supports non-streaming OpenAI-compatible /v1/chat/completions. Phase 3 adds fallback for 429/5xx/timeouts and records proxy usage in SQLite. Streaming proxy passthrough is supported; streamed usage is recorded as estimated because OpenAI-compatible SSE chunks usually do not include final token usage.

Hook mode creates shims only. It does not edit shell startup files automatically. Add the printed export PATH=... line yourself when you want to activate it. Once active, the shims launch supported Agent platforms through cc-router so the default provider's saved API key can be injected into the child process environment without printing it. For OpenCode with provider id openai, the shim injects OPENAI_API_KEY.

Team templates are shareable configuration bundles without secrets. They should contain provider IDs, base URLs, model lists, routes, fallback chains, and pricing defaults, while each developer supplies their own API keys locally.

License

MIT