ccgw 0.1.0__tar.gz

ccgw-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package
+        run: python -m pip install -e .
+      - name: Smoke test
+        run: python -c "from ccgw.config import Config; Config.load('config.toml')"
+      - name: Build package
+        run: python -m pip install build && python -m build

ccgw-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,27 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Install build backend
+        run: python -m pip install build
+      - name: Build package
+        run: python -m build
+      - name: Publish package
+        uses: pypa/gh-action-pypi-publish@release/v1

ccgw-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.env
+*.env
+secrets.env
+*.log
+logs/
+*.tar.gz
+.DS_Store
+.idea/
+.vscode/

ccgw-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 XuNeo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ccgw-0.1.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.5
+Name: ccgw
+Version: 0.1.0
+Summary: Local multi-provider Anthropic-protocol gateway for Claude Code: coconut, GLM and MiMo in one /model menu.
+Project-URL: Homepage, https://github.com/XuNeo/ccgw
+Project-URL: Repository, https://github.com/XuNeo/ccgw
+Project-URL: Issues, https://github.com/XuNeo/ccgw/issues
+Author: XuNeo
+License-Expression: MIT
+License-File: LICENSE
+Keywords: anthropic,claude,claude-code,gateway,glm,llm,mimo,proxy
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.115
+Requires-Dist: httpx>=0.27
+Requires-Dist: uvicorn[standard]>=0.32
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cc-gateway
+
+A local multi-provider gateway that impersonates the Anthropic Messages API for
+Claude Code, so you can switch between models from different backends at any
+point in any session.
+
+It forwards the Anthropic dialect only. Every backend must expose an
+Anthropic-compatible endpoint; there is deliberately no OpenAI translation
+layer.
+
+## Providers
+
+| provider | endpoint | auth |
+| --- | --- | --- |
+| `coconut` | `http://127.0.0.1:8787` (local daemon) | `Bearer coconut` |
+| `glm` | `https://open.bigmodel.cn/api/anthropic` | `x-api-key`, `$GLM_API_KEY` |
+| `mimo` | `https://token-plan-cn.xiaomimimo.com/anthropic` | `x-api-key`, `$MIMO_API_KEY` |
+
+## Install
+
+Requires Python 3.11+ (`tomllib` is stdlib there).
+
+```bash
+uv tool install ccgw
+# or
+pipx install ccgw
+```
+
+## Run
+
+The gateway reads its provider registry from a `config.toml`, looked up in
+this order: `$CCGW_CONFIG`, `./config.toml`, `~/.config/ccgw/config.toml`.
+
+```bash
+export GLM_API_KEY=...      # never stored in this repo
+export MIMO_API_KEY=...
+ccgw                        # listens on 127.0.0.1:8788
+ccgw --port 9000            # or --config /path/to/config.toml
+```
+
+A source checkout can run the same entry point directly:
+
+```bash
+pip install -r requirements.txt
+python serve.py
+```
+
+Point Claude Code at it in `~/.claude/settings.json`:
+
+```json
+{
+  "env": {
+    "ANTHROPIC_BASE_URL": "http://127.0.0.1:8788",
+    "ANTHROPIC_AUTH_TOKEN": "ccgw",
+    "ANTHROPIC_API_KEY": "",
+    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"
+  }
+}
+```
+
+Do **not** set `ANTHROPIC_DEFAULT_*_MODEL` or `ANTHROPIC_SMALL_FAST_MODEL`:
+the gateway serves every model from one catalogue, and pinning those variables
+would route background traffic around the router.
+
+## Model naming
+
+Public ids are generated as `claude-<provider>-<slug>` plus a `[1m]` suffix for
+models with a 1M context window. Both parts are load-bearing:
+
+* Claude Code's gateway discovery drops any id that does not contain `claude`
+  or `anthropic`, so the prefix is mandatory for a model to appear in `/model`.
+* Claude Code infers a 1M window from a `[1m]` substring, which is how the
+  gateway communicates window size. `/v1/models` cannot carry it: Claude Code's
+  parser keeps only `id` and `display_name`.
+
+The suffix is presentation only. It is stripped before the request goes
+upstream, because neither GLM nor MiMo accepts a `[1m]` model name on these
+endpoints (both reject it outright), even though their Coding Plan docs
+describe the suffix.
+
+## Behaviour worth knowing
+
+**History sanitisation.** Every request has `thinking` and `redacted_thinking`
+blocks stripped from the history, unconditionally. Thinking signatures are
+bound to the model and credentials that produced them, and Claude Code replays
+the full history verbatim when you switch models, so a stale signature is a 400
+that can wedge a session permanently. Stripping is stateless, matches
+Anthropic's own guidance for switching models, and is a no-op for backends that
+ignore thinking anyway. The top-level `thinking` parameter is removed in
+lockstep, since removing the blocks alone is itself a 400.
+
+**Tool repair.** Tool ids are normalised to `^[a-zA-Z0-9_-]+$` and dangling
+`tool_use` blocks get a synthetic error result, both of which are otherwise
+400s after an interrupted turn.
+
+**Errors.** Upstream failures are re-shaped into the Anthropic envelope but the
+upstream message text is preserved verbatim, because Claude Code matches on it
+to drive automatic capability downgrade and retry.
+
+**Streaming.** Upstream bytes are relayed unbuffered, with a `ping` injected
+every 15 seconds of silence to stay under Claude Code's 300 second stream
+watchdog.
+
+**Token counting.** `/v1/messages/count_tokens` is answered locally and never
+proxied; coconut does not implement it, and Claude Code falls back to its own
+estimate anyway.
+
+## License
+
+[MIT](LICENSE)

