tokensaver-cli 0.1.0__tar.gz

tokensaver_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) TokenSaver
+
+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.

tokensaver_cli-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: tokensaver-cli
+Version: 0.1.0
+Summary: TokenSaver CLI — route AI agents (Claude Code, Cursor, Codex) through the SaaS control plane
+Author: TokenSaver
+License-Expression: MIT
+Project-URL: Homepage, https://platform.tokensaver.fr
+Project-URL: Documentation, https://tokensaver.fr/sdk-api
+Project-URL: PyPI, https://pypi.org/project/tokensaver-cli/
+Keywords: tokensaver,llm,cli,claude,cursor,mcp,agents
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Dynamic: license-file
+
+# TokenSaver CLI (`tokensaver-cli`)
+
+Console command **`tokensaver`** to route AI agents through the **TokenSaver SaaS control plane** (`api.tokensaver.fr`) — cache, compression, PII, MCP gateway, observability.
+
+Companion package to **[`tokensaver-sdk`](https://pypi.org/project/tokensaver-sdk/)** (Python API client). The CLI configures your **local machine**; the pipeline runs on TokenSaver servers.
+
+**Get started:** sign up at [platform.tokensaver.fr](https://platform.tokensaver.fr), create a **`ts_…`** API key, then:
+
+```bash
+pip install tokensaver-cli
+export TOKENSAVER_API_KEY=ts_your_key
+tokensaver route claude --launch
+tokensaver doctor
+```
+
+## Installation
+
+```bash
+pip install tokensaver-cli
+```
+
+Development inside the monorepo:
+
+```bash
+cd packages/cli
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+**Requirements:** Python ≥ 3.10, no extra runtime dependencies (stdlib only).
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `tokensaver route claude` | Configure Claude Code (`~/.claude/settings.json` + `.mcp.json`) |
+| `tokensaver route claude --launch` | Configure + start `claude` |
+| `tokensaver route cursor` | Write `.cursor/mcp.json` + print Override URL steps |
+| `tokensaver route codex` | Print OpenAI-compat env vars for Codex |
+| `tokensaver route proxy` | Show base URLs for LangChain / OpenAI SDK / your code |
+| `tokensaver unroute <target>` | Restore backed-up config |
+| `tokensaver doctor` | Check API key and SaaS endpoint reachability |
+
+## SaaS defaults (no local server)
+
+| Surface | URL |
+|---------|-----|
+| API | `https://api.tokensaver.fr` |
+| OpenAI-compat | `https://api.tokensaver.fr/openai/v1` |
+| Anthropic-compat | `https://api.tokensaver.fr/anthropic` |
+| MCP tools | `https://mcp.tokensaver.fr/mcp` |
+| MCP gateway | `https://gateway.tokensaver.fr/mcp` |
+
+Override with `TOKENSAVER_API_URL`, `TOKENSAVER_MCP_URL`, etc. if you use a private deployment.
+
+## Environment
+
+```bash
+export TOKENSAVER_API_KEY=ts_…   # required
+# optional scope for MCP gateway headers:
+export X-Organisation-ID=…
+export X-Workspace-ID=…
+```
+
+## Related packages
+
+| PyPI package | Role |
+|--------------|------|
+| **`tokensaver-cli`** | This package — `tokensaver route` / `doctor` |
+| **`tokensaver-sdk`** | Python API client — `TokenSaver(api_key=…).ask(…)` |
+
+API reference (public): [tokensaver.fr/sdk-api](https://tokensaver.fr/sdk-api)
+
+## Tests
+
+```bash
+cd packages/cli && pip install -e ".[dev]" && pytest -q
+```
+
+## Publishing to PyPI
+
+Maintainers: see **[`docs/PYPI-CLI-RELEASE.md`](../../docs/PYPI-CLI-RELEASE.md)**.
+
+Tag format: **`cli-vX.Y.Z`** (version in `src/tokensaver_cli/__init__.py`).

tokensaver_cli-0.1.0/README.md

@@ -0,0 +1,84 @@
+# TokenSaver CLI (`tokensaver-cli`)
+
+Console command **`tokensaver`** to route AI agents through the **TokenSaver SaaS control plane** (`api.tokensaver.fr`) — cache, compression, PII, MCP gateway, observability.
+
+Companion package to **[`tokensaver-sdk`](https://pypi.org/project/tokensaver-sdk/)** (Python API client). The CLI configures your **local machine**; the pipeline runs on TokenSaver servers.
+
+**Get started:** sign up at [platform.tokensaver.fr](https://platform.tokensaver.fr), create a **`ts_…`** API key, then:
+
+```bash
+pip install tokensaver-cli
+export TOKENSAVER_API_KEY=ts_your_key
+tokensaver route claude --launch
+tokensaver doctor
+```
+
+## Installation
+
+```bash
+pip install tokensaver-cli
+```
+
+Development inside the monorepo:
+
+```bash
+cd packages/cli
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+**Requirements:** Python ≥ 3.10, no extra runtime dependencies (stdlib only).
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `tokensaver route claude` | Configure Claude Code (`~/.claude/settings.json` + `.mcp.json`) |
+| `tokensaver route claude --launch` | Configure + start `claude` |
+| `tokensaver route cursor` | Write `.cursor/mcp.json` + print Override URL steps |
+| `tokensaver route codex` | Print OpenAI-compat env vars for Codex |
+| `tokensaver route proxy` | Show base URLs for LangChain / OpenAI SDK / your code |
+| `tokensaver unroute <target>` | Restore backed-up config |
+| `tokensaver doctor` | Check API key and SaaS endpoint reachability |
+
+## SaaS defaults (no local server)
+
+| Surface | URL |
+|---------|-----|
+| API | `https://api.tokensaver.fr` |
+| OpenAI-compat | `https://api.tokensaver.fr/openai/v1` |
+| Anthropic-compat | `https://api.tokensaver.fr/anthropic` |
+| MCP tools | `https://mcp.tokensaver.fr/mcp` |
+| MCP gateway | `https://gateway.tokensaver.fr/mcp` |
+
+Override with `TOKENSAVER_API_URL`, `TOKENSAVER_MCP_URL`, etc. if you use a private deployment.
+
+## Environment
+
+```bash
+export TOKENSAVER_API_KEY=ts_…   # required
+# optional scope for MCP gateway headers:
+export X-Organisation-ID=…
+export X-Workspace-ID=…
+```
+
+## Related packages
+
+| PyPI package | Role |
+|--------------|------|
+| **`tokensaver-cli`** | This package — `tokensaver route` / `doctor` |
+| **`tokensaver-sdk`** | Python API client — `TokenSaver(api_key=…).ask(…)` |
+
+API reference (public): [tokensaver.fr/sdk-api](https://tokensaver.fr/sdk-api)
+
+## Tests
+
+```bash
+cd packages/cli && pip install -e ".[dev]" && pytest -q
+```
+
+## Publishing to PyPI
+
+Maintainers: see **[`docs/PYPI-CLI-RELEASE.md`](../../docs/PYPI-CLI-RELEASE.md)**.
+
+Tag format: **`cli-vX.Y.Z`** (version in `src/tokensaver_cli/__init__.py`).

tokensaver_cli-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tokensaver-cli"
+dynamic = ["version"]
+description = "TokenSaver CLI — route AI agents (Claude Code, Cursor, Codex) through the SaaS control plane"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "TokenSaver" }]
+keywords = ["tokensaver", "llm", "cli", "claude", "cursor", "mcp", "agents"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Environment :: Console",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = []
+
+[project.scripts]
+tokensaver = "tokensaver_cli.main:main"
+
+[project.optional-dependencies]
+dev = [
+    "build>=1.0.0",
+    "pytest>=7.4.0",
+    "ruff>=0.1.0",
+    "twine>=5.0.0",
+]
+
+[project.urls]
+Homepage = "https://platform.tokensaver.fr"
+Documentation = "https://tokensaver.fr/sdk-api"
+PyPI = "https://pypi.org/project/tokensaver-cli/"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.dynamic]
+version = { attr = "tokensaver_cli.__version__" }
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]

tokensaver_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tokensaver_cli-0.1.0/src/tokensaver_cli/__init__.py

@@ -0,0 +1,8 @@
+"""
+TokenSaver CLI — route agent traffic through the TokenSaver SaaS control plane.
+
+Published on PyPI as ``tokensaver-cli``; installs the ``tokensaver`` console command.
+No server-side pipeline code — configures local agents to call api.tokensaver.fr.
+"""
+
+__version__ = "0.1.0"

tokensaver_cli-0.1.0/src/tokensaver_cli/agents.py

@@ -0,0 +1,257 @@
+"""Route / unroute handlers per agent or integration mode."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from tokensaver_cli.config import MCP_GATEWAY_KEY, MCP_TOOLS_KEY, RouteConfig
+from tokensaver_cli.json_merge import deep_merge, read_json, write_json
+from tokensaver_cli.state import RoutedFile, backup_file, clear_route, load_state, record_route, restore_file
+
+
+def _begin_route_files(target: str, paths: list[Path]) -> list[RoutedFile]:
+    """Backup config files once per target; preserve originals on re-route."""
+    existing = load_state().get(target)
+    if existing and existing.files:
+        return existing.files
+    routed: list[RoutedFile] = []
+    for path in paths:
+        backup = backup_file(path) if path.is_file() else None
+        routed.append(RoutedFile(path=str(path), backup=backup or ""))
+    return routed
+
+
+def _mcp_tools_entry(cfg: RouteConfig) -> dict:
+    return {
+        "type": "http",
+        "url": cfg.mcp_tools_url,
+        "headers": {"Authorization": f"Bearer {cfg.api_key}"},
+    }
+
+
+def _mcp_gateway_entry(cfg: RouteConfig, client: str) -> dict:
+    headers: dict[str, str] = {
+        "Authorization": f"Bearer {cfg.api_key}",
+        "X-Tokensaver-Client": client,
+    }
+    if cfg.organisation_id:
+        headers["X-Organisation-ID"] = cfg.organisation_id
+    if cfg.workspace_id:
+        headers["X-Workspace-ID"] = cfg.workspace_id
+    return {
+        "type": "http",
+        "url": cfg.gateway_url,
+        "headers": headers,
+    }
+
+
+def _restore_routed_files(files: list[RoutedFile]) -> None:
+    for item in files:
+        path = Path(item.path)
+        if not item.backup:
+            path.unlink(missing_ok=True)
+            continue
+        restore_file(path, item.backup)
+
+
+def route_claude(cfg: RouteConfig, *, launch: bool, extra_args: list[str]) -> int:
+    settings_path = Path.home() / ".claude" / "settings.json"
+    mcp_path = Path.cwd() / ".mcp.json"
+    routed = _begin_route_files("claude", [settings_path, mcp_path])
+
+    settings = read_json(settings_path)
+    env_patch = {
+        "ANTHROPIC_BASE_URL": cfg.anthropic_base_url,
+        "ANTHROPIC_AUTH_TOKEN": cfg.api_key,
+        "ANTHROPIC_API_KEY": "",
+        "TOKENSAVER_API_KEY": cfg.api_key,
+    }
+    settings = deep_merge(settings, {"env": env_patch})
+    write_json(settings_path, settings)
+
+    data = read_json(mcp_path)
+    patch = {
+        "mcpServers": {
+            MCP_TOOLS_KEY: _mcp_tools_entry(cfg),
+            MCP_GATEWAY_KEY: _mcp_gateway_entry(cfg, "claude-code/1.0"),
+        }
+    }
+    write_json(mcp_path, deep_merge(data, patch))
+
+    record_route("claude", routed)
+    _print_routed("Claude Code", cfg, client="claude-code/1.0")
+
+    if launch or extra_args:
+        env = os.environ.copy()
+        env.update(env_patch)
+        return subprocess.call(["claude", *extra_args], env=env)
+    return 0
+
+
+def unroute_claude() -> int:
+    rec = clear_route("claude")
+    if not rec:
+        print("Claude Code is not routed through TokenSaver.", file=sys.stderr)
+        return 1
+    _restore_routed_files(rec.files)
+    print("Claude Code unrouted — original config restored.")
+    return 0
+
+
+def route_cursor(cfg: RouteConfig) -> int:
+    mcp_path = Path.cwd() / ".cursor" / "mcp.json"
+    routed = _begin_route_files("cursor", [mcp_path])
+
+    data = read_json(mcp_path)
+    patch = {
+        "mcpServers": {
+            MCP_TOOLS_KEY: _mcp_tools_entry(cfg),
+            MCP_GATEWAY_KEY: _mcp_gateway_entry(cfg, "cursor/1.0"),
+        }
+    }
+    mcp_path.parent.mkdir(parents=True, exist_ok=True)
+    write_json(mcp_path, deep_merge(data, patch))
+    record_route("cursor", routed)
+
+    print("Cursor routed through TokenSaver.")
+    print()
+    print("MCP config written:", mcp_path)
+    print()
+    print("Manual step — Cursor Settings → Models → Override OpenAI Base URL:")
+    print(f"  {cfg.openai_base_url}")
+    print()
+    print("Use a TokenSaver model id (e.g. openai/gpt-4o or anthropic/claude-sonnet-4-6).")
+    print("Restart Cursor → Settings → Tools & MCP → enable tokensaver-route-* servers.")
+    print()
+    print("Note: native Cursor Agent/Autocomplete may still bypass the override (~40% coverage).")
+    return 0
+
+
+def unroute_cursor() -> int:
+    rec = clear_route("cursor")
+    if not rec:
+        print("Cursor is not routed through TokenSaver.", file=sys.stderr)
+        return 1
+    _restore_routed_files(rec.files)
+    print("Cursor unrouted — .cursor/mcp.json restored.")
+    print("Remove Override OpenAI Base URL in Cursor Settings if you set it manually.")
+    return 0
+
+
+def route_codex(cfg: RouteConfig, *, launch: bool, extra_args: list[str]) -> int:
+    env_patch = {
+        "OPENAI_BASE_URL": cfg.openai_base_url,
+        "OPENAI_API_KEY": cfg.api_key,
+        "TOKENSAVER_API_KEY": cfg.api_key,
+    }
+    routed = [RoutedFile(path="__env__", backup="")]
+    record_route("codex", routed)
+    _print_routed("OpenAI Codex", cfg, client="codex/1.0", env_only=env_patch)
+
+    if launch or extra_args:
+        env = os.environ.copy()
+        env.update(env_patch)
+        return subprocess.call(["codex", *extra_args], env=env)
+    return 0
+
+
+def unroute_codex() -> int:
+    rec = clear_route("codex")
+    if not rec:
+        print("Codex is not routed through TokenSaver.", file=sys.stderr)
+        return 1
+    print("Codex unrouted.")
+    print("Unset OPENAI_BASE_URL and OPENAI_API_KEY if you exported them in your shell profile.")
+    return 0
+
+
+def route_proxy(cfg: RouteConfig) -> int:
+    record_route("proxy", [])
+    print("TokenSaver API proxy endpoints (OpenAI-compatible clients):")
+    print(f"  OpenAI base URL : {cfg.openai_base_url}")
+    print(f"  Anthropic base  : {cfg.anthropic_base_url}")
+    print(f"  API key         : Bearer {cfg.api_key[:8]}…")
+    print()
+    print("Point any OpenAI-compatible SDK (LangChain, Agno, LiteLLM, your code) at the base URL above.")
+    print()
+    print("Optional — capture all outbound HTTPS (advanced, self-hosted egress proxy):")
+    print("  export HTTPS_PROXY=http://127.0.0.1:8888")
+    print("  export TOKENSAVER_API_KEY=ts_…")
+    return 0
+
+
+def unroute_proxy() -> int:
+    if not clear_route("proxy"):
+        print("Proxy route state was not set.", file=sys.stderr)
+        return 1
+    print("Proxy route cleared. Unset HTTPS_PROXY if you configured egress capture.")
+    return 0
+
+
+def route_mcp(cfg: RouteConfig, *, target: str | None) -> int:
+    if not target:
+        print("MCP gateway (SaaS): gateway URL is already injected in .mcp.json by route claude/cursor.")
+        print()
+        print("Local stdio wrapper (advanced) requires tokensaver-mcp-gateway on PATH:")
+        print()
+        print("  tokensaver-mcp-gateway \\")
+        print('    --target "npx -y @modelcontextprotocol/server-filesystem /path/to/project" \\')
+        print('    --workspace "dev-local"')
+        print()
+        print("Environment:")
+        print(f"  TOKENSAVER_API_KEY={cfg.api_key[:8]}…")
+        print(f"  TOKENSAVER_API_BASE_URL={cfg.api_v1_base}")
+        return 0
+
+    cmd = [
+        "tokensaver-mcp-gateway",
+        "--target",
+        target,
+        "--workspace",
+        cfg.workspace_id or "route-cli",
+    ]
+    env = os.environ.copy()
+    env.setdefault("TOKENSAVER_API_KEY", cfg.api_key)
+    env.setdefault("TOKENSAVER_API_BASE_URL", cfg.api_v1_base)
+    record_route("mcp", [])
+    print("Starting MCP Trust Gateway:", " ".join(cmd))
+    return subprocess.call(cmd, env=env)
+
+
+def unroute_mcp() -> int:
+    if not clear_route("mcp"):
+        print("MCP route state was not set.", file=sys.stderr)
+        return 1
+    print("MCP route cleared. Stop any running tokensaver-mcp-gateway process manually.")
+    return 0
+
+
+def _print_routed(
+    label: str,
+    cfg: RouteConfig,
+    *,
+    client: str,
+    env_only: dict[str, str] | None = None,
+) -> None:
+    print(f"{label} routed through TokenSaver.")
+    print()
+    print("  Control plane:")
+    print(f"    LLM (Anthropic) : {cfg.anthropic_base_url}")
+    print(f"    LLM (OpenAI)    : {cfg.openai_base_url}")
+    print(f"    MCP tools       : {cfg.mcp_tools_url}")
+    print(f"    MCP gateway     : {cfg.gateway_url}")
+    print(f"    Client tag      : {client}")
+    if env_only:
+        print()
+        print("  Export in your shell (or use --launch):")
+        for key, value in env_only.items():
+            if key == "TOKENSAVER_API_KEY":
+                print(f"    export {key}={value[:8]}…")
+            else:
+                print(f"    export {key}={value}")
+    print()
+    print("  Undo: tokensaver unroute", label.split()[0].lower())
+    print("  Check: tokensaver doctor")

tokensaver_cli-0.1.0/src/tokensaver_cli/banner.py

@@ -0,0 +1,36 @@
+"""Retro ASCII banner shown when the ``tokensaver`` command starts."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from tokensaver_cli import __version__
+
+_BANNER = r"""
+  ████████╗ ██████╗ ██╗  ██╗███████╗███╗   ██╗███████╗ █████╗ ██╗   ██╗███████╗██████╗
+  ╚══██╔══╝██╔═══██╗██║  ██║██╔════╝████╗  ██║██╔════╝██╔══██╗██║   ██║██╔════╝██╔══██╗
+     ██║   ██║   ██║███████║█████╗  ██╔██╗ ██║███████╗███████║██║   ██║█████╗  ██████╔╝
+     ██║   ██║   ██║██╔══██║██╔══╝  ██║╚██╗██║╚════██║██╔══██║╚██╗ ██╔╝██╔══╝  ██╔══██╗
+     ██║   ╚██████╔╝██║  ██║███████╗██║ ╚████║███████║██║  ██║ ╚████╔╝ ███████╗██║  ██║
+     ╚═╝    ╚═════╝ ╚═╝  ╚═╝╚══════╝╚═╝  ╚═══╝╚══════╝╚═╝  ╚═╝  ╚═══╝  ╚══════╝╚═╝  ╚═╝
+
+        ┌─────────────────────────────────────────────────────────────┐
+        │  CONTROL PLANE  ·  route  ·  compress  ·  govern  ·  save   │
+        │  Claude Code · Cursor · Codex · LangChain · your code       │
+        └─────────────────────────────────────────────────────────────┘
+"""
+
+
+def banner_enabled() -> bool:
+    flag = (os.environ.get("TOKENSAVER_NO_BANNER") or "").strip().lower()
+    return flag not in ("1", "true", "yes", "on")
+
+
+def print_banner(*, file=None) -> None:
+    if not banner_enabled():
+        return
+    out = file if file is not None else sys.stdout
+    print(_BANNER, file=out)
+    print(f"  TokenSaver CLI v{__version__}  —  https://platform.tokensaver.fr", file=out)
+    print(file=out)

tokensaver_cli-0.1.0/src/tokensaver_cli/config.py

@@ -0,0 +1,78 @@
+"""Resolved URLs and credentials for ``tokensaver route``."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+PROD_API_HOST = "https://api.tokensaver.fr"
+PROD_MCP_URL = "https://mcp.tokensaver.fr/mcp"
+PROD_GATEWAY_URL = "https://gateway.tokensaver.fr/mcp"
+
+MCP_TOOLS_KEY = "tokensaver-route-tools"
+MCP_GATEWAY_KEY = "tokensaver-route-gateway"
+
+
+def _strip_trailing_slash(url: str) -> str:
+    return url.rstrip("/")
+
+
+@dataclass(frozen=True)
+class RouteConfig:
+    api_key: str
+    api_host: str
+    anthropic_base_url: str
+    openai_base_url: str
+    mcp_tools_url: str
+    gateway_url: str
+    organisation_id: str | None
+    workspace_id: str | None
+
+    @property
+    def api_v1_base(self) -> str:
+        host = _strip_trailing_slash(self.api_host)
+        if host.endswith("/api/v1"):
+            return host
+        return f"{host}/api/v1"
+
+
+def resolve_route_config() -> RouteConfig:
+    api_key = (os.environ.get("TOKENSAVER_API_KEY") or "").strip()
+    if not api_key:
+        raise RouteConfigError(
+            "TOKENSAVER_API_KEY is required. "
+            "Create a key at https://platform.tokensaver.fr → Paramètres → TokenSaver API keys."
+        )
+
+    api_host = _strip_trailing_slash(
+        os.environ.get("TOKENSAVER_API_URL") or os.environ.get("TOKENSAVER_API_BASE_URL") or PROD_API_HOST
+    )
+    if api_host.endswith("/api/v1"):
+        api_host = api_host[: -len("/api/v1")]
+
+    anthropic_base = _strip_trailing_slash(
+        os.environ.get("TOKENSAVER_ANTHROPIC_BASE_URL") or f"{api_host}/anthropic"
+    )
+    openai_base = _strip_trailing_slash(
+        os.environ.get("TOKENSAVER_OPENAI_BASE_URL") or f"{api_host}/openai/v1"
+    )
+    mcp_url = os.environ.get("TOKENSAVER_MCP_URL") or PROD_MCP_URL
+    gateway_url = os.environ.get("TOKENSAVER_GATEWAY_URL") or PROD_GATEWAY_URL
+
+    org_id = (os.environ.get("X-Organisation-ID") or os.environ.get("X-Team-ID") or "").strip() or None
+    workspace_id = (os.environ.get("X-Workspace-ID") or "").strip() or None
+
+    return RouteConfig(
+        api_key=api_key,
+        api_host=api_host,
+        anthropic_base_url=anthropic_base,
+        openai_base_url=openai_base,
+        mcp_tools_url=mcp_url,
+        gateway_url=gateway_url,
+        organisation_id=org_id,
+        workspace_id=workspace_id,
+    )
+
+
+class RouteConfigError(Exception):
+    """Missing or invalid route configuration."""

tokensaver_cli-0.1.0/src/tokensaver_cli/doctor.py

@@ -0,0 +1,61 @@
+"""Health checks for routed integrations."""
+
+from __future__ import annotations
+
+import sys
+import urllib.error
+import urllib.request
+
+from tokensaver_cli.config import RouteConfigError, resolve_route_config
+from tokensaver_cli.state import load_state
+
+
+def _probe(url: str, headers: dict[str, str] | None = None) -> tuple[bool, str]:
+    req = urllib.request.Request(url, method="GET", headers=headers or {})
+    try:
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            return True, f"HTTP {resp.status}"
+    except urllib.error.HTTPError as exc:
+        if exc.code in (401, 405):
+            return True, f"HTTP {exc.code} (reachable, auth required)"
+        return False, f"HTTP {exc.code}"
+    except Exception as exc:  # noqa: BLE001 — doctor surfaces any transport error
+        return False, str(exc)
+
+
+def run_doctor() -> int:
+    try:
+        cfg = resolve_route_config()
+    except RouteConfigError as exc:
+        print(f"FAIL  config — {exc}", file=sys.stderr)
+        return 1
+
+    ok = True
+    print("TokenSaver route doctor")
+    print()
+
+    checks = [
+        ("API key", True, f"{cfg.api_key[:8]}… ({len(cfg.api_key)} chars)"),
+        ("OpenAI-compat", *_probe(f"{cfg.openai_base_url}/models", {"Authorization": f"Bearer {cfg.api_key}"})),
+        ("Anthropic-compat", *_probe(f"{cfg.anthropic_base_url}/v1/models", {"x-api-key": cfg.api_key})),
+        ("MCP tools", *_probe(cfg.mcp_tools_url, {"Authorization": f"Bearer {cfg.api_key}"})),
+        ("MCP gateway", *_probe(cfg.gateway_url, {"Authorization": f"Bearer {cfg.api_key}"})),
+    ]
+
+    for name, passed, detail in checks:
+        status = "OK" if passed else "FAIL"
+        print(f"  {status:4}  {name:16}  {detail}")
+        if not passed:
+            ok = False
+
+    routes = load_state()
+    if routes:
+        print()
+        print("  Active routes:")
+        for target, rec in sorted(routes.items()):
+            print(f"    - {target} (since {rec.routed_at})")
+    else:
+        print()
+        print("  No active routes. Run: tokensaver route claude")
+
+    return 0 if ok else 1

tokensaver_cli-0.1.0/src/tokensaver_cli/json_merge.py

@@ -0,0 +1,28 @@
+"""Small JSON helpers for merging agent config files."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+def read_json(path: Path) -> dict[str, Any]:
+    if not path.is_file():
+        return {}
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def write_json(path: Path, data: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+
+
+def deep_merge(base: dict[str, Any], patch: dict[str, Any]) -> dict[str, Any]:
+    out = dict(base)
+    for key, value in patch.items():
+        if key in out and isinstance(out[key], dict) and isinstance(value, dict):
+            out[key] = deep_merge(out[key], value)
+        else:
+            out[key] = value
+    return out

tokensaver_cli-0.1.0/src/tokensaver_cli/main.py

@@ -0,0 +1,150 @@
+"""CLI entrypoint: tokensaver route | unroute | doctor."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from tokensaver_cli.agents import (
+    route_claude,
+    route_codex,
+    route_cursor,
+    route_mcp,
+    route_proxy,
+    unroute_claude,
+    unroute_codex,
+    unroute_cursor,
+    unroute_mcp,
+    unroute_proxy,
+)
+from tokensaver_cli.banner import print_banner
+from tokensaver_cli.config import RouteConfigError, resolve_route_config
+from tokensaver_cli.doctor import run_doctor
+
+ROUTE_TARGETS = ("claude", "cursor", "codex", "proxy", "mcp")
+UNROUTE_TARGETS = ("claude", "cursor", "codex", "proxy", "mcp")
+
+DOCS_URL = "https://tokensaver.fr/sdk-api"
+
+
+def print_usage() -> None:
+    print(
+        f"""TokenSaver CLI — route agent traffic through the control plane
+
+Usage:
+  tokensaver route <target> [options] [-- extra-args...]
+  tokensaver unroute <target>
+  tokensaver doctor
+
+Targets:
+  claude    Claude Code — settings.json + .mcp.json (+ optional launch)
+  cursor    Cursor — writes .cursor/mcp.json + prints Override URL steps
+  codex     OpenAI Codex — prints env vars (+ optional launch)
+  proxy     Print OpenAI/Anthropic base URLs for any compatible client
+  mcp       MCP Trust Gateway — SaaS URL or local stdio wrapper
+
+Options (route claude | codex):
+  --launch          Start the agent after routing
+
+Options (route mcp):
+  --target CMD      Upstream MCP command (local tokensaver-mcp-gateway)
+
+Environment:
+  TOKENSAVER_API_KEY          Required — ts_… API key
+  TOKENSAVER_API_URL          API host (default https://api.tokensaver.fr)
+  TOKENSAVER_OPENAI_BASE_URL  Override OpenAI-compat base
+  TOKENSAVER_ANTHROPIC_BASE_URL Override Anthropic-compat base
+  TOKENSAVER_MCP_URL          MCP tools URL (default mcp.tokensaver.fr)
+  TOKENSAVER_GATEWAY_URL      MCP gateway URL (default gateway.tokensaver.fr)
+  X-Organisation-ID           Optional scope header for gateway
+  X-Workspace-ID              Optional scope header for gateway
+
+Examples:
+  tokensaver route claude --launch
+  tokensaver route cursor
+  tokensaver route proxy
+  tokensaver unroute claude
+  tokensaver doctor
+
+Install: pip install tokensaver-cli
+Docs: {DOCS_URL}
+"""
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="tokensaver",
+        description="Route AI agents through TokenSaver (cache, compression, PII, governance).",
+        add_help=False,
+    )
+    parser.add_argument("command", nargs="?", choices=("route", "unroute", "doctor", "help"))
+    parser.add_argument("target", nargs="?", choices=ROUTE_TARGETS)
+    parser.add_argument("--launch", action="store_true", help="Launch agent after route (claude, codex)")
+    parser.add_argument("--target", dest="mcp_target", default=None, help="Upstream MCP for route mcp")
+    parser.add_argument("-h", "--help", action="store_true")
+    parser.add_argument("remainder", nargs=argparse.REMAINDER)
+    return parser
+
+
+def _split_remainder(remainder: list[str]) -> list[str]:
+    if remainder and remainder[0] == "--":
+        return remainder[1:]
+    return [a for a in remainder if a != "--"]
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    print_banner()
+
+    if args.help or args.command in (None, "help"):
+        print_usage()
+        raise SystemExit(0)
+
+    if args.command == "doctor":
+        raise SystemExit(run_doctor())
+
+    if args.command == "unroute":
+        if not args.target:
+            print("unroute requires a target:", ", ".join(UNROUTE_TARGETS), file=sys.stderr)
+            raise SystemExit(2)
+        handlers = {
+            "claude": unroute_claude,
+            "cursor": unroute_cursor,
+            "codex": unroute_codex,
+            "proxy": unroute_proxy,
+            "mcp": unroute_mcp,
+        }
+        raise SystemExit(handlers[args.target]())
+
+    if args.command != "route":
+        print_usage()
+        raise SystemExit(2)
+
+    if not args.target:
+        print("route requires a target:", ", ".join(ROUTE_TARGETS), file=sys.stderr)
+        raise SystemExit(2)
+
+    try:
+        cfg = resolve_route_config()
+    except RouteConfigError as exc:
+        print(str(exc), file=sys.stderr)
+        raise SystemExit(1) from exc
+
+    extra = _split_remainder(args.remainder)
+    launch = args.launch or bool(extra)
+
+    handlers = {
+        "claude": lambda: route_claude(cfg, launch=launch, extra_args=extra),
+        "cursor": lambda: route_cursor(cfg),
+        "codex": lambda: route_codex(cfg, launch=launch, extra_args=extra),
+        "proxy": lambda: route_proxy(cfg),
+        "mcp": lambda: route_mcp(cfg, target=args.mcp_target),
+    }
+    raise SystemExit(handlers[args.target]())
+
+
+if __name__ == "__main__":
+    main()

tokensaver_cli-0.1.0/src/tokensaver_cli/state.py

@@ -0,0 +1,102 @@
+"""Persist route state and config backups for ``unroute``."""
+
+from __future__ import annotations
+
+import json
+import shutil
+from dataclasses import asdict, dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+
+
+@dataclass
+class RoutedFile:
+    path: str
+    backup: str
+
+
+@dataclass
+class RouteRecord:
+    target: str
+    routed_at: str
+    files: list[RoutedFile]
+
+
+def route_state_dir() -> Path:
+    base = Path.home() / ".config" / "tokensaver" / "route"
+    base.mkdir(parents=True, exist_ok=True)
+    return base
+
+
+def backups_dir() -> Path:
+    path = route_state_dir() / "backups"
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def state_file() -> Path:
+    return route_state_dir() / "state.json"
+
+
+def load_state() -> dict[str, RouteRecord]:
+    path = state_file()
+    if not path.is_file():
+        return {}
+    raw = json.loads(path.read_text(encoding="utf-8"))
+    out: dict[str, RouteRecord] = {}
+    for target, rec in (raw.get("routes") or {}).items():
+        files = [RoutedFile(**f) for f in rec.get("files") or []]
+        out[target] = RouteRecord(
+            target=target,
+            routed_at=rec.get("routed_at", ""),
+            files=files,
+        )
+    return out
+
+
+def save_state(routes: dict[str, RouteRecord]) -> None:
+    payload = {
+        "routes": {
+            target: {
+                "target": rec.target,
+                "routed_at": rec.routed_at,
+                "files": [asdict(f) for f in rec.files],
+            }
+            for target, rec in routes.items()
+        }
+    }
+    state_file().write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+
+
+def backup_file(source: Path) -> str | None:
+    if not source.is_file():
+        return None
+    stamp = datetime.now(UTC).strftime("%Y%m%dT%H%M%SZ")
+    dest = backups_dir() / f"{source.name}.{stamp}.bak"
+    shutil.copy2(source, dest)
+    return str(dest)
+
+
+def restore_file(source: Path, backup_path: str) -> None:
+    backup = Path(backup_path)
+    if not backup.is_file():
+        raise FileNotFoundError(f"Backup not found: {backup_path}")
+    source.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(backup, source)
+
+
+def record_route(target: str, files: list[RoutedFile]) -> None:
+    routes = load_state()
+    routes[target] = RouteRecord(
+        target=target,
+        routed_at=datetime.now(UTC).isoformat(),
+        files=files,
+    )
+    save_state(routes)
+
+
+def clear_route(target: str) -> RouteRecord | None:
+    routes = load_state()
+    rec = routes.pop(target, None)
+    save_state(routes)
+    return rec

tokensaver_cli-0.1.0/src/tokensaver_cli.egg-info/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: tokensaver-cli
+Version: 0.1.0
+Summary: TokenSaver CLI — route AI agents (Claude Code, Cursor, Codex) through the SaaS control plane
+Author: TokenSaver
+License-Expression: MIT
+Project-URL: Homepage, https://platform.tokensaver.fr
+Project-URL: Documentation, https://tokensaver.fr/sdk-api
+Project-URL: PyPI, https://pypi.org/project/tokensaver-cli/
+Keywords: tokensaver,llm,cli,claude,cursor,mcp,agents
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Dynamic: license-file
+
+# TokenSaver CLI (`tokensaver-cli`)
+
+Console command **`tokensaver`** to route AI agents through the **TokenSaver SaaS control plane** (`api.tokensaver.fr`) — cache, compression, PII, MCP gateway, observability.
+
+Companion package to **[`tokensaver-sdk`](https://pypi.org/project/tokensaver-sdk/)** (Python API client). The CLI configures your **local machine**; the pipeline runs on TokenSaver servers.
+
+**Get started:** sign up at [platform.tokensaver.fr](https://platform.tokensaver.fr), create a **`ts_…`** API key, then:
+
+```bash
+pip install tokensaver-cli
+export TOKENSAVER_API_KEY=ts_your_key
+tokensaver route claude --launch
+tokensaver doctor
+```
+
+## Installation
+
+```bash
+pip install tokensaver-cli
+```
+
+Development inside the monorepo:
+
+```bash
+cd packages/cli
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+**Requirements:** Python ≥ 3.10, no extra runtime dependencies (stdlib only).
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `tokensaver route claude` | Configure Claude Code (`~/.claude/settings.json` + `.mcp.json`) |
+| `tokensaver route claude --launch` | Configure + start `claude` |
+| `tokensaver route cursor` | Write `.cursor/mcp.json` + print Override URL steps |
+| `tokensaver route codex` | Print OpenAI-compat env vars for Codex |
+| `tokensaver route proxy` | Show base URLs for LangChain / OpenAI SDK / your code |
+| `tokensaver unroute <target>` | Restore backed-up config |
+| `tokensaver doctor` | Check API key and SaaS endpoint reachability |
+
+## SaaS defaults (no local server)
+
+| Surface | URL |
+|---------|-----|
+| API | `https://api.tokensaver.fr` |
+| OpenAI-compat | `https://api.tokensaver.fr/openai/v1` |
+| Anthropic-compat | `https://api.tokensaver.fr/anthropic` |
+| MCP tools | `https://mcp.tokensaver.fr/mcp` |
+| MCP gateway | `https://gateway.tokensaver.fr/mcp` |
+
+Override with `TOKENSAVER_API_URL`, `TOKENSAVER_MCP_URL`, etc. if you use a private deployment.
+
+## Environment
+
+```bash
+export TOKENSAVER_API_KEY=ts_…   # required
+# optional scope for MCP gateway headers:
+export X-Organisation-ID=…
+export X-Workspace-ID=…
+```
+
+## Related packages
+
+| PyPI package | Role |
+|--------------|------|
+| **`tokensaver-cli`** | This package — `tokensaver route` / `doctor` |
+| **`tokensaver-sdk`** | Python API client — `TokenSaver(api_key=…).ask(…)` |
+
+API reference (public): [tokensaver.fr/sdk-api](https://tokensaver.fr/sdk-api)
+
+## Tests
+
+```bash
+cd packages/cli && pip install -e ".[dev]" && pytest -q
+```
+
+## Publishing to PyPI
+
+Maintainers: see **[`docs/PYPI-CLI-RELEASE.md`](../../docs/PYPI-CLI-RELEASE.md)**.
+
+Tag format: **`cli-vX.Y.Z`** (version in `src/tokensaver_cli/__init__.py`).

tokensaver_cli-0.1.0/src/tokensaver_cli.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+LICENSE
+README.md
+pyproject.toml
+src/tokensaver_cli/__init__.py
+src/tokensaver_cli/agents.py
+src/tokensaver_cli/banner.py
+src/tokensaver_cli/config.py
+src/tokensaver_cli/doctor.py
+src/tokensaver_cli/json_merge.py
+src/tokensaver_cli/main.py
+src/tokensaver_cli/state.py
+src/tokensaver_cli.egg-info/PKG-INFO
+src/tokensaver_cli.egg-info/SOURCES.txt
+src/tokensaver_cli.egg-info/dependency_links.txt
+src/tokensaver_cli.egg-info/entry_points.txt
+src/tokensaver_cli.egg-info/requires.txt
+src/tokensaver_cli.egg-info/top_level.txt
+tests/test_banner.py
+tests/test_route_cli.py

tokensaver_cli-0.1.0/src/tokensaver_cli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

tokensaver_cli-0.1.0/src/tokensaver_cli.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tokensaver = tokensaver_cli.main:main

tokensaver_cli-0.1.0/src/tokensaver_cli.egg-info/requires.txt

@@ -0,0 +1,6 @@
+
+[dev]
+build>=1.0.0
+pytest>=7.4.0
+ruff>=0.1.0
+twine>=5.0.0

tokensaver_cli-0.1.0/src/tokensaver_cli.egg-info/top_level.txt

@@ -0,0 +1 @@
+tokensaver_cli

tokensaver_cli-0.1.0/tests/test_banner.py

@@ -0,0 +1,21 @@
+"""Banner tests."""
+
+from tokensaver_cli.banner import banner_enabled, print_banner
+
+
+def test_banner_enabled_default(monkeypatch) -> None:
+    monkeypatch.delenv("TOKENSAVER_NO_BANNER", raising=False)
+    assert banner_enabled() is True
+
+
+def test_banner_disabled(monkeypatch) -> None:
+    monkeypatch.setenv("TOKENSAVER_NO_BANNER", "1")
+    assert banner_enabled() is False
+
+
+def test_print_banner_runs(capsys, monkeypatch) -> None:
+    monkeypatch.delenv("TOKENSAVER_NO_BANNER", raising=False)
+    print_banner()
+    out = capsys.readouterr().out
+    assert "TokenSaver CLI" in out
+    assert "CONTROL PLANE" in out

tokensaver_cli-0.1.0/tests/test_route_cli.py

@@ -0,0 +1,131 @@
+"""Tests for tokensaver route CLI."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+import pytest
+
+from tokensaver_cli.agents import route_claude, route_cursor, unroute_claude, unroute_cursor
+from tokensaver_cli.config import RouteConfig, RouteConfigError, resolve_route_config
+from tokensaver_cli.state import load_state, route_state_dir
+
+
+@pytest.fixture
+def route_home(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+    config_home = tmp_path / "home"
+    monkeypatch.setenv("HOME", str(config_home))
+    monkeypatch.setenv("TOKENSAVER_API_KEY", "ts_test_key_12345678")
+    monkeypatch.setenv("TOKENSAVER_API_URL", "https://api.example.test")
+    return config_home
+
+
+@pytest.fixture
+def cfg() -> RouteConfig:
+    return RouteConfig(
+        api_key="ts_test_key_12345678",
+        api_host="https://api.example.test",
+        anthropic_base_url="https://api.example.test/anthropic",
+        openai_base_url="https://api.example.test/openai/v1",
+        mcp_tools_url="https://mcp.example.test/mcp",
+        gateway_url="https://gateway.example.test/mcp",
+        organisation_id="org-1",
+        workspace_id="ws-1",
+    )
+
+
+def test_resolve_route_config_requires_api_key(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("TOKENSAVER_API_KEY", raising=False)
+    with pytest.raises(RouteConfigError):
+        resolve_route_config()
+
+
+def test_resolve_route_config_strips_api_v1_suffix(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("TOKENSAVER_API_KEY", "ts_x")
+    monkeypatch.setenv("TOKENSAVER_API_BASE_URL", "https://api.example.test/api/v1")
+    resolved = resolve_route_config()
+    assert resolved.api_host == "https://api.example.test"
+    assert resolved.api_v1_base == "https://api.example.test/api/v1"
+
+
+def test_route_claude_writes_settings_and_mcp(route_home: Path, cfg: RouteConfig, tmp_path: Path) -> None:
+    project = tmp_path / "project"
+    project.mkdir()
+    old_cwd = os.getcwd()
+    try:
+        os.chdir(project)
+        assert route_claude(cfg, launch=False, extra_args=[]) == 0
+    finally:
+        os.chdir(old_cwd)
+
+    settings_path = route_home / ".claude" / "settings.json"
+    assert settings_path.is_file()
+    settings = json.loads(settings_path.read_text())
+    assert settings["env"]["ANTHROPIC_BASE_URL"] == cfg.anthropic_base_url
+    assert settings["env"]["ANTHROPIC_AUTH_TOKEN"] == cfg.api_key
+
+    mcp_path = project / ".mcp.json"
+    assert mcp_path.is_file()
+    mcp = json.loads(mcp_path.read_text())
+    assert "tokensaver-route-tools" in mcp["mcpServers"]
+    assert "tokensaver-route-gateway" in mcp["mcpServers"]
+
+    state = load_state()
+    assert "claude" in state
+    assert route_state_dir().is_dir()
+
+
+def test_unroute_claude_restores_backup(route_home: Path, cfg: RouteConfig, tmp_path: Path) -> None:
+    project = tmp_path / "project"
+    project.mkdir()
+    settings_path = route_home / ".claude"
+    settings_path.mkdir(parents=True)
+    original = settings_path / "settings.json"
+    original.write_text('{"env": {"FOO": "bar"}}\n', encoding="utf-8")
+
+    old_cwd = os.getcwd()
+    try:
+        os.chdir(project)
+        route_claude(cfg, launch=False, extra_args=[])
+        assert "ANTHROPIC_BASE_URL" in original.read_text()
+        assert unroute_claude() == 0
+        restored = json.loads(original.read_text())
+        assert restored["env"]["FOO"] == "bar"
+        assert "ANTHROPIC_BASE_URL" not in restored.get("env", {})
+    finally:
+        os.chdir(old_cwd)
+
+
+def test_route_cursor_writes_mcp_json(cfg: RouteConfig, tmp_path: Path) -> None:
+    project = tmp_path / "proj"
+    project.mkdir()
+    old_cwd = os.getcwd()
+    try:
+        os.chdir(project)
+        assert route_cursor(cfg) == 0
+        mcp = json.loads((project / ".cursor" / "mcp.json").read_text())
+        assert mcp["mcpServers"]["tokensaver-route-gateway"]["headers"]["X-Tokensaver-Client"] == "cursor/1.0"
+    finally:
+        os.chdir(old_cwd)
+
+
+def test_unroute_cursor_restores(route_home: Path, cfg: RouteConfig, tmp_path: Path) -> None:
+    project = tmp_path / "proj"
+    cursor_dir = project / ".cursor"
+    cursor_dir.mkdir(parents=True)
+    mcp_path = cursor_dir / "mcp.json"
+    mcp_path.write_text('{"mcpServers": {"other": {"url": "http://x"}}}\n', encoding="utf-8")
+
+    old_cwd = os.getcwd()
+    try:
+        os.chdir(project)
+        route_cursor(cfg)
+        route_cursor(cfg)
+        assert unroute_cursor() == 0
+        restored = json.loads(mcp_path.read_text())
+        assert "tokensaver-route-tools" not in restored.get("mcpServers", {})
+        assert restored["mcpServers"]["other"]["url"] == "http://x"
+    finally:
+        os.chdir(old_cwd)