🛡️ CCProxy Agent

The local guardrail that stops Claude Code from blowing past its context window.

A transparent safety proxy that sits between Claude Code / Claude Desktop and CC Switch — protecting tool protocol, managing token budgets, retrying context-limit errors once, and routing multimodal inputs.

🚀 Quick Start · ✨ Features · ⚙️ How It Works · 🔧 Configuration · 🤝 Contributing · 🇨🇳 中文说明

---

⚠️ This is an independent community project and is not affiliated with ccswitch, Anthropic, or Claude Code.

📸 Dashboard Preview

CCProxy Agent ships with a local web console for checking proxy status, editing guardrail settings, and watching live routing logs.

💡 Why This Exists

Ever seen this error mid-coding session?

This model's maximum context length is 200000 tokens.
However, you requested 64000 output tokens and your prompt contains at least 136001 input tokens.

That's a hard stop — your session dies, work is lost, and you restart. CCProxy Agent fixes this automatically by:

• 📉 Lowering max_tokens before the request even leaves your machine
• 🔁 Parsing the upstream 400 and retrying once with a safe budget
• 🧮 The math is dead simple: 200000 − 8000 safety − 136001 input = 55999 max_tokens

It's not a replacement for ccswitch — it's the crumple zone above it.

🏗️ Topology

                 ┌─────────────────┐     ┌──────────────┐     ┌────────────────┐
  Claude CLI ──▶ │  CCProxy Agent  │ ──▶ │   ccswitch   │ ──▶ │  model provider │
  Claude Desktop │  :15722 (guard) │     │  :15721      │     │  (GLM, Qwen...) │
                 └─────────────────┘     └──────────────┘     └────────────────┘
                  token budgeting ·       local switch         upstream LLM
                  retry · vision ·
                  compact reminder

The proxy intercepts /v1/messages and /v1/chat/completions, applies guardrails, then forwards to ccswitch. On startup it temporarily re-points Claude CLI / Claude Desktop configs at itself and restores them cleanly on shutdown.

✨ Features

	Feature	What it does
🧠	Auto token budgeting	Reduces max_tokens before forwarding so input + output never exceeds the context limit
🔁	One-shot retry	Parses upstream context-limit 400 errors and retries with a safer output budget
🧰	Agent protocol rescue	Clears old tool results and preserves bounded head/tail evidence from the newest result without breaking tool IDs
🪧	Compact reminder	Appends a /compact hint to responses when the session nears the threshold
🖼️	Vision summarization	Routes Claude Desktop images through vision models, injects [VISION SUMMARY] for text-only downstreams like GLM-5.2
🧩	Fallback chunking	Splits requests that remain too large after budgeting
🔌	Claude CLI patching	Temporarily redirects Claude CLI settings → proxy, restores on exit
🖥️	Claude Desktop 3P patching	Rewrites Desktop gateway config under %LOCALAPPDATA%/Claude-3p/configLibrary
🔌	Port fallback	Auto-jumps to the next free port (15722 → 15723 → …) if busy
🔍	Upstream auto-discovery	Finds a reachable local ccswitch when the configured upstream is down
📊	Built-in dashboard	Optional status, routing, process info & live logs at the active proxy URL
🪵	Local Chinese logs	Human-readable Token预算评估 / 已自动降低max_tokens style messages
📦	Windows + macOS packaging	Ship a portable Windows EXE plus macOS DMG/ZIP builds

🚀 Quick Start

Windows portable app

1. Download CCProxy-Agent-v0.4.97.exe from the latest GitHub Release.
2. Run the EXE. On first startup it creates a secret-free config.json beside the executable.
3. Configure CC Switch and optional Vision settings in the desktop UI.

The release also includes config.example.json and SHA256SUMS.txt. Private config.json files are never included in release artifacts.

macOS app

