fusionAIze · typelicious · Mar 30, 2026 · Mar 29, 2026 · Mar 29, 2026 · Mar 29, 2026
diff --git a/README.md b/README.md
@@ -23,6 +23,7 @@ Runs locally on Linux, macOS, and Windows, with first-class workstation guidance
 - [Quickstart](#quickstart)
 - [Why fusionAIze Gate](#why-fusionaize-gate)
 - [How It Works](#how-it-works)
+- [Anthropic Bridge](#anthropic-bridge-optional)
 - [API Surface](#api-surface)
 - [How fusionAIze Gate Compares](#how-fusionaize-gate-compares)
 - [Deployment](#deployment)
@@ -211,23 +212,55 @@ which -a faigate
 ## How It Works
 
 ```text
-Client (OpenClaw, n8n, CLI, custom app)
-  |
-  v
-http://127.0.0.1:8090/v1
-  |
-  +--> policy rules
-  +--> static rules
-  +--> heuristic rules
-  +--> optional request hooks
-  +--> optional routing modes (auto / eco / premium / free / custom)
-  +--> optional client profile defaults
-  +--> optional LLM classifier
-  |
-  +--> provider selection and fallback
-         |- cloud APIs
-         |- proxy providers
-         `- local workers
+                                 fusionAIze Gate
+
+    +---------------------+   +--------------------+   +--------------------+
+    | Claude-native       |   | OpenAI-native      |   | Automation / CLI   |
+    | clients             |   | clients            |   | clients            |
+    |                     |   |                    |   |                    |
+    | Claude Code         |   | OpenClaw           |   | n8n                |
+    | Claude Desktop      |   | opencode           |   | curl / scripts     |
+    | Anthropic SDK tools |   | OpenAI SDK apps    |   | custom apps        |
+    +---------------------+   +--------------------+   +--------------------+
+               \                        |                       /
+                v                       v                      v
+         +-------------------------------------------------------------+
+         | One local endpoint                                          |
+         |                                                             |
+         | http://127.0.0.1:8090                                       |
+         | OpenAI-compatible + Anthropic-compatible bridge             |
+         +-------------------------------------------------------------+
+                                        |
+                                        v
+         +-------------------------------------------------------------+
+         | Routing core - Chooses the best route for the job           |
+         |                                                             |
+         | - quality / cost / speed / heuristics / policies            |
+         | - client profiles / routing modes / hooks                   |
+         | - health / readiness / fallback                             |
+         +-------------------------------------------------------------+
+                                        |
+               +------------------------+------------------------+
+               |                        |                        |
+               v                        v                        v
++------------------------+ +------------------------+ +------------------------+
+| Direct providers       | | Aggregators / mirrors  | | Local workers / models |
+| Anthropic              | | Kilo                   | | Ollama                 |
+| OpenAI                 | | BLACKBOX               | | vLLM                   |
+| Google                 | | OpenRouter             | | LM Studio              |
+| DeepSeek               | |                        | | LAN GPU workers        |
++------------------------+ +------------------------+ +------------------------+
+
+    +----------------------------------------------------------------------+
+    | Stable session continuity                                            |
+    |                                                                      |
+    | Keep one local endpoint across Claude-native, OpenAI-native, and     |
+    | automation-driven workflows. When Anthropic quota, one provider      |
+    | account, or one route path is exhausted, Gate can continue through   |
+    | another healthy direct route, aggregator route, or local worker      |
+    | without retooling clients. Hooks, health checks, readiness, and      |
+    | fallback stay in one gateway core.                                   |
+    +----------------------------------------------------------------------+
 ```
 
 Routing is layered on purpose:
@@ -241,6 +274,58 @@ Routing is layered on purpose:
 
 For OpenClaw specifically, both one-agent and many-agent traffic can use the same endpoint. fusionAIze Gate can distinguish delegated traffic through request headers such as `x-openclaw-source` when they are present.
 
+## Anthropic Bridge (Optional)
+
+fusionAIze Gate can also expose a small Anthropic-/Claude-compatible bridge surface for clients that speak `POST /v1/messages` instead of OpenAI chat completions.
+
+The bridge stays intentionally narrow:
+
+- it validates and normalizes Anthropic-style requests
+- it maps them into Gate's internal canonical request model
+- the existing Gate core still owns hooks, policies, routing, health checks, and fallback
+- responses are mapped back into Anthropic-compatible message envelopes
+
+That makes the bridge useful when a Claude-oriented client should keep one stable local endpoint while Gate decides whether the request should stay on a direct Anthropic route, move to an Anthropic-capable aggregator, or step sideways to a similar coding-capable route or local worker.
+
+Operationally, this helps in two common cases:
+
+- Anthropic subscription or account limits are exhausted, but you still want the session to continue through another route with similar coding or context characteristics.
+- Anthropic-capable aggregator routes such as Kilo or BLACKBOX are available, but you want Gate health checks and fallback rules to decide whether they are actually usable.
+
+Do not assume every aggregator route escapes Anthropic limits. Some routes may still rely on a BYOK Anthropic key from the same account. Keep those paths probeable, degradeable, and out of the top fallback position if they share the same exhausted quota domain.
+
+The same pattern also helps when the best fallback is not Anthropic at all. Gate can route the same Claude-oriented session toward a coding-capable OpenAI-, Gemini-, DeepSeek-, or local-worker lane when that is the healthiest path with acceptable context and tool fit.
+
+Minimal bridge config:
+
+```yaml
+api_surfaces:
+  anthropic_messages: true
+
+anthropic_bridge:
+  enabled: true
+  allow_claude_code_hints: true
+  model_aliases:
+    claude-code: auto
+    claude-code-fast: eco
+    claude-code-premium: premium
+```
+
+Known v1 limits:
+
+- non-streaming only
+- text content blocks only
+- `count_tokens` is a local estimate, not provider-exact accounting
+- the optional `claude-code-router` hook only adds routing hints; it is not the protocol bridge
+
+Local smoke test:
+
+```bash
+./docs/examples/anthropic-bridge-smoke.sh
+```
+
+For a fuller operator view, see [docs/anthropic-bridge.md](./docs/anthropic-bridge.md) and [docs/API.md](./docs/API.md).
+
 ## API Surface
 
 fusionAIze Gate keeps the primary surface compact and OpenAI-compatible. The full endpoint reference lives in [docs/API.md](./docs/API.md).
@@ -250,6 +335,8 @@ fusionAIze Gate keeps the primary surface compact and OpenAI-compatible. The ful
 | `GET /health` | Service health, provider status, and capability coverage |
 | `GET /v1/models` | OpenAI-compatible model list |
 | `POST /v1/chat/completions` | OpenAI-compatible chat routing |
+| `POST /v1/messages` | Optional Anthropic-/Claude-compatible bridge route |
+| `POST /v1/messages/count_tokens` | Optional Anthropic-compatible token estimate |
 | `POST /v1/images/generations` | OpenAI-compatible image generation |
 | `POST /v1/images/edits` | OpenAI-compatible image editing |
 | `POST /api/route` | Chat routing dry-run with decision details |

diff --git a/config.yaml b/config.yaml
@@ -920,6 +920,15 @@ request_hooks:
   - profile-override-header
   - mode-override-header
   on_error: continue
+api_surfaces:
+  anthropic_messages: false
+anthropic_bridge:
+  enabled: false
+  allow_claude_code_hints: true
+  model_aliases:
+    claude-code: auto
+    claude-code-fast: eco
+    claude-code-premium: premium
 routing_modes:
   default: auto
   enabled: true

diff --git a/docs/API.md b/docs/API.md
@@ -36,6 +36,85 @@ curl -fsS http://127.0.0.1:8090/v1/chat/completions \
   }'
 ```
 
+## Optional Anthropic-Compatible Bridge
+
+The Anthropic bridge stays optional and v1 is intentionally narrow. It exists to let Claude-oriented clients keep one stable local endpoint while Gate still owns routing, health checks, fallback, and provider selection.
+
+Enable it with:
+
+```yaml
+api_surfaces:
+  anthropic_messages: true
+
+anthropic_bridge:
+  enabled: true
+```
+
+### `POST /v1/messages`
+
+Routes Anthropic-/Claude-style message requests through the same internal Gate routing path used by the OpenAI-compatible surface.
+
+- validates a small v1 subset of Anthropic `messages`
+- supports a simple `system` prompt
+- supports text content blocks
+- non-streaming only in v1
+- optional `anthropic_bridge.model_aliases` can map Claude-facing model ids onto Gate routing modes or provider ids
+
+```bash
+curl -fsS http://127.0.0.1:8090/v1/messages \
+  -H 'Content-Type: application/json' \
+  -H 'anthropic-client: claude-code' \
+  -d '{
+    "model": "claude-code",
+    "system": "Prefer concise technical explanations.",
+    "messages": [
+      {"role": "user", "content": "Summarize the current fallback path."}
+    ]
+  }'
+```
+
+Response shape is Anthropic-compatible and still carries the normal Gate response headers such as:
+
+- `X-faigate-Provider`
+- `X-faigate-Profile`
+- `X-faigate-Layer`
+- `X-faigate-Rule`
+
+### `POST /v1/messages/count_tokens`
+
+Returns a minimal Anthropic-compatible token-count response for the same request structure as `/v1/messages`.
+
+v1 uses a deterministic local estimate instead of provider-exact token accounting.
+
+```bash
+curl -fsS http://127.0.0.1:8090/v1/messages/count_tokens \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "claude-code",
+    "messages": [
+      {"role": "user", "content": "Count these tokens."}
+    ]
+  }'
+```
+
+Response body:
+
+```json
+{"input_tokens": 11}
+```
+
+Response headers make the approximation explicit:
+
+- `X-faigate-Token-Count-Exact: false`
+- `X-faigate-Token-Count-Method: estimated-char-v1`
+
+Known v1 bridge limits:
+
+- non-streaming only
+- text content blocks only
+- image or binary content blocks are rejected
+- `count_tokens` is an estimate, not provider-exact accounting
+
 ### `POST /v1/images/generations`
 
 Routes image-generation requests to providers with `capabilities.image_generation: true`.

diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
@@ -298,6 +298,69 @@ fusionAIze Gate supports two lightweight extension seams:
   - bounded pre-routing hint injection
   - can fail closed depending on `request_hooks.on_error`
 
+For optional Claude-Code-/Anthropic-bridge routing refinement, you can load the
+community hook shipped in this repo:
+
+```yaml
+request_hooks:
+  enabled: true
+  community_hooks_dir: "./hooks/community"
+  hooks:
+    - claude-code-router
+```
+
+The hook stays optional and only adds routing hints for bridge traffic. It does
+not perform protocol translation. By default it treats Anthropic bridge traffic
+as `coding-default`, and it also understands bridge metadata such as
+`claude_code_profile: premium` or `claude_code_profile: fast`.
+
+## Anthropic Bridge Surface
+
+The Anthropic bridge is an optional additional API surface inside Gate. It does
+not replace the OpenAI-compatible surface and it does not add a second routing
+stack.
+
+Relevant config blocks:
+
+- `api_surfaces`
+- `anthropic_bridge`
+- optional `request_hooks` when you want Claude-Code-specific routing hints
+
+Minimal example:
+
+```yaml
+api_surfaces:
+  anthropic_messages: true
+
+anthropic_bridge:
+  enabled: true
+  allow_claude_code_hints: true
+  model_aliases:
+    claude-code: auto
+    claude-code-fast: eco
+    claude-code-premium: premium
+```
+
+What this means:
+
+- `api_surfaces.anthropic_messages`
+  - exposes `POST /v1/messages` and `POST /v1/messages/count_tokens`
+- `anthropic_bridge.enabled`
+  - enables request parsing, canonical mapping, and response remapping
+- `anthropic_bridge.model_aliases`
+  - lets you keep stable Claude-facing model ids while Gate routes internally
+- `anthropic_bridge.allow_claude_code_hints`
+  - preserves bridge metadata for optional request hooks such as `claude-code-router`
+
+Recommended operational pattern:
+
+- use stable logical aliases like `claude-code`, `claude-code-fast`, and `claude-code-premium`
+- keep direct Anthropic routes, Anthropic-capable aggregators, and local workers all probeable
+- be careful with aggregator routes that may still use a BYOK Anthropic key from the same quota domain
+- prefer health checks and fallback ordering over assuming every Anthropic-shaped route is independent
+
+For the end-to-end flow and local smoke example, see [Anthropic Bridge](./anthropic-bridge.md).
+
 Use the onboarding docs and starter examples when introducing a new client instead of hand-authoring these sections from scratch.
 
 ## Config Wizard