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
refactor: migrate Python callsites to canonical paths module
JerrettDavis3a1bbbbc1444
diff --git a/headroom/ccr/mcp_server.py b/headroom/ccr/mcp_server.pyindex a2172e4ef..569e04928 100644--- a/headroom/ccr/mcp_server.py+++ b/headroom/ccr/mcp_server.py@@ -32,6 +32,8 @@ from dataclasses import dataclass, fieldfrom pathlib import Pathfrom typing import Any+from headroom import paths as _paths+# fcntl is Unix-only; on Windows we skip file locking (stats are best-effort).# Keep the module typed as Any so Windows mypy runs don't try to resolve Unix-only attrs.fcntl: Any = None@@ -168,8 +170,9 @@ MCP_SESSION_TTL = 3600# Shared stats file: all MCP instances (main + sub-agents) append here.# headroom_stats aggregates across all instances within the session window.-SHARED_STATS_DIR = Path.home() / ".headroom"-SHARED_STATS_FILE = SHARED_STATS_DIR / "session_stats.jsonl"+# Respects HEADROOM_WORKSPACE_DIR.+SHARED_STATS_DIR = _paths.workspace_dir()+SHARED_STATS_FILE = _paths.session_stats_path()SESSION_WINDOW_SECONDS = 7200 # 2 hours — events older than this are pruned@@ -726,7 +729,6 @@ class HeadroomMCPServer:async def _handle_read(self, arguments: dict[str, Any]) -> list[TextContent]:"""Handle headroom_read tool call — file read with session caching."""import hashlib- from pathlib import Pathfile_path = arguments.get("file_path", "")fresh = arguments.get("fresh", False)diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.pyindex a3e19cb18..310ed53ff 100644--- a/headroom/cli/wrap.py+++ b/headroom/cli/wrap.py@@ -68,7 +68,9 @@ def _check_proxy(port: int) -> bool:def _get_log_path() -> Path:"""Get path for proxy log file."""- log_dir = Path.home() / ".headroom" / "logs"+ from headroom import paths as _paths++ log_dir = _paths.log_dir()log_dir.mkdir(parents=True, exist_ok=True)return log_dir / "proxy.log"diff --git a/headroom/install/paths.py b/headroom/install/paths.pyindex 500ce5e33..a0f6a3def 100644--- a/headroom/install/paths.py+++ b/headroom/install/paths.py@@ -8,6 +8,8 @@ from pathlib import Pathimport click+from headroom import paths as _paths+_PROFILE_RE = re.compile(r"^[A-Za-z0-9._-]+$")@@ -22,7 +24,7 @@ def validate_profile_name(profile: str) -> str:def deploy_root() -> Path:"""Return the root directory for deployment state."""- return Path.home() / ".headroom" / "deploy"+ return _paths.deploy_root()def profile_root(profile: str) -> Path:diff --git a/headroom/install/planner.py b/headroom/install/planner.pyindex 0d50c1c48..fad523036 100644--- a/headroom/install/planner.py+++ b/headroom/install/planner.py@@ -4,10 +4,11 @@ from __future__ import annotationsimport shutilfrom collections.abc import Iterable-from pathlib import Pathimport click+from headroom import paths as _paths+from .models import (ConfigScope,DeploymentManifest,@@ -192,9 +193,7 @@ def build_manifest(if not telemetry_enabled:proxy_args.append("--no-telemetry")if memory_enabled:- proxy_args.extend(- ["--memory", "--memory-db-path", str(Path.home() / ".headroom" / "memory.db")]- )+ proxy_args.extend(["--memory", "--memory-db-path", str(_paths.memory_db_path())])if anyllm_provider:proxy_args.extend(["--anyllm-provider", anyllm_provider])if region:@@ -216,7 +215,7 @@ def build_manifest(region=region,proxy_mode=proxy_mode,memory_enabled=memory_enabled,- memory_db_path=str(Path.home() / ".headroom" / "memory.db"),+ memory_db_path=str(_paths.memory_db_path()),telemetry_enabled=telemetry_enabled,image=image,service_name=f"headroom-{normalized_profile}",diff --git a/headroom/memory/bridge_config.py b/headroom/memory/bridge_config.pyindex 5d69ff247..0225d757e 100644--- a/headroom/memory/bridge_config.py+++ b/headroom/memory/bridge_config.py@@ -10,6 +10,8 @@ from dataclasses import dataclass, fieldfrom enum import Enumfrom pathlib import Path+from headroom import paths as _paths+class MarkdownFormat(Enum):"""Supported markdown memory formats."""@@ -47,9 +49,7 @@ class BridgeConfig:heading_importance_map: dict[int, float] = field(default_factory=lambda: {1: 0.9, 2: 0.8, 3: 0.7, 4: 0.6, 5: 0.5, 6: 0.4})- sync_state_path: Path = field(- default_factory=lambda: Path.home() / ".headroom" / "bridge_state.json"- )+ sync_state_path: Path = field(default_factory=_paths.bridge_state_path)auto_import_on_startup: bool = Falseexport_path: Path | None = Noneexport_format: MarkdownFormat = MarkdownFormat.GENERICdiff --git a/headroom/memory/easy.py b/headroom/memory/easy.pyindex 7c6397030..737137b17 100644--- a/headroom/memory/easy.py+++ b/headroom/memory/easy.py@@ -105,10 +105,12 @@ class Memory:# Config for local backendif db_path is None:- # Default to ~/.headroom/memory.db- default_dir = Path.home() / ".headroom"- default_dir.mkdir(parents=True, exist_ok=True)- db_path = default_dir / "memory.db"+ # Default: workspace memory.db (respects HEADROOM_WORKSPACE_DIR)+ from headroom import paths as _paths++ default_db = _paths.memory_db_path()+ default_db.parent.mkdir(parents=True, exist_ok=True)+ db_path = default_dbself._db_path = Path(db_path)# Config for qdrant-neo4j backenddiff --git a/headroom/memory/sync.py b/headroom/memory/sync.pyindex c568c16fd..4ab48dbc0 100644--- a/headroom/memory/sync.py+++ b/headroom/memory/sync.py@@ -30,10 +30,13 @@ from datetime import datetime, timezonefrom pathlib import Pathfrom typing import Any+from headroom import paths as _paths+logger = logging.getLogger("headroom.memory.sync")-# State file for fast no-op detection-_DEFAULT_STATE_PATH = Path.home() / ".headroom" / "sync_state.json"+# State file for fast no-op detection (workspace bucket, respects+# HEADROOM_WORKSPACE_DIR). Resolved at import time, matching prior behavior.+_DEFAULT_STATE_PATH = _paths.sync_state_path()# ---------------------------------------------------------------------------diff --git a/headroom/perf/analyzer.py b/headroom/perf/analyzer.pyindex bf06add0f..e89851c80 100644--- a/headroom/perf/analyzer.py+++ b/headroom/perf/analyzer.py@@ -13,11 +13,12 @@ from __future__ import annotationsimport loggingimport refrom dataclasses import dataclass, field-from pathlib import Path++from headroom import paths as _pathslog = logging.getLogger(__name__)-LOG_DIR = Path.home() / ".headroom" / "logs"+LOG_DIR = _paths.log_dir()# Matches: 2026-03-07 13:38:31,009 - headroom.proxy - INFO - [hr_...] PERF model=... ..._PERF_RE = re.compile(diff --git a/headroom/providers/anthropic.py b/headroom/providers/anthropic.pyindex 556048196..70c2773d7 100644--- a/headroom/providers/anthropic.py+++ b/headroom/providers/anthropic.py@@ -20,9 +20,10 @@ import jsonimport loggingimport osimport warnings-from pathlib import Pathfrom typing import Any, cast+from headroom import paths as _paths+from .base import Provider, TokenCounterLITELLM_AVAILABLE = importlib.util.find_spec("litellm") is not None@@ -151,8 +152,13 @@ def _load_custom_model_config() -> dict[str, Any]:except (json.JSONDecodeError, OSError) as e:logger.warning(f"Failed to load HEADROOM_MODEL_LIMITS: {e}")- # Check config file- config_file = Path.home() / ".headroom" / "models.json"+ # Check config file. Prefer the canonical config-dir location, then fall+ # back to the legacy workspace-root location for backward compatibility.+ config_file = _paths.models_config_path()+ if not config_file.exists():+ legacy_models = _paths.workspace_dir() / "models.json"+ if legacy_models.exists():+ config_file = legacy_modelsif config_file.exists():try:with open(config_file) as f:diff --git a/headroom/providers/openai.py b/headroom/providers/openai.pyindex b2af317b5..beaa43644 100644--- a/headroom/providers/openai.py+++ b/headroom/providers/openai.py@@ -13,9 +13,10 @@ import osimport warningsfrom datetime import datefrom functools import lru_cache-from pathlib import Pathfrom typing import Any, cast+from headroom import paths as _paths+from .base import Provider, TokenCounterlogger = logging.getLogger(__name__)@@ -165,8 +166,13 @@ def _load_custom_model_config() -> dict[str, Any]:except (json.JSONDecodeError, OSError) as e:logger.warning(f"Failed to load HEADROOM_MODEL_LIMITS: {e}")- # Check config file- config_file = Path.home() / ".headroom" / "models.json"+ # Check config file. Prefer the canonical config-dir location, then fall+ # back to the legacy workspace-root location for backward compatibility.+ config_file = _paths.models_config_path()+ if not config_file.exists():+ legacy_models = _paths.workspace_dir() / "models.json"+ if legacy_models.exists():+ config_file = legacy_modelsif config_file.exists():try:with open(config_file) as f:@@ -380,7 +386,7 @@ class OpenAIProvider(Provider):# Handle pricing (can be tuple or list from JSON)for model, pricing in custom_config["pricing"].items():- if isinstance(pricing, (list, tuple)) and len(pricing) >= 2:+ if isinstance(pricing, list | tuple) and len(pricing) >= 2:self._pricing[model] = (float(pricing[0]), float(pricing[1]))# Explicit overrides take precedencediff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.pyindex a130aa909..45659ff38 100644--- a/headroom/proxy/handlers/anthropic.py+++ b/headroom/proxy/handlers/anthropic.py@@ -12,7 +12,6 @@ import loggingimport osimport timefrom datetime import datetime-from pathlib import Pathfrom typing import TYPE_CHECKING, Anyif TYPE_CHECKING:@@ -1073,7 +1072,9 @@ class AnthropicHandlerMixin:# Dump full request details to debug filetry:- debug_dir = Path.home() / ".headroom" / "logs" / "debug_400"+ from headroom import paths as _hr_paths++ debug_dir = _hr_paths.debug_400_dir()debug_dir.mkdir(parents=True, exist_ok=True)ts = datetime.now().strftime("%Y%m%d_%H%M%S")debug_file = debug_dir / f"{ts}_{request_id}.json"diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.pyindex a23d81c61..eb127ed71 100644--- a/headroom/proxy/handlers/openai.py+++ b/headroom/proxy/handlers/openai.py@@ -14,7 +14,6 @@ import loggingimport osimport timefrom datetime import datetime-from pathlib import Pathfrom typing import TYPE_CHECKING, Anyif TYPE_CHECKING:@@ -584,7 +583,9 @@ class OpenAIHandlerMixin:)try:- debug_dir = Path.home() / ".headroom" / "logs" / "debug_400"+ from headroom import paths as _hr_paths++ debug_dir = _hr_paths.debug_400_dir()debug_dir.mkdir(parents=True, exist_ok=True)ts = datetime.now().strftime("%Y%m%d_%H%M%S")debug_file = debug_dir / f"{ts}_{request_id}.json"diff --git a/headroom/proxy/helpers.py b/headroom/proxy/helpers.pyindex e4d857133..f3e8b93b8 100644--- a/headroom/proxy/helpers.py+++ b/headroom/proxy/helpers.py@@ -13,6 +13,8 @@ import loggingfrom pathlib import Pathfrom typing import TYPE_CHECKING, Any+from headroom import paths as _paths+if TYPE_CHECKING:from fastapi import Request@@ -52,8 +54,12 @@ def _get_image_compressor():return _image_compressor if _image_compressor else None-# Always-on file logging to ~/.headroom/logs/ for `headroom perf` analysis-_HEADROOM_LOG_DIR = Path.home() / ".headroom" / "logs"+# Always-on file logging to the workspace logs directory for `headroom perf` analysis.+# Resolved lazily so HEADROOM_WORKSPACE_DIR env-var changes are honored.+++def _headroom_log_dir() -> Path:+ return _paths.log_dir()def _setup_file_logging() -> None:@@ -66,8 +72,9 @@ def _setup_file_logging() -> None:from logging.handlers import RotatingFileHandlertry:- _HEADROOM_LOG_DIR.mkdir(parents=True, exist_ok=True)- log_path = _HEADROOM_LOG_DIR / "proxy.log"+ log_dir = _headroom_log_dir()+ log_dir.mkdir(parents=True, exist_ok=True)+ log_path = log_dir / "proxy.log"handler = RotatingFileHandler(log_path,maxBytes=10 * 1024 * 1024, # 10 MB@@ -101,8 +108,10 @@ def _get_rtk_stats() -> dict[str, Any] | None:rtk_bin = shutil.which("rtk")if not rtk_bin:- # Check headroom-managed install- rtk_managed = Path.home() / ".headroom" / "bin" / "rtk"+ # Check headroom-managed install. Preserve the historical Unix-name+ # behavior here (bin_dir()/"rtk") rather than switching to+ # paths.rtk_path() which would become rtk.exe on Windows.+ rtk_managed = _paths.bin_dir() / "rtk"if rtk_managed.exists():rtk_bin = str(rtk_managed)else:diff --git a/headroom/proxy/memory_handler.py b/headroom/proxy/memory_handler.pyindex d1bc17034..5ad45c3c4 100644--- a/headroom/proxy/memory_handler.py+++ b/headroom/proxy/memory_handler.py@@ -114,8 +114,10 @@ class MemoryHandler:if self.config.native_memory_dir:self._native_memory_dir = Path(self.config.native_memory_dir)else:- # Default: ~/.headroom/memories- self._native_memory_dir = Path.home() / ".headroom" / "memories"+ # Default: workspace memories directory (respects HEADROOM_WORKSPACE_DIR)+ from headroom import paths as _paths++ self._native_memory_dir = _paths.native_memory_dir()# Create directory if it doesn't existself._native_memory_dir.mkdir(parents=True, exist_ok=True)diff --git a/headroom/proxy/savings_tracker.py b/headroom/proxy/savings_tracker.pyindex 6ffe263cc..1d115b53a 100644--- a/headroom/proxy/savings_tracker.py+++ b/headroom/proxy/savings_tracker.py@@ -19,9 +19,11 @@ from io import StringIOfrom pathlib import Pathfrom typing import Any+from headroom import paths as _paths+logger = logging.getLogger(__name__)-HEADROOM_SAVINGS_PATH_ENV_VAR = "HEADROOM_SAVINGS_PATH"+HEADROOM_SAVINGS_PATH_ENV_VAR = _paths.HEADROOM_SAVINGS_PATH_ENVDEFAULT_SAVINGS_DIR = ".headroom"DEFAULT_SAVINGS_FILE = "proxy_savings.json"SCHEMA_VERSION = 2@@ -53,10 +55,13 @@ def _get_litellm_module() -> Any | None:def get_default_savings_storage_path() -> str:"""Return the configured savings storage path."""+ # Preserve legacy behavior: when HEADROOM_SAVINGS_PATH is set we return+ # the raw string exactly as supplied (no tilde expansion, no+ # path-separator normalization) to match prior behavior and existing tests.env_path = os.environ.get(HEADROOM_SAVINGS_PATH_ENV_VAR, "").strip()if env_path:return env_path- return str(Path.home() / DEFAULT_SAVINGS_DIR / DEFAULT_SAVINGS_FILE)+ return str(_paths.savings_path())def _utc_now() -> datetime:@@ -225,7 +230,7 @@ def _normalize_history_entry(entry: Any) -> dict[str, Any] | None:compression_savings_usd = _coerce_float(entry.get("compression_savings_usd"))total_input_tokens = _coerce_int(entry.get("total_input_tokens"))total_input_cost_usd = _coerce_float(entry.get("total_input_cost_usd"))- elif isinstance(entry, (list, tuple)) and len(entry) >= 2:+ elif isinstance(entry, list | tuple) and len(entry) >= 2:timestamp = _parse_timestamp(entry[0])total_tokens_saved = _coerce_int(entry[1])if len(entry) >= 3:diff --git a/headroom/proxy/server.py b/headroom/proxy/server.pyindex 3b5729337..7ee1f19a4 100644--- a/headroom/proxy/server.py+++ b/headroom/proxy/server.py@@ -976,7 +976,9 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:sdk=os.environ.get("HEADROOM_SDK", "proxy").strip() or "proxy",backend=config.backend if hasattr(config, "backend") else "anthropic",)- _beacon_lock_path = Path.home() / ".headroom" / f".beacon_lock_{config.port}"+ from headroom import paths as _hr_paths++ _beacon_lock_path = _hr_paths.beacon_lock_path(config.port)_beacon_lock_fd: list = [None] # mutable holder for the lock file descriptor_beacon_is_owner: list = [False]@@ -2532,7 +2534,8 @@ if __name__ == "__main__":"--openai-api-url", help=f"Custom OpenAI API URL (default: {HeadroomProxy.OPENAI_API_URL})")parser.add_argument(- "--anthropic-api-url", help=f"Custom Anthropic API URL (default: {HeadroomProxy.ANTHROPIC_API_URL})"+ "--anthropic-api-url",+ help=f"Custom Anthropic API URL (default: {HeadroomProxy.ANTHROPIC_API_URL})",)# Backend (anthropic direct, bedrock, openrouter, anyllm, or litellm-<provider>)diff --git a/headroom/rtk/__init__.py b/headroom/rtk/__init__.pyindex e9d9558dc..60632acd5 100644--- a/headroom/rtk/__init__.py+++ b/headroom/rtk/__init__.py@@ -10,8 +10,10 @@ import platformimport shutilfrom pathlib import Path+from headroom import paths as _paths+RTK_VERSION = "v0.28.2"-RTK_BIN_DIR = Path.home() / ".headroom" / "bin"+RTK_BIN_DIR = _paths.bin_dir()_RTK_NAME = "rtk.exe" if platform.system() == "Windows" else "rtk"RTK_BIN_PATH = RTK_BIN_DIR / _RTK_NAMEdiff --git a/headroom/subscription/tracker.py b/headroom/subscription/tracker.pyindex 33dccab51..ce0bf9237 100644--- a/headroom/subscription/tracker.py+++ b/headroom/subscription/tracker.py@@ -29,6 +29,7 @@ import threadingfrom pathlib import Pathfrom typing import Any+from headroom import paths as _pathsfrom headroom.subscription.base import QuotaTrackerfrom headroom.subscription.client import SubscriptionClientfrom headroom.subscription.models import (@@ -44,7 +45,7 @@ logger = logging.getLogger(__name__)_DEFAULT_POLL_INTERVAL_S = 10_DEFAULT_ACTIVE_WINDOW_S = 60-_PERSIST_FILE_ENV = "HEADROOM_SUBSCRIPTION_STATE_PATH"+_PERSIST_FILE_ENV = _paths.HEADROOM_SUBSCRIPTION_STATE_PATH_ENV_DEFAULT_PERSIST_DIR = ".headroom"_DEFAULT_PERSIST_FILE = "subscription_state.json"@@ -58,10 +59,7 @@ _CACHE_MISS_RATIO_THRESHOLD = 0.10def _get_persist_path() -> Path:- env = os.environ.get(_PERSIST_FILE_ENV, "").strip()- if env:- return Path(env)- return Path.home() / _DEFAULT_PERSIST_DIR / _DEFAULT_PERSIST_FILE+ return _paths.subscription_state_path()class SubscriptionTracker(QuotaTracker):diff --git a/headroom/telemetry/reporter.py b/headroom/telemetry/reporter.pyindex eb800e1c7..cf72fab2d 100644--- a/headroom/telemetry/reporter.py+++ b/headroom/telemetry/reporter.py@@ -29,6 +29,8 @@ from typing import TYPE_CHECKING, Anyimport httpx+from headroom import paths as _paths+if TYPE_CHECKING:from headroom.proxy.server import HeadroomProxy@@ -37,8 +39,8 @@ logger = logging.getLogger("headroom.telemetry.reporter")# Grace period: if the cloud API is unreachable, use cached license for up to 7 daysGRACE_PERIOD_SECONDS = 7 * 24 * 3600 # 7 days-# Default cache location-LICENSE_CACHE_PATH = Path.home() / ".headroom" / "license_cache.json"+# Default cache location (workspace bucket, respects HEADROOM_WORKSPACE_DIR).+LICENSE_CACHE_PATH = _paths.license_cache_path()@dataclassdiff --git a/headroom/telemetry/toin.py b/headroom/telemetry/toin.pyindex 191b48efb..f6ef9f8be 100644--- a/headroom/telemetry/toin.py+++ b/headroom/telemetry/toin.py@@ -50,7 +50,6 @@ import threadingimport timefrom collections.abc import Callablefrom dataclasses import dataclass, field-from pathlib import Pathfrom typing import Any, Literalfrom .models import FieldSemantics, ToolSignature@@ -69,19 +68,23 @@ def get_default_toin_storage_path() -> str:"""Get the default TOIN storage path.Checks for the HEADROOM_TOIN_PATH environment variable first.- Falls back to ~/.headroom/toin.json if not set or empty.+ Falls back to ``${HEADROOM_WORKSPACE_DIR}/toin.json`` (which defaults+ to ``~/.headroom/toin.json``) when unset.Returns:The path string for TOIN storage."""- # Check environment variable first+ # Preserve legacy behavior: when HEADROOM_TOIN_PATH is set we return the+ # raw string exactly as the user supplied it (no tilde expansion, no+ # path-separator normalization). This matches what existing tests and+ # users have relied on since the env var was introduced.env_path = os.environ.get(TOIN_PATH_ENV_VAR, "").strip()if env_path:return env_path- # Fall back to default path in user's home directory- home = Path.home()- return str(home / DEFAULT_TOIN_DIR / DEFAULT_TOIN_FILE)+ from headroom import paths as _paths++ return str(_paths.toin_path())# LOW FIX #22: Define callback types for metrics/monitoring hooks