Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
feat(wrap): add `headroom wrap kimi` for Kimi CLI (#1426)
kazeac49656a1cd
diff --git a/README.md b/README.mdindex 0f4da2dc3..c61a1b0e9 100644--- a/README.md+++ b/README.md@@ -240,10 +240,11 @@ shows an **Output Tokens Saved** card next to input compression, labelled| Mistral Vibe | ✅ | starts proxy + launches || Oh My Pi | ✅ | injects config · starts proxy + launches || Cortex Code | Library only | 60–65% savings (library mode; no `wrap`) |+| Kimi CLI | ✅ | OAuth bearer forwarded — log in once || ZCode | ✅ | starts proxy and prints base URLs for ZCode settings |Any OpenAI-compatible client works via `headroom proxy`. MCP-native: `headroom mcp install`.-Undo durable wrapping with `headroom unwrap <tool>` (supports: `claude`, `copilot`, `codex`, `grok`, `omp`, `opencode`, `openclaw`, `zcode`).+Undo durable wrapping with `headroom unwrap <tool>` (supports: `claude`, `copilot`, `codex`, `grok`, `kimi`, `omp`, `opencode`, `openclaw`, `zcode`).Registry authors can use the canonical [`server.json`](server.json) in the repo root instead of reconstructing the `headroom mcp serve` contract from prose.### GitHub Copilot CLI subscription modediff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.pyindex 3a53bcfd1..0dee5a053 100644--- a/headroom/cli/wrap.py+++ b/headroom/cli/wrap.py@@ -120,6 +120,7 @@ from headroom.providers.grok_build.config import (inject_grok_provider_config,restore_grok_provider_config,)+from headroom.providers.kimi import build_launch_env as _build_kimi_launch_envfrom headroom.providers.mistral_vibe import build_launch_env as _build_mistral_vibe_launch_envfrom headroom.providers.omp import build_launch_env as _build_omp_launch_envfrom headroom.providers.omp import inject_models_override as _inject_omp_models_override@@ -1832,7 +1833,7 @@ def _codex_toml_value(value: Any) -> str:return json.dumps(value)if isinstance(value, bool):return "true" if value else "false"- if isinstance(value, (int, float)):+ if isinstance(value, int | float):return str(value)raise TypeError(f"unsupported Codex config override: {type(value).__name__}")@@ -5709,6 +5710,93 @@ def vibe()+# =============================================================================+# Kimi CLI+# =============================================================================++[email protected](context_settings={"ignore_unknown_options": True})+ "--port", "-p", default=8787, type=click.IntRange(1, 65535), help="Proxy port (default: 8787)"+)+ "--no-context-tool",+ "--no-rtk",+ "no_rtk",+ is_flag=True,+ help="Skip CLI context-tool setup (no effect for kimi)",+)+ "--code-graph",+ is_flag=True,+ help="Enable code graph indexing via codebase-memory-mcp (optional)",+)[email protected]("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")[email protected]("--learn", is_flag=True, help="Enable live traffic learning")[email protected]("--memory", is_flag=True, help="Enable persistent cross-session memory")[email protected]("--verbose", "-v", is_flag=True, help="Verbose output")+ "--kimi-api-url",+ default="https://api.kimi.com/coding/v1",+ help="Upstream Kimi coding endpoint (default: https://api.kimi.com/coding/v1)",+)[email protected]("--prepare-only", is_flag=True, hidden=True)[email protected]("kimi_args", nargs=-1, type=click.UNPROCESSED)+def kimi(+ port: int,+ no_rtk: bool,+ code_graph: bool,+ no_proxy: bool,+ learn: bool,+ memory: bool,+ verbose: bool,+ kimi_api_url: str,+ prepare_only: bool,+ kimi_args: tuple,+) -> None:+ """Launch Kimi CLI through Headroom proxy.++ \b+ Sets KIMI_BASE_URL to route Kimi's OpenAI-compatible /chat/completions+ traffic through Headroom. Kimi's own OAuth bearer is forwarded upstream,+ so no extra login is required — run `kimi` once to authenticate first.++ \b+ Examples:+ headroom wrap kimi # Start proxy + kimi+ headroom wrap kimi -- -m kimi-for-coding # Pass args to kimi+ headroom wrap kimi --port 9999 # Custom proxy port+ headroom wrap kimi --kimi-api-url https://api.moonshot.ai/v1+ """+ if prepare_only:+ return++ kimi_bin = shutil.which("kimi") or shutil.which("kimi-cli")+ if not kimi_bin:+ click.echo("Error: 'kimi' (or 'kimi-cli') not found in PATH.")+ click.echo("Install Kimi CLI: https://github.com/MoonshotAI/kimi-cli")+ raise SystemExit(1)++ env, env_vars_display = _build_kimi_launch_env(+ port, os.environ, project=_project_name_from_cwd()+ )++ _launch_tool(+ binary=kimi_bin,+ args=kimi_args,+ env=env,+ port=port,+ no_proxy=no_proxy,+ tool_label="KIMI",+ env_vars_display=env_vars_display,+ learn=learn,+ memory=memory,+ agent_type="kimi",+ code_graph=code_graph,+ openai_api_url=kimi_api_url,+ )++# =============================================================================# Grok CLI# =============================================================================diff --git a/headroom/providers/kimi/__init__.py b/headroom/providers/kimi/__init__.pynew file mode 100644index 000000000..e53b4ed47--- /dev/null+++ b/headroom/providers/kimi/__init__.py@@ -0,0 +1,5 @@+"""Kimi CLI-specific provider helpers."""++from .runtime import build_launch_env++__all__ = ["build_launch_env"]diff --git a/headroom/providers/kimi/runtime.py b/headroom/providers/kimi/runtime.pynew file mode 100644index 000000000..fa2a30678--- /dev/null+++ b/headroom/providers/kimi/runtime.py@@ -0,0 +1,34 @@+"""Runtime helpers for Kimi CLI integrations."""++from __future__ import annotations++import os+from collections.abc import Mapping++from headroom.providers.codex import proxy_base_url as codex_proxy_base_url+from headroom.proxy.project_context import with_project_prefix+++def build_launch_env(+ port: int,+ environ: Mapping[str, str] | None = None,+ project: str | None = None,+) -> tuple[dict[str, str], list[str]]:+ """Build environment variables for Kimi CLI through the local proxy.++ Kimi CLI (``kimi`` / ``kimi-cli``) talks to its managed coding endpoint with+ an OpenAI-compatible ``/chat/completions`` client (``kosong``'s ``Kimi``+ provider wraps ``AsyncOpenAI``). Its base URL is overridable via the+ ``KIMI_BASE_URL`` environment variable, so we point it at the local proxy.+ The proxy forwards the request — including Kimi's own OAuth ``Authorization``+ bearer (passthrough auth mode) — to the real upstream configured by+ ``--openai-api-url`` (``https://api.kimi.com/coding/v1``).++ ``project`` (the wrap launch directory) is encoded as a ``/p/<name>``+ base-URL prefix because the Kimi base-URL override cannot carry custom+ headers; the proxy strips it and attributes savings per project.+ """+ env = dict(environ or os.environ)+ base_url = with_project_prefix(codex_proxy_base_url(port), project)+ env["KIMI_BASE_URL"] = base_url+ return env, [f"KIMI_BASE_URL={base_url}"]diff --git a/tests/test_cli/test_wrap_kimi.py b/tests/test_cli/test_wrap_kimi.pynew file mode 100644index 000000000..01f94b45c--- /dev/null+++ b/tests/test_cli/test_wrap_kimi.py@@ -0,0 +1,214 @@+"""Tests for `headroom wrap kimi` command."""++from __future__ import annotations++from pathlib import Path+from typing import Any+from unittest.mock import patch++import pytest+from click.testing import CliRunner++from headroom.cli import wrap as wrap_mod+from headroom.cli.main import main+++def runner() -> CliRunner:+ return CliRunner()+++def test_wrap_kimi_launch(+ runner: CliRunner,+ tmp_path: Path,+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """Kimi launches with correct configuration."""+ monkeypatch.chdir(tmp_path)+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)++ captured: dict[str, Any] = {}++ def fake_launch_tool(**kwargs: Any) -> None: # noqa: ANN003+ captured.update(kwargs)++ with patch.object(wrap_mod.shutil, "which", return_value="kimi"):+ with patch.object(wrap_mod, "_launch_tool", side_effect=fake_launch_tool):+ with patch.object(wrap_mod, "_project_name_from_cwd", return_value=None):+ result = runner.invoke(+ main, ["wrap", "kimi", "--port", "9000", "--", "-m", "kimi-for-coding"]+ )++ assert result.exit_code == 0, result.output+ env = captured["env"]+ assert isinstance(env, dict)+ assert captured["tool_label"] == "KIMI"+ assert captured["agent_type"] == "kimi"+ assert captured["args"] == ("-m", "kimi-for-coding")+ assert captured["openai_api_url"] == "https://api.kimi.com/coding/v1"+ assert env["KIMI_BASE_URL"] == "http://127.0.0.1:9000/v1"+++def test_wrap_kimi_with_project_name(+ runner: CliRunner,+ tmp_path: Path,+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """Project name is encoded in KIMI_BASE_URL when run from a project directory."""+ project_dir = tmp_path / "my-project"+ project_dir.mkdir()+ monkeypatch.chdir(project_dir)+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)++ captured: dict[str, Any] = {}++ def fake_launch_tool(**kwargs: Any) -> None: # noqa: ANN003+ captured.update(kwargs)++ with patch.object(wrap_mod.shutil, "which", return_value="kimi"):+ with patch.object(wrap_mod, "_launch_tool", side_effect=fake_launch_tool):+ result = runner.invoke(main, ["wrap", "kimi", "--port", "7000"])++ assert result.exit_code == 0, result.output+ env = captured["env"]+ assert env["KIMI_BASE_URL"] == "http://127.0.0.1:7000/p/my-project/v1"+++def test_wrap_kimi_cli_fallback(+ runner: CliRunner,+ tmp_path: Path,+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """Falls back to the `kimi-cli` binary when `kimi` is not on PATH."""+ monkeypatch.chdir(tmp_path)+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)++ captured: dict[str, Any] = {}++ def fake_launch_tool(**kwargs: Any) -> None: # noqa: ANN003+ captured.update(kwargs)++ def fake_which(name: str) -> str | None:+ return "/usr/local/bin/kimi-cli" if name == "kimi-cli" else None++ with patch.object(wrap_mod.shutil, "which", side_effect=fake_which):+ with patch.object(wrap_mod, "_launch_tool", side_effect=fake_launch_tool):+ with patch.object(wrap_mod, "_project_name_from_cwd", return_value=None):+ result = runner.invoke(main, ["wrap", "kimi"])++ assert result.exit_code == 0, result.output+ assert captured["binary"] == "/usr/local/bin/kimi-cli"+++def test_wrap_kimi_not_found(+ runner: CliRunner,+ tmp_path: Path,+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """Error message when neither kimi nor kimi-cli is found."""+ monkeypatch.chdir(tmp_path)+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)++ with patch.object(wrap_mod.shutil, "which", return_value=None):+ result = runner.invoke(main, ["wrap", "kimi"])++ assert result.exit_code == 1+ assert "Error: 'kimi' (or 'kimi-cli') not found in PATH" in result.output+ assert "https://github.com/MoonshotAI/kimi-cli" in result.output+++def test_wrap_kimi_custom_port(+ runner: CliRunner,+ tmp_path: Path,+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """Custom --port is passed to _launch_tool and appears in KIMI_BASE_URL."""+ monkeypatch.chdir(tmp_path)+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)++ captured: dict[str, Any] = {}++ def fake_launch_tool(**kwargs: Any) -> None: # noqa: ANN003+ captured.update(kwargs)++ with patch.object(wrap_mod.shutil, "which", return_value="kimi"):+ with patch.object(wrap_mod, "_launch_tool", side_effect=fake_launch_tool):+ with patch.object(wrap_mod, "_project_name_from_cwd", return_value=None):+ result = runner.invoke(main, ["wrap", "kimi", "--port", "9999"])++ assert result.exit_code == 0, result.output+ assert captured["port"] == 9999+ assert captured["env"]["KIMI_BASE_URL"] == "http://127.0.0.1:9999/v1"+++def test_wrap_kimi_custom_api_url(+ runner: CliRunner,+ tmp_path: Path,+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """--kimi-api-url overrides the upstream endpoint passed to _launch_tool."""+ monkeypatch.chdir(tmp_path)+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)++ captured: dict[str, Any] = {}++ def fake_launch_tool(**kwargs: Any) -> None: # noqa: ANN003+ captured.update(kwargs)++ with patch.object(wrap_mod.shutil, "which", return_value="kimi"):+ with patch.object(wrap_mod, "_launch_tool", side_effect=fake_launch_tool):+ with patch.object(wrap_mod, "_project_name_from_cwd", return_value=None):+ result = runner.invoke(+ main,+ ["wrap", "kimi", "--kimi-api-url", "https://api.moonshot.ai/v1"],+ )++ assert result.exit_code == 0, result.output+ assert captured["openai_api_url"] == "https://api.moonshot.ai/v1"+++def test_wrap_kimi_no_proxy(+ runner: CliRunner,+ tmp_path: Path,+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """--no-proxy flag prevents proxy startup."""+ monkeypatch.chdir(tmp_path)+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)++ captured: dict[str, Any] = {}++ def fake_launch_tool(**kwargs: Any) -> None: # noqa: ANN003+ captured.update(kwargs)++ with patch.object(wrap_mod.shutil, "which", return_value="kimi"):+ with patch.object(wrap_mod, "_launch_tool", side_effect=fake_launch_tool):+ with patch.object(wrap_mod, "_project_name_from_cwd", return_value=None):+ result = runner.invoke(main, ["wrap", "kimi", "--no-proxy"])++ assert result.exit_code == 0, result.output+ assert captured["no_proxy"] is True+++def test_wrap_kimi_learn_memory(+ runner: CliRunner,+ tmp_path: Path,+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """--learn and --memory flags are passed to _launch_tool."""+ monkeypatch.chdir(tmp_path)+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)++ captured: dict[str, Any] = {}++ def fake_launch_tool(**kwargs: Any) -> None: # noqa: ANN003+ captured.update(kwargs)++ with patch.object(wrap_mod.shutil, "which", return_value="kimi"):+ with patch.object(wrap_mod, "_launch_tool", side_effect=fake_launch_tool):+ with patch.object(wrap_mod, "_project_name_from_cwd", return_value=None):+ result = runner.invoke(main, ["wrap", "kimi", "--learn", "--memory"])++ assert result.exit_code == 0, result.output+ assert captured["learn"] is True+ assert captured["memory"] is True