ccgw-0.1.0/README.md

@@ -0,0 +1,110 @@
+# cc-gateway
+
+A local multi-provider gateway that impersonates the Anthropic Messages API for
+Claude Code, so you can switch between models from different backends at any
+point in any session.
+
+It forwards the Anthropic dialect only. Every backend must expose an
+Anthropic-compatible endpoint; there is deliberately no OpenAI translation
+layer.
+
+## Providers
+
+| provider | endpoint | auth |
+| --- | --- | --- |
+| `coconut` | `http://127.0.0.1:8787` (local daemon) | `Bearer coconut` |
+| `glm` | `https://open.bigmodel.cn/api/anthropic` | `x-api-key`, `$GLM_API_KEY` |
+| `mimo` | `https://token-plan-cn.xiaomimimo.com/anthropic` | `x-api-key`, `$MIMO_API_KEY` |
+
+## Install
+
+Requires Python 3.11+ (`tomllib` is stdlib there).
+
+```bash
+uv tool install ccgw
+# or
+pipx install ccgw
+```
+
+## Run
+
+The gateway reads its provider registry from a `config.toml`, looked up in
+this order: `$CCGW_CONFIG`, `./config.toml`, `~/.config/ccgw/config.toml`.
+
+```bash
+export GLM_API_KEY=...      # never stored in this repo
+export MIMO_API_KEY=...
+ccgw                        # listens on 127.0.0.1:8788
+ccgw --port 9000            # or --config /path/to/config.toml
+```
+
+A source checkout can run the same entry point directly:
+
+```bash
+pip install -r requirements.txt
+python serve.py
+```
+
+Point Claude Code at it in `~/.claude/settings.json`:
+
+```json
+{
+  "env": {
+    "ANTHROPIC_BASE_URL": "http://127.0.0.1:8788",
+    "ANTHROPIC_AUTH_TOKEN": "ccgw",
+    "ANTHROPIC_API_KEY": "",
+    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"
+  }
+}
+```
+
+Do **not** set `ANTHROPIC_DEFAULT_*_MODEL` or `ANTHROPIC_SMALL_FAST_MODEL`:
+the gateway serves every model from one catalogue, and pinning those variables
+would route background traffic around the router.
+
+## Model naming
+
+Public ids are generated as `claude-<provider>-<slug>` plus a `[1m]` suffix for
+models with a 1M context window. Both parts are load-bearing:
+
+* Claude Code's gateway discovery drops any id that does not contain `claude`
+  or `anthropic`, so the prefix is mandatory for a model to appear in `/model`.
+* Claude Code infers a 1M window from a `[1m]` substring, which is how the
+  gateway communicates window size. `/v1/models` cannot carry it: Claude Code's
+  parser keeps only `id` and `display_name`.
+
+The suffix is presentation only. It is stripped before the request goes
+upstream, because neither GLM nor MiMo accepts a `[1m]` model name on these
+endpoints (both reject it outright), even though their Coding Plan docs
+describe the suffix.
+
+## Behaviour worth knowing
+
+**History sanitisation.** Every request has `thinking` and `redacted_thinking`
+blocks stripped from the history, unconditionally. Thinking signatures are
+bound to the model and credentials that produced them, and Claude Code replays
+the full history verbatim when you switch models, so a stale signature is a 400
+that can wedge a session permanently. Stripping is stateless, matches
+Anthropic's own guidance for switching models, and is a no-op for backends that
+ignore thinking anyway. The top-level `thinking` parameter is removed in
+lockstep, since removing the blocks alone is itself a 400.
+
+**Tool repair.** Tool ids are normalised to `^[a-zA-Z0-9_-]+$` and dangling
+`tool_use` blocks get a synthetic error result, both of which are otherwise
+400s after an interrupted turn.
+
+**Errors.** Upstream failures are re-shaped into the Anthropic envelope but the
+upstream message text is preserved verbatim, because Claude Code matches on it
+to drive automatic capability downgrade and retry.
+
+**Streaming.** Upstream bytes are relayed unbuffered, with a `ping` injected
+every 15 seconds of silence to stay under Claude Code's 300 second stream
+watchdog.
+
+**Token counting.** `/v1/messages/count_tokens` is answered locally and never
+proxied; coconut does not implement it, and Claude Code falls back to its own
+estimate anyway.
+
+## License
+
+[MIT](LICENSE)