1. Download the arm64 build for Apple Silicon or x64 for Intel Macs from the latest release.
2. Open the DMG and move CCProxy Agent to Applications, or extract the ZIP.
3. This first macOS build is unsigned. If Gatekeeper blocks it, Control-click the app and choose Open. Configuration is stored under the app's macOS user-data directory, never inside the read-only app bundle.

From source

git clone https://github.com/geekchongv/ccswitch-context-guard.git
cd ccswitch-context-guard
npm install
npm run dev

The first source startup also creates config.json when it is missing. The proxy starts on http://127.0.0.1:15722 and the local dashboard remains available at that URL.

Health check:

curl http://127.0.0.1:15722/health

💡 If you open the optional dashboard manually, its Stop button closes cleanly and restores patched Claude settings before exit.

⚙️ How It Works

Token budgeting (before the request leaves)

   safe budget = hardLimit − safetyMargin
   max_tokens  = safe budget − estimated_input_tokens

   e.g.  200000 − 8000 − 136001  =  55999   ✅ never overflows

Context-limit retry (after a 400)

   upstream ──400──▶ parse "200000 ... 136001 input ... 64000 output"
                   ──▶ recompute max_tokens
                   ──▶ retry once ──▶ 200 OK

Vision routing (Claude Desktop → text-only model)

   image blocks ──▶ vision model (qwen3-vl) ──▶ [VISION SUMMARY]
                 ──▶ strip original images ──▶ forward to GLM-5.2

🔧 Configuration

Copy config.example.json → config.json. Key sections:

🎫 Token policy

{
  "tokenPolicy": {
    "compactThreshold": 90000,
    "hardLimit": 130000,
    "safetyMargin": 8000,
    "compactMode": "warn",
    "autoReduceMaxTokens": true,
    "retryOnContextError": true,
    "minOutputTokens": 1024
  }
}

Claude Code native compact and tool observation

{
  "claudeConfigPatch": {
    "enabled": true,
    "autoCompactEnabled": true,
    "autoCompactReserveTokens": 30000,
    "hookObserverEnabled": true
  }
}

With the bundled 130k safety limit, reserving 30k configures new Claude Code CLI processes to compact at about 76%. Existing user values for CLAUDE_CODE_AUTO_COMPACT_WINDOW and CLAUDE_AUTOCOMPACT_PCT_OVERRIDE are preserved. The hook observer records only session prefixes, tool-call fingerprints, output sizes, repeated-call counts, and truncation flags; it does not persist source or tool output content.

Agent requests containing tools, tool_use, or tool_result are never sent through generic proxy chunking or text-flattening compaction. When an Agent request reaches the configured threshold, CCProxy Agent keeps every tool_use, tool_use_id, message role, and message position while replacing only older tool_result.content values with explicit placeholders. The three most recent tool results are preserved by default. After an upstream context-limit error, old results are cleared first; if that is insufficient, the newest oversized result keeps bounded head and tail evidence instead of being erased.

🖼️ Vision

{
  "vision": {
    "enabled": true,
    "models": ["qwen3-vl-30b-a3b-instruct", "Qwen3.6-35B-A3B"],
    "compareModels": true,
    "apiKeyEnv": "CCPROXY_VISION_API_KEY",
    "stripImagesAfterSummary": true
  }
}

Desktop users can enter the API key directly on the Multimodal page. It is encrypted with Windows DPAPI or macOS Keychain-backed Electron safe storage and is never returned to the renderer. The environment variable remains an optional CLI fallback:

[Environment]::SetEnvironmentVariable("CCPROXY_VISION_API_KEY", "your-token", "User")

🖥️ Claude Desktop 3P patching

When claudeDesktopConfigPatch.enabled is true, the proxy rewrites the ccswitch Desktop gateway path:

  http://127.0.0.1:15721/claude-desktop   ──▶   http://127.0.0.1:15722/claude-desktop

⚠️ Fully quit and reopen Claude Desktop after starting the proxy — it reads 3P config only at launch.

📜 Logs

Written to logs/ccproxy-agent.log. Useful Chinese log lines:

Message	Meaning
Token预算评估	Estimated input / output / total tokens
已自动降低max_tokens…	Output budget reduced before sending upstream
上游返回上下文超限错误…	Upstream returned a context-limit error, parsed
已降低max_tokens并自动重试一次	Retried once with a safer budget
已触发compact提醒模式	Response will include a /compact reminder
已触发分块执行	Chunking fallback started

🛠️ Development

npm run check      # typecheck
npm test           # run test suite
npm run build      # compile TS → dist
npm run check:gui  # validate desktop UI references
npm run package:gui   # build sanitized portable Windows EXE
npm run package:gui:mac # build macOS DMG + ZIP (run on macOS)
npm run smoke:packaged # run the real packaged context-rescue smoke test

📚 Documentation

• 📐 Design
• ✅ Validation
• 🧭 Next release assessment
• 📚 Architecture and Operations Wiki
• 📦 Latest Release
• 📝 Full Changelog

🔒 Security & Privacy

CCProxy Agent is a local proxy — it can see prompts/responses passing through it, but by default everything stays on your machine.

• ✅ Logs and session snapshots are local-only
• ✅ Release builds reject private config.json files and configured secret bytes
• ✅ Desktop Vision API keys are encrypted with the operating-system credential service
• ✅ CLI users can still use CCPROXY_VISION_API_KEY without writing a key to config
• 🚫 Never commit your config.json, runtime/, logs/, or personal builds

See SECURITY.md for details.

⚠️ Current Limits

• Token counting before upstream is heuristic, not provider-native
• Claude Code CLI native auto-compact settings apply to newly started CLI processes
• Tool-loop hooks are observe-only and require a Claude Code version with HTTP hook support
• Claude Desktop does not expose the same CLI hook lifecycle and receives base proxy protection only
• Agent rescue preserves protocol structure but cannot guarantee lossless recovery after the provider hard limit is exceeded
• Multimodal summarization requires explicit endpoint, model, and Vision API key configuration
• Compact reminders on SSE responses are currently buffered before rewriting
• Chunking is a fallback, not a full long-task planning engine
• Configuration restart is not yet transactional; invalid settings can leave the proxy stopped until corrected
• macOS builds are currently unsigned; Apple notarization requires release signing credentials
• Linux desktop binaries are not currently published

---

🇨🇳 中文说明

CCProxy Agent 是一个放在 Claude CLI / Claude Desktop 和 ccswitch 中间的本地护栏代理。

它不是 ccswitch 的替代品，而是 ccswitch 上层的防撞护栏，主要解决这些问题：

• 📉 快到上下文上限时提醒你执行 /compact
• 🧠 input_tokens + max_tokens 超过模型上下文时，自动降低 max_tokens
• 🔁 上游返回 context limit 400 时，解析错误并自动重试一次
• 🖥️ 临时接管 Claude Desktop 3P 网关配置
• 🖼️ Claude Desktop 发图后调用视觉模型生成摘要，再转给不支持图片的 GLM-5.2

默认拓扑：

Claude CLI / Claude Desktop  ──▶  CCProxy Agent :15722  ──▶  ccswitch :15721  ──▶  模型
                                  (自动降低 / 重试 / 摘要 / 提醒)

快速开始：

npm install
cp config.example.json config.json
npm run dev

核心日志：

• Token预算评估：估算的输入 / 输出 / 总 token
• 已自动降低max_tokens，避免总token撞上上下文硬上限
• 上游返回上下文超限错误，已解析错误详情
• 已降低max_tokens并自动重试一次
• 已触发compact提醒模式

---

Made with 🛡️ for the Claude Code + ccswitch community.

If this saved your session, a ⭐ on GitHub means a lot.

Report a bug · Request a feature · Contributing · View releases