coderouter-cli 2.6.0__tar.gz → 2.6.1__tar.gz

{coderouter_cli-2.6.0 → coderouter_cli-2.6.1}/.gitignore

@@ -36,6 +36,7 @@ ENV/
 # _OUTPUTS
 # ============================================================
 _OUTPUTS/
+_run/
 
 # uv
 # Note: uv.lock SHOULD be committed (per plan.md §5.4)

{coderouter_cli-2.6.0 → coderouter_cli-2.6.1}/CHANGELOG.md

@@ -6,6 +6,51 @@ versioning follows [SemVer](https://semver.org/).
 
 ---
 
+## [v2.6.1] — 2026-06-28 (Token-savings accounting)
+
+Patch release: surfaces **token-savings accounting** in the metrics layer
+and dashboard. The figure is owned by core, so it appears even when no
+plugin is installed (trim savings from the context-budget guard), and the
+optional `compress` plugin adds to the same total via a neutral
+`tokens-saved` log event. **No new core dependency**, **no behavioral
+change** to existing paths, and **fully backward compatible** — existing
+counters and events are untouched; the new buckets are additive.
+
+### Added
+
+- **Token-savings buckets in `MetricsCollector`**
+  (`coderouter/metrics/collector.py`). `tokens_saved_total` plus a
+  per-mechanism breakdown (`tokens_saved_by_mechanism`). Two feeds
+  aggregate under one schema: `trim` (derived from the existing
+  `context-budget-trimmed` event's before/after token estimate) and
+  `compress` (the neutral `tokens-saved` event emitted by the compress
+  plugin — no core import). Wired through `snapshot()`, `save_state()`,
+  `load_state()`, and `reset()`.
+- **Dashboard Token Savings tiles**
+  (`coderouter/ingress/dashboard_routes.py`). Three tiles — trim /
+  compress / total — in the "Cost & Language Tax" panel, zero-filled so a
+  fresh or local-only deployment renders cleanly.
+
+### Docs / examples
+
+- Reorganized provider samples under `examples/` with a category index.
+- Added the language-tax guide (JA/EN) and a Claude Code +
+  llama.cpp/vllm backend guide.
+
+### Tests
+
+- `tests/test_tokens_saved_metric.py` — trim/compress accounting,
+  negative-delta clamping, combined aggregate, persistence round-trip,
+  and reset. Full suite: **1263 passed, 1 skipped**.
+
+### Companion
+
+- `coderouter-plugin-compress` emits the `tokens-saved` event (plugin
+  branch `feat/tokens-saved-emit`, v0.2.0). CodeRouter core works
+  standalone — trim savings show without the plugin.
+
+---
+
 ## [v2.6.0] — 2026-06-20 (Language Tax: measure, route, visualize)
 
 Minor release: makes the CJK **"language tax"** — cloud tokenizers bill

{coderouter_cli-2.6.0 → coderouter_cli-2.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coderouter-cli
-Version: 2.6.0
+Version: 2.6.1
 Summary: Local-first, free-first, fallback-built-in LLM router. Claude Code / OpenAI compatible.
 Project-URL: Homepage, https://github.com/zephel01/CodeRouter
 Project-URL: Repository, https://github.com/zephel01/CodeRouter
@@ -161,6 +161,36 @@ ANTHROPIC_BASE_URL=http://localhost:8088 ANTHROPIC_AUTH_TOKEN=dummy claude
 | **`coderouter replay`** | provider 切替の効果を統計比較 (A/B 分析) / `--suggest-rules` でルール最適化提案 |
 | **Continuous Probe** | idle 時も定期的に backend を監視 |
 
+### 言語税トラッキング — v2.6.0
+
+日本語などの CJK テキストは、クラウドのトークナイザだと「同じ意味の英語」より多くのトークンを消費します（**実測: GPT-4o 系 o200k で平均 1.6 倍、GPT-4 系 cl100k で平均 2.0 倍**）。ローカル LLM は課金されないので、この「言語税」はクラウド利用時だけ効いてきます。CodeRouter v2.6.0 はこれを **計測・ルーティング回避・可視化** します。
+
+| 機能 | 何をしてくれるか |
+|---|---|
+| **言語税の計測** | プロバイダに `tokenizer_path`（ローカルの `tokenizer.json`）を指定すると、char/4 ヒューリスティック比の実トークン倍率と割増 USD を算出（ネットワーク不要・未設定なら無効） |
+| **`cjk_ratio_min` ルーティング** | CJK 比率が高いリクエストを自動でローカル LLM（課金ゼロ）へ。コードや英語はクラウドへ |
+| **ダッシュボード可視化** | `/dashboard` の「Cost & Language Tax」パネルで総支出・キャッシュ節約・言語税をリアルタイム表示 |
+
+```yaml
+# providers.yaml — CJK 多めのターンはローカルへ自動回避
+auto_router:
+  rules:
+    - match: { cjk_ratio_min: 0.3 }   # 日本語が3割以上 → ローカル
+      profile: local
+    - match: { has_tools: true }      # ツール使用 → クラウド
+      profile: cloud
+  default_rule_profile: cloud
+
+providers:
+  - name: cloud-sonnet
+    kind: anthropic
+    base_url: https://api.anthropic.com
+    model: claude-sonnet-4-6
+    tokenizer_path: ~/.coderouter/tokenizers/sonnet.json   # 言語税の正確計測（任意）
+```
+
+詳細 → [言語税ガイド](./docs/guides/language-tax.md)
+
 ### Launcher — llama.cpp / vllm 起動 UI
 
 `http://localhost:8088/launcher` で開けるブラウザ UI。llama.cpp や vllm を GUI で起動・管理できます。
@@ -229,6 +259,7 @@ providers:
 | 使いこなす | [利用ガイド](./docs/guides/usage-guide.md) |
 | 無料で回す | [無料枠ガイド](./docs/guides/free-tier-guide.md) |
 | llama.cpp / vllm を GUI で起動 | [Launcher ガイド](./docs/backends/launcher.md) |
+| 言語税を計測・回避する | [言語税ガイド](./docs/guides/language-tax.md) |
 | 詰まった | [トラブルシューティング](./docs/guides/troubleshooting.md) |
 | 設計を知りたい | [アーキテクチャ詳細](./docs/concepts/architecture.md) |
 | 全リリース履歴 | [CHANGELOG](./CHANGELOG.md) |

{coderouter_cli-2.6.0 → coderouter_cli-2.6.1}/README.en.md

@@ -116,6 +116,36 @@ Full decision matrix → [Do I need CodeRouter?](./docs/start/when-do-i-need-cod
 | **`coderouter replay`** | Compare providers statistically (A/B analysis) / `--suggest-rules` for automated rule suggestions |
 | **Continuous Probe** | Background health monitoring even during idle |
 
+### Language Tax tracking — v2.6.0
+
+CJK text (Japanese / Chinese / Korean) costs more tokens on cloud tokenizers than the same meaning in English (**measured: ~1.6× on average with GPT-4o-era o200k, ~2.0× with GPT-4-era cl100k**). Local models bill nothing per token, so this "language tax" only bites on the cloud leg. CodeRouter v2.6.0 makes it **measurable, routable, and visible**.
+
+| Feature | What it does |
+|---|---|
+| **Language-tax measurement** | Set a provider's `tokenizer_path` (a local `tokenizer.json`) to compute the real token multiplier vs the char/4 heuristic and the extra USD. No network; inert when unset. |
+| **`cjk_ratio_min` routing** | Auto-route CJK-heavy turns to a local (tax-free) model; code/English falls through to the cloud chain. |
+| **Dashboard panel** | The `/dashboard` "Cost & Language Tax" panel shows total spend, cache savings, and language-tax spend live. |
+
+```yaml
+# providers.yaml — steer CJK-heavy turns to local
+auto_router:
+  rules:
+    - match: { cjk_ratio_min: 0.3 }   # >=30% CJK chars -> local
+      profile: local
+    - match: { has_tools: true }      # tool use -> cloud
+      profile: cloud
+  default_rule_profile: cloud
+
+providers:
+  - name: cloud-sonnet
+    kind: anthropic
+    base_url: https://api.anthropic.com
+    model: claude-sonnet-4-6
+    tokenizer_path: ~/.coderouter/tokenizers/sonnet.json   # accurate language-tax (optional)
+```
+
+Details → [Language Tax guide](./docs/guides/language-tax.en.md)
+
 ### Launcher — llama.cpp / vllm GUI
 
 Browser UI at `http://localhost:8088/launcher` for starting and managing local inference backends.
@@ -184,6 +214,7 @@ More detail → [Usage guide](./docs/guides/usage-guide.en.md) · [Architecture]
 | Use it well | [Usage guide](./docs/guides/usage-guide.en.md) |
 | Run for free | [Free-tier guide](./docs/guides/free-tier-guide.en.md) |
 | Launch llama.cpp / vllm via GUI | [Launcher guide](./docs/backends/launcher.md) |
+| Measure & avoid the language tax | [Language Tax guide](./docs/guides/language-tax.en.md) |
 | Stuck? | [Troubleshooting](./docs/guides/troubleshooting.en.md) |
 | Understand the design | [Architecture](./docs/concepts/architecture.md) |
 | Full release history | [CHANGELOG](./CHANGELOG.md) |

{coderouter_cli-2.6.0 → coderouter_cli-2.6.1}/README.md

@@ -116,6 +116,36 @@ ANTHROPIC_BASE_URL=http://localhost:8088 ANTHROPIC_AUTH_TOKEN=dummy claude
 | **`coderouter replay`** | provider 切替の効果を統計比較 (A/B 分析) / `--suggest-rules` でルール最適化提案 |
 | **Continuous Probe** | idle 時も定期的に backend を監視 |
 
+### 言語税トラッキング — v2.6.0
+
+日本語などの CJK テキストは、クラウドのトークナイザだと「同じ意味の英語」より多くのトークンを消費します（**実測: GPT-4o 系 o200k で平均 1.6 倍、GPT-4 系 cl100k で平均 2.0 倍**）。ローカル LLM は課金されないので、この「言語税」はクラウド利用時だけ効いてきます。CodeRouter v2.6.0 はこれを **計測・ルーティング回避・可視化** します。
+
+| 機能 | 何をしてくれるか |
+|---|---|
+| **言語税の計測** | プロバイダに `tokenizer_path`（ローカルの `tokenizer.json`）を指定すると、char/4 ヒューリスティック比の実トークン倍率と割増 USD を算出（ネットワーク不要・未設定なら無効） |
+| **`cjk_ratio_min` ルーティング** | CJK 比率が高いリクエストを自動でローカル LLM（課金ゼロ）へ。コードや英語はクラウドへ |
+| **ダッシュボード可視化** | `/dashboard` の「Cost & Language Tax」パネルで総支出・キャッシュ節約・言語税をリアルタイム表示 |
+
+```yaml
+# providers.yaml — CJK 多めのターンはローカルへ自動回避
+auto_router:
+  rules:
+    - match: { cjk_ratio_min: 0.3 }   # 日本語が3割以上 → ローカル
+      profile: local
+    - match: { has_tools: true }      # ツール使用 → クラウド
+      profile: cloud
+  default_rule_profile: cloud
+
+providers:
+  - name: cloud-sonnet
+    kind: anthropic
+    base_url: https://api.anthropic.com
+    model: claude-sonnet-4-6
+    tokenizer_path: ~/.coderouter/tokenizers/sonnet.json   # 言語税の正確計測（任意）
+```
+
+詳細 → [言語税ガイド](./docs/guides/language-tax.md)
+
 ### Launcher — llama.cpp / vllm 起動 UI
 
 `http://localhost:8088/launcher` で開けるブラウザ UI。llama.cpp や vllm を GUI で起動・管理できます。
@@ -184,6 +214,7 @@ providers:
 | 使いこなす | [利用ガイド](./docs/guides/usage-guide.md) |
 | 無料で回す | [無料枠ガイド](./docs/guides/free-tier-guide.md) |
 | llama.cpp / vllm を GUI で起動 | [Launcher ガイド](./docs/backends/launcher.md) |
+| 言語税を計測・回避する | [言語税ガイド](./docs/guides/language-tax.md) |
 | 詰まった | [トラブルシューティング](./docs/guides/troubleshooting.md) |
 | 設計を知りたい | [アーキテクチャ詳細](./docs/concepts/architecture.md) |
 | 全リリース履歴 | [CHANGELOG](./CHANGELOG.md) |

{coderouter_cli-2.6.0 → coderouter_cli-2.6.1}/coderouter/ingress/dashboard_routes.py

@@ -184,6 +184,21 @@ _DASHBOARD_HTML = r"""<!doctype html>
         </div>
       </div>
       <div id="language-tax-by-provider" class="text-xs text-slate-400 tabnum mt-3"></div>
+      <!-- Token Savings: trim (core budget guard) + compress (plugin) -->
+      <div class="grid grid-cols-3 gap-3 mt-3">
+        <div class="rounded-md bg-slate-800/50 p-3">
+          <div class="text-xs text-slate-400">Tokens saved &middot; trim</div>
+          <div class="text-2xl font-semibold tabnum text-sky-400" data-bind="tokens_saved_trim">0</div>
+        </div>
+        <div class="rounded-md bg-slate-800/50 p-3">
+          <div class="text-xs text-slate-400">Tokens saved &middot; compress</div>
+          <div class="text-2xl font-semibold tabnum text-sky-400" data-bind="tokens_saved_compress">0</div>
+        </div>
+        <div class="rounded-md bg-slate-800/50 p-3">
+          <div class="text-xs text-slate-400">Tokens saved &middot; total</div>
+          <div class="text-2xl font-semibold tabnum text-green-400" data-bind="tokens_saved_total">0</div>
+        </div>
+      </div>
     </section>
     <section class="bg-slate-900/60 border border-slate-800 rounded-lg p-4">
       <h2 class="text-sm font-semibold uppercase tracking-wider text-slate-400 mb-3">Usage Mix</h2>
@@ -474,6 +489,14 @@ _DASHBOARD_HTML = r"""<!doctype html>
       rows.map(([n, v]) =>
         '<span class="mr-4"><span class="text-slate-500">' + escapeHTML(n) +
         '</span> ' + usd(v) + '</span>').join("");
+    // token-savings tiles. trim comes from the core budget guard;
+    // compress from the optional plugin. Collector zero-fills, so an
+    // install with neither still renders "0" cleanly.
+    const ts = c.tokens_saved_by_mechanism || {};
+    const intfmt = (x) => (Number(x) || 0).toLocaleString();
+    setBind("tokens_saved_trim", intfmt(ts.trim));
+    setBind("tokens_saved_compress", intfmt(ts.compress));
+    setBind("tokens_saved_total", intfmt(c.tokens_saved_total));
   };
 
   const renderSnapshot = (snap) => {

{coderouter_cli-2.6.0 → coderouter_cli-2.6.1}/coderouter/metrics/collector.py

@@ -197,6 +197,16 @@ class MetricsCollector(logging.Handler):
         self._language_tax_usd: dict[str, float] = {}
         self._language_tax_usd_aggregate: float = 0.0
 
+        # token-savings accounting. Tokens that never reached the backend
+        # because a reduction mechanism shrank or dropped them. Two
+        # mechanisms feed this: ``trim`` (core context-budget guard, derived
+        # from the existing ``context-budget-trimmed`` event) and
+        # ``compress`` (the optional compress plugin, via the neutral
+        # ``tokens-saved`` event). Owned by core so the figure exists even
+        # when no plugin is installed.
+        self._tokens_saved_total: int = 0
+        self._tokens_saved_by_mechanism: Counter[str] = Counter()
+
         # v2.0-F (L1): context budget guard counters. Per-profile counts
         # of warnings (over warn threshold) and trims (messages removed).
         # The ``latest_usage_ratio`` dict records the most recent ratio
@@ -425,6 +435,41 @@ class MetricsCollector(logging.Handler):
                 profile = _str(extras.get("profile"))
                 self._context_budget_trims_total += 1
                 self._context_budget_trims_by_profile[profile] += 1
+                # token-savings: the trim already carries the estimated
+                # before/after token counts, so fold the delta into the
+                # shared savings buckets (mechanism="trim").
+                before = extras.get("estimated_tokens_before")
+                after = extras.get("estimated_tokens_after")
+                if isinstance(before, int | float) and isinstance(
+                    after, int | float
+                ):
+                    saved = max(0, int(before) - int(after))
+                    if saved:
+                        self._tokens_saved_total += saved
+                        self._tokens_saved_by_mechanism["trim"] += saved
+            elif event == "tokens-saved":
+                # Neutral token-savings event emitted by non-core reduction
+                # mechanisms (e.g. the compress plugin). Carries a
+                # ``mechanism`` label plus either a precomputed
+                # ``tokens_saved`` or a ``tokens_before`` / ``tokens_after``
+                # pair. Negative deltas clamp to zero. No core import needed
+                # by the emitter — it just logs this record name.
+                mechanism = _str(extras.get("mechanism")) or "unknown"
+                saved_raw = extras.get("tokens_saved")
+                before = extras.get("tokens_before")
+                after = extras.get("tokens_after")
+                if isinstance(saved_raw, int | float):
+                    saved = max(0, int(saved_raw))
+                elif isinstance(before, int | float) and isinstance(
+                    after, int | float
+                ):
+                    saved = max(0, int(before) - int(after))
+                else:
+                    saved = 0
+                if saved:
+                    self._tokens_saved_total += saved
+                    self._tokens_saved_by_mechanism[mechanism] += saved
+                self._push_recent(event, extras, record)
             elif event == "drift-detected":
                 # v2.0-G (L4): drift detection fired.
                 provider = _str(extras.get("provider"))
@@ -624,6 +669,11 @@ class MetricsCollector(logging.Handler):
                     "language_tax_usd_aggregate": round(
                         self._language_tax_usd_aggregate, 6
                     ),
+                    # token-savings: total + per-mechanism (trim / compress).
+                    "tokens_saved_total": self._tokens_saved_total,
+                    "tokens_saved_by_mechanism": dict(
+                        self._tokens_saved_by_mechanism
+                    ),
                     # v2.0-F (L1): context budget guard aggregate counters.
                     "context_budget_warnings_total": self._context_budget_warnings_total,
                     "context_budget_trims_total": self._context_budget_trims_total,
@@ -684,6 +734,10 @@ class MetricsCollector(logging.Handler):
                 "chain_budget_exceeded_total": self._chain_budget_exceeded_total,
                 "chain_memory_pressure_blocked_total": self._chain_memory_pressure_blocked_total,
                 "chain_uniform_auth_failure_total": self._chain_uniform_auth_failure_total,
+                "tokens_saved_total": self._tokens_saved_total,
+                "tokens_saved_by_mechanism": dict(
+                    self._tokens_saved_by_mechanism
+                ),
                 "probe_rounds_total": self._probe_rounds_total,
             }
 
@@ -724,6 +778,9 @@ class MetricsCollector(logging.Handler):
             self._language_tax_usd_aggregate += float(
                 state.get("language_tax_usd_aggregate", 0.0)
             )
+            self._tokens_saved_total += int(state.get("tokens_saved_total", 0))
+            for k, v in (state.get("tokens_saved_by_mechanism") or {}).items():
+                self._tokens_saved_by_mechanism[k] += int(v)
             self._chain_paid_gate_blocked_total += int(
                 state.get("chain_paid_gate_blocked_total", 0)
             )
@@ -782,6 +839,9 @@ class MetricsCollector(logging.Handler):
             # v2.6
             self._language_tax_usd.clear()
             self._language_tax_usd_aggregate = 0.0
+            # token-savings
+            self._tokens_saved_total = 0
+            self._tokens_saved_by_mechanism.clear()
             # v2.0-H (L6)
             self._partial_stitch_surfaced_total = 0
             # v2.0-I

{coderouter_cli-2.6.0 → coderouter_cli-2.6.1}/docs/README.md

@@ -16,10 +16,12 @@ Index of CodeRouter's public documentation — find the right page by what you w
 | 自分に必要か知りたい / Is it for me? | [start/when-do-i-need-coderouter](start/when-do-i-need-coderouter.md) |
 | 無料で運用したい / Run for free | [guides/free-tier-guide](guides/free-tier-guide.md) |
 | 機能を一通り知りたい / Learn the features | [guides/usage-guide](guides/usage-guide.md) |
+| 言語税を計測・回避したい / Measure & avoid the language tax | [guides/language-tax](guides/language-tax.md) |
 | エラーで詰まった / Something broke | [guides/troubleshooting](guides/troubleshooting.md) |
 | ローカル LLM を起動したい / Launch a local LLM | [backends/launcher-quickstart](backends/launcher-quickstart.md) |
 | APIキー・機密の扱い / Secrets & security | [guides/security](guides/security.md) |
 | 仕組みを理解したい / Understand the design | [concepts/architecture](concepts/architecture.md) |
+| プラグインで拡張したい / Extend with plugins | [対応プラグイン / Plugins](#対応プラグイン--plugins) |
 
 ---
 
@@ -55,6 +57,7 @@ Many documents have a Japanese version (`.md`) and an English version (`.en.md`)
 日常的に使いこなすためのガイド。 / Day-to-day usage.
 
 - **usage-guide** — 機能を一通り使いこなす / Full feature guide · [日本語](guides/usage-guide.md) · [English](guides/usage-guide.en.md)
+- **language-tax** — 日本語の言語税を計測・ルーティング回避・可視化 / Measure, route around, and visualize the CJK language tax · [日本語](guides/language-tax.md) · [English](guides/language-tax.en.md)
 - **free-tier-guide** — NVIDIA NIM × OpenRouter Free でコストゼロ運用 / Zero-cost operation · [日本語](guides/free-tier-guide.md) · [English](guides/free-tier-guide.en.md)
 - **troubleshooting** — つまずいたときの解決集 / Fixing problems · [日本語](guides/troubleshooting.md) · [English](guides/troubleshooting.en.md)
 - **security** — シークレット管理とセキュリティ方針 / Secrets handling & security posture · [日本語](guides/security.md) · [English](guides/security.en.md)
@@ -91,4 +94,38 @@ CodeRouter の仕組みと信頼性機構。 / How CodeRouter works and its reli
 
 ---
 
-最終更新 / Last updated: 2026-05-22
+## 対応プラグイン / Plugins
+
+CodeRouter は v2.3.0 で入った **Plugin SDK** により、別パッケージのプラグインを *opt-in* で読み込めます。`plugins.enabled` に名前を明示したときだけ作動する（サプライチェーン防御）ため、インストールしただけでは何も起きません。各プラグインは独立した PyPI パッケージなので、**コアの依存は一切増えません**。
+
+CodeRouter's **Plugin SDK** (since v2.3.0) loads out-of-tree plugins *opt-in*: a plugin runs only when its name is listed in `plugins.enabled` (supply-chain defense), so installing one does nothing by itself. Each plugin ships as a separate PyPI package, so **the core's dependencies never grow**.
+
+| プラグイン / Plugin | 何をするか / What it does | インストール / Install | リポジトリ / Repo |
+|---|---|---|---|
+| **compress** | ツール出力（JSON / ログ）を LLM に届く前に圧縮してトークンを削減。原文はローカル保持で可逆（CCR）。`cache-align` で Anthropic プロンプトキャッシュも整列。<br>Compresses tool output (JSON / logs) before it reaches the LLM to cut tokens; originals kept locally and reversible (CCR). `cache-align` also aligns Anthropic prompt caching. | `pip install coderouter-plugin-compress` | [coderouter-plugin-compress](https://github.com/zephel01/coderouter-plugin-compress) |
+| **memory** | 応答から key facts を抽出して `facts.jsonl` に蓄積し、次セッションの system prompt へ自動注入。「毎回同じ説明」を wire 層で解消。<br>Extracts key facts from responses into `facts.jsonl` and auto-injects them into the next session's system prompt — solving "explain it every time" at the wire layer. | `pip install coderouter-plugin-memory` | [coderouter-plugin-memory](https://github.com/zephel01/coderouter-plugin-memory) |
+
+有効化は `providers.yaml` に追記するだけ。起動ログに `plugin-loaded` が出れば有効です。
+Enable by adding to `providers.yaml`; a `plugin-loaded` line in the startup log confirms activation.
+
+```yaml
+plugins:
+  enabled:
+    - compress          # ツール出力を圧縮 / compress tool output
+    - compress-stats    # 圧縮率を coderouter stats に出力 / report compression ratio
+    - cache-align       # プロンプトキャッシュのブレークポイント整列 / align prompt-cache breakpoints
+    - memory            # セッション横断メモリ / cross-session memory
+  config:
+    compress:
+      mode: safe        # off | safe | aggressive
+      ccr: true         # 圧縮の可逆復元（既定 on）/ reversible re-expansion (default on)
+    memory:
+      consolidate_model: qwen3:1.7b
+```
+
+各プラグインの詳細・設定は上記リポジトリの README を参照してください。
+See each plugin's repo README for full configuration.
+
+---
+
+最終更新 / Last updated: 2026-06-24

coderouter_cli-2.6.1/docs/backends/claude-code-llamacpp-vllm.md

@@ -0,0 +1,172 @@
+# Claude Code × ローカル LLM(llama.cpp / vLLM)接続ガイド — Ollama なしの設定とトラブルシュート
+
+Ollama を使わず、**ダウンロード済みの `.gguf` を llama.cpp で**、または **vLLM で** 動かし、CodeRouter 経由で Claude Code に繋ぐための実践ガイドです。
+構成の作り方と、実際に踏みやすいエラー（400 / 接続拒否 / 502 / コネクタ無効化 / `n_ctx=4096` のまま）の直し方をまとめています。
+
+> 関連: [Launcher ガイド](./launcher.md) / [バックエンド インストール手順書](./install-backends.md) / [examples/README](../../examples/README.md)
+
+---
+
+## 全体構成
+
+```
+Claude Code ──(ANTHROPIC_BASE_URL)──► CodeRouter (:8088) ──► ① llama.cpp (:8080)
+                                                          ├─► ② vLLM (:8000)
+                                                          └─► ③ 無料クラウド (fallback)
+```
+
+CodeRouter が求めるのは「OpenAI 互換 API を話すバックエンド」だけです。Ollama はその選択肢の 1 つにすぎず、llama.cpp / vLLM でも等価に使えます。
+
+---
+
+## セットアップ手順
+
+### 1. バックエンドを起動する（Ollama なし）
+
+**llama.cpp（ダウンロード済み GGUF を使う）**
+
+```bash
+brew install llama.cpp           # macOS / Linux（Windows: winget install ggml.llamacpp）
+
+llama-server -m ~/models/<model>.gguf --host 127.0.0.1 --port 8080 \
+  -ngl 99 --ctx-size 32768
+# 起動ログの「n_ctx = 32768」を必ず確認する
+```
+
+**vLLM（NVIDIA GPU）**
+
+```bash
+uv venv ~/.coderouter/backends/vllm
+~/.coderouter/backends/vllm/bin/python -m pip install vllm
+~/.coderouter/backends/vllm/bin/python -m vllm.entrypoints.openai.api_server \
+  --model Qwen/Qwen2.5-Coder-7B-Instruct --port 8000 --max-model-len 32768
+```
+
+> 起動を GUI に任せたい場合は [Launcher](./launcher.md)。ただし Launcher が面倒を見るのは**起動まで**で、下記の provider 登録は別作業です。
+
+### 2. CodeRouter に provider として登録する（`~/.coderouter/providers.yaml`）
+
+```yaml
+allow_paid: false
+default_profile: default
+
+providers:
+  - name: llama-cpp-local
+    kind: openai_compat
+    base_url: http://localhost:8080/v1     # ← 起動したポートと一致させる
+    model: ""                              # llama-server は model 名を問わない
+    timeout_s: 120
+
+  - name: vllm-local
+    kind: openai_compat
+    base_url: http://localhost:8000/v1     # ← vLLM の既定は 8000
+    model: Qwen/Qwen2.5-Coder-7B-Instruct
+    timeout_s: 120
+
+  - name: openrouter-free                  # 逃げ先（任意だが推奨）
+    kind: openai_compat
+    base_url: https://openrouter.ai/api/v1
+    model: qwen/qwen3-coder:free
+    api_key_env: OPENROUTER_API_KEY
+
+profiles:
+  - name: default
+    providers: [llama-cpp-local, vllm-local, openrouter-free]
+```
+
+`examples/providers.llamacpp-vllm.yaml` をコピーして始めると速いです。
+
+### 3. CodeRouter を起動して Claude Code を繋ぐ
+
+```bash
+# ターミナル1
+coderouter serve --port 8088
+
+# ターミナル2（このシェルだけに env を効かせる。グローバルに置かない）
+ANTHROPIC_BASE_URL=http://localhost:8088 ANTHROPIC_AUTH_TOKEN=dummy claude
+```
+
+`ANTHROPIC_AUTH_TOKEN` はダミーで可（CodeRouter は検証しない）。実 API キーは `providers.yaml` 側で管理します。
+
+---
+
+## 設定の 4 つの要点
+
+### ① ポートを一致させる
+
+`base_url` のポートは起動した推論サーバーと一字一句一致させること。ズレると `transport error: All connection attempts failed`（接続拒否）になります。
+
+| バックエンド | 既定ポート | 確認 |
+|---|---|---|
+| llama.cpp | `8080` | `curl localhost:8080/health` |
+| vLLM | `8000` | `curl localhost:8000/v1/models` |
+| Ollama | `11434` | `curl localhost:11434/api/version` |
+
+### ② context size を Claude Code 用に上げる
+
+Claude Code は毎ターン **15〜35K tokens** を送ります。`--ctx-size` / `--max-model-len` が小さいと
+`exceed_context_size_error (400)` になります。**32768 以上**を既定に。
+モデルの学習時 context を超える場合は YaRN 等の rope 拡張を使います。
+
+```bash
+llama-server -m <model>.gguf --port 8080 -ngl 99 \
+  --ctx-size 65536 --rope-scaling yarn --yarn-orig-ctx 32768
+```
+
+大きい ctx で OOM する場合は、ctx を下げる / KV 量子化（`--cache-type-k q8_0 --cache-type-v q8_0`）/ 小さいモデルへ。
+
+### ③ チェーン末尾に「効くフォールバック」を置く
+
+`providers:` がローカルだけだと、落ちた瞬間に逃げ先が無く **502** になります。末尾に無料クラウドを 1 本足すと、ローカルが落ちても・context が載らなくても Claude Code が止まりません。有料は `ALLOW_PAID=true` を立てない限り呼ばれません（既定 `allow_paid: false`）。
+
+### ④ 編集の反映は 3 ステップ
+
+動いているプロセスには即時反映されません。
+
+1. 設定を **`~/.coderouter/providers.yaml`** に置く（`examples/` を直すだけでは効かない）
+2. **`coderouter serve` を再起動**（`launcher:` / プロファイルは起動時に読まれる）
+3. **バックエンドを起動し直す**（`--ctx-size` 等は再起動して初めて効く）
+
+---
+
+## トラブルシュート早見表
+
+| 症状 / ログ | 原因 | 対処 |
+|---|---|---|
+| `400 exceed_context_size_error` `n_ctx:4096` | ctx-size が小さく Claude Code の prompt が入らない | `--ctx-size 32768` 以上で**起動し直す**。学習 ctx 超は YaRN |
+| `transport error: All connection attempts failed` (status: null) | バックエンドが落ちている / **ポート不一致** | サーバを起動 + `base_url` のポートを実ポートに合わせる |
+| すべて `provider-failed` → **502 Bad Gateway** | チェーンの逃げ先が全滅 | バックエンドを 1 つ復旧 + 末尾に無料クラウド fallback |
+| 起動し直しても `n_ctx=4096` のまま | 旧プロセスが残存 / 設定が `~/.coderouter` に未反映 / serve 未再起動 | `ps aux \| grep llama-server` で実コマンド確認 → 反映3ステップ |
+| OOM でバックエンドが即落ち | ctx を上げすぎ | ctx を下げる / KV 量子化 / 小さいモデル |
+| `capability-degraded: cache_control` | OpenAI 形式へ翻訳時に Anthropic prompt-cache マーカーを落とすだけ | **無害**。対処不要 |
+| `claude.ai connectors are disabled …` | env の `ANTHROPIC_AUTH_TOKEN`/`API_KEY` が claude.ai ログインより優先 | CodeRouter 用 env はそのシェル/フォルダ限定に（`direnv`）。普段使いシェルでは `unset` |
+| `/mcp` に `✘ failed` が残る | 不要な MCP サーバ登録 | `claude mcp remove <name> -s user` |
+
+### 切り分けコマンド
+
+```bash
+# バックエンドが生きているか
+curl -s localhost:8080/health ; echo            # llama.cpp
+curl -s localhost:8000/v1/models ; echo         # vLLM
+ps aux | grep -E '[l]lama-server|[v]llm'
+
+# CodeRouter 側の状態
+open http://localhost:8088/dashboard            # 誰が落ちているか色で分かる
+coderouter doctor --check-model llama-cpp-local # provider を 6 プローブで診断
+```
+
+---
+
+## 3 つのバックエンド早見
+
+| | 何が要るか | モデル形式 | 起動の単位 |
+|---|---|---|---|
+| Ollama | `ollama pull` | Ollama 管理 | デーモン 1 つが on-demand |
+| **llama.cpp** | `.gguf` + `llama-server` | `.gguf`（手元のファイル） | **1 起動 = 1 モデル = 1 ポート** |
+| **vLLM** | NVIDIA GPU + venv | HF ID / ローカルパス | 1 起動 = 1 モデル = 1 ポート |
+
+llama.cpp / vLLM は「起動したモデルだけ」が使えます（Ollama のように 1 つの口で複数モデルを出し分けることはしません）。複数使うならポートを分けてそれぞれ provider 登録します。
+
+---
+
+最終更新: 2026-06-24