ccgw-0.1.0/ccgw/__init__.py

@@ -0,0 +1,7 @@
+"""cc-gateway: a multi-provider Anthropic-dialect gateway for Claude Code."""
+
+__version__ = "0.1.0"
+
+__all__ = ["create_app"]
+
+from .app import create_app  # noqa: E402

ccgw-0.1.0/ccgw/app.py

@@ -0,0 +1,182 @@
+"""HTTP surface: the three endpoints Claude Code actually calls."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, Request, Response
+from fastapi.responses import JSONResponse, StreamingResponse
+
+from .config import Config
+from .errors import anthropic_error
+from .provider import Registry, UpstreamError
+
+log = logging.getLogger("ccgw")
+
+CONFIG_PATH = os.environ.get("CCGW_CONFIG", "config.toml")
+
+
+def create_app(config: Config | None = None) -> FastAPI:
+    config = config or Config.load(CONFIG_PATH)
+    registry = Registry(config)
+
+    @asynccontextmanager
+    async def lifespan(_: FastAPI):
+        for warning in await registry.refresh():
+            log.warning("%s", warning)
+        log.info(
+            "catalogue ready: %d model(s) across %d provider(s)",
+            len(registry.models),
+            len(registry.clients),
+        )
+        for entry in registry.models.values():
+            log.info("  %-38s -> %s/%s", entry.public_id, entry.provider, entry.upstream)
+        yield
+        await registry.aclose()
+
+    app = FastAPI(title="cc-gateway", lifespan=lifespan)
+
+    # ------------------------------------------------------------ /v1/models
+
+    @app.get("/v1/models")
+    async def list_models():
+        """Claude Code keeps only `id` and `display_name`; everything else is
+        dropped by its parser. It also fails discovery on any redirect and
+        gives up after 3 seconds, so this must be served locally and fast."""
+        return {
+            "object": "list",
+            "has_more": False,
+            "data": [
+                {
+                    "id": entry.public_id,
+                    "type": "model",
+                    "display_name": entry.display_name,
+                    "created_at": "2026-01-01T00:00:00Z",
+                }
+                for entry in registry.models.values()
+            ],
+        }
+
+    # ---------------------------------------------- /v1/messages/count_tokens
+
+    @app.post("/v1/messages/count_tokens")
+    async def count_tokens(request: Request):
+        """Answered locally and never forwarded.
+
+        coconut does not implement this endpoint at all, and Claude Code allows
+        10 seconds before falling back to its own estimate -- proxying would
+        only add latency. A rough local estimate keeps the context meter
+        approximately honest.
+        """
+        try:
+            body = await request.json()
+        except Exception:
+            body = {}
+        blob = json.dumps(
+            {
+                "system": body.get("system"),
+                "messages": body.get("messages"),
+                "tools": body.get("tools"),
+            },
+            ensure_ascii=False,
+        )
+        # ~3.5 chars per token is a better fit for mixed CJK/code than /4.
+        return {"input_tokens": max(1, int(len(blob) / 3.5))}
+
+    # ---------------------------------------------------------- /v1/messages
+
+    @app.post("/v1/messages")
+    async def messages(request: Request):
+        try:
+            body = await request.json()
+        except Exception:
+            return JSONResponse(
+                anthropic_error(400, "Request body must be valid JSON."), 400
+            )
+
+        entry = registry.resolve(body.get("model"))
+        if entry is None:
+            return JSONResponse(
+                anthropic_error(404, "No models are configured on this gateway."), 404
+            )
+
+        client = registry.client_for(entry)
+        session = request.headers.get("x-claude-code-session-id", "-")
+        surface = request.headers.get("x-app", "-")
+        log.info(
+            "%s %s -> %s/%s (session=%s)",
+            surface,
+            body.get("model"),
+            entry.provider,
+            entry.upstream,
+            session[:8],
+        )
+
+        try:
+            headers = client.build_headers(dict(request.headers))
+        except RuntimeError as exc:
+            return JSONResponse(anthropic_error(500, str(exc)), 500)
+
+        payload = client.build_payload(body, entry)
+
+        if not payload.get("stream"):
+            try:
+                upstream = await client.messages_once(payload, headers)
+            except UpstreamError as exc:
+                return JSONResponse(exc.payload, exc.status)
+            except Exception as exc:
+                return JSONResponse(
+                    anthropic_error(502, f"[{entry.provider}] {exc}"), 502
+                )
+            result = upstream.json()
+            # Report the id the client asked for, not the upstream one.
+            if isinstance(result, dict):
+                result["model"] = body.get("model") or entry.public_id
+            return JSONResponse(result, upstream.status_code)
+
+        try:
+            stream = client.messages_stream(payload, headers)
+            first = await stream.__anext__()
+        except StopAsyncIteration:
+            return JSONResponse(
+                anthropic_error(502, f"[{entry.provider}] empty upstream response"), 502
+            )
+        except UpstreamError as exc:
+            return JSONResponse(exc.payload, exc.status)
+        except Exception as exc:
+            return JSONResponse(anthropic_error(502, f"[{entry.provider}] {exc}"), 502)
+
+        async def relay():
+            yield first
+            async for chunk in stream:
+                yield chunk
+
+        return StreamingResponse(
+            relay(),
+            media_type="text/event-stream",
+            headers={
+                "Cache-Control": "no-cache, no-transform",
+                "Connection": "keep-alive",
+                # Defeat any buffering proxy sitting in front of us.
+                "X-Accel-Buffering": "no",
+            },
+        )
+
+    @app.get("/healthz")
+    async def healthz():
+        return {"ok": True, "models": len(registry.models)}
+
+    @app.head("/api/hello")
+    async def hello():
+        # Claude Code fires this once at startup as a fire-and-forget TCP
+        # preconnect probe and ignores the response; answer so it does not
+        # land in the access log as a 404.
+        return Response(status_code=204)
+
+    return app
+
+
+app = create_app

ccgw-0.1.0/ccgw/cli.py

@@ -0,0 +1,63 @@
+"""Command-line entry point: `ccgw` (installed via [project.scripts])."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+from pathlib import Path
+
+import uvicorn
+
+from ccgw.app import create_app
+from ccgw.config import Config
+
+DEFAULT_CONFIG_DIRS = (Path.cwd(), Path.home() / ".config" / "ccgw")
+
+
+def find_config() -> str | None:
+    """First existing config.toml among the well-known locations."""
+    for directory in DEFAULT_CONFIG_DIRS:
+        candidate = directory / "config.toml"
+        if candidate.is_file():
+            return str(candidate)
+    return None
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Claude Code multi-provider gateway")
+    parser.add_argument(
+        "--config",
+        default=os.environ.get("CCGW_CONFIG"),
+        help="Config file path (default: $CCGW_CONFIG, ./config.toml, ~/.config/ccgw/config.toml)",
+    )
+    parser.add_argument("--host", default=None)
+    parser.add_argument("--port", type=int, default=None)
+    args = parser.parse_args()
+
+    config_path = args.config or find_config()
+    if not config_path:
+        parser.error(
+            "no config found: pass --config, set $CCGW_CONFIG, "
+            "or place config.toml in the cwd or ~/.config/ccgw/"
+        )
+
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)-7s %(name)s | %(message)s",
+    )
+
+    config = Config.load(config_path)
+    app = create_app(config)
+    uvicorn.run(
+        app,
+        host=args.host or config.server.host,
+        port=args.port or config.server.port,
+        log_level="info",
+        # Streaming correctness: never let the server buffer responses.
+        timeout_keep_alive=75,
+    )
+
+
+if __name__ == "__main__":
+    main()