Skip to content

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.

refactor: migrate Python callsites to canonical paths module

JerrettDavis3a1bbbbc1444
diff --git a/headroom/ccr/mcp_server.py b/headroom/ccr/mcp_server.py
index a2172e4ef..569e04928 100644
--- a/headroom/ccr/mcp_server.py
+++ b/headroom/ccr/mcp_server.py
@@ -32,6 +32,8 @@ from dataclasses import dataclass, field
from pathlib import Path
from 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 Path
file_path = arguments.get("file_path", "")
fresh = arguments.get("fresh", False)
diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.py
index 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.py
index 500ce5e33..a0f6a3def 100644
--- a/headroom/install/paths.py
+++ b/headroom/install/paths.py
@@ -8,6 +8,8 @@ from pathlib import Path
import 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.py
index 0d50c1c48..fad523036 100644
--- a/headroom/install/planner.py
+++ b/headroom/install/planner.py
@@ -4,10 +4,11 @@ from __future__ import annotations
import shutil
from collections.abc import Iterable
-from pathlib import Path
import 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.py
index 5d69ff247..0225d757e 100644
--- a/headroom/memory/bridge_config.py
+++ b/headroom/memory/bridge_config.py
@@ -10,6 +10,8 @@ from dataclasses import dataclass, field
from enum import Enum
from 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 = False
export_path: Path | None = None
export_format: MarkdownFormat = MarkdownFormat.GENERIC
diff --git a/headroom/memory/easy.py b/headroom/memory/easy.py
index 7c6397030..737137b17 100644
--- a/headroom/memory/easy.py
+++ b/headroom/memory/easy.py
@@ -105,10 +105,12 @@ class Memory:
# Config for local backend
if 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_db
self._db_path = Path(db_path)
# Config for qdrant-neo4j backend
diff --git a/headroom/memory/sync.py b/headroom/memory/sync.py
index c568c16fd..4ab48dbc0 100644
--- a/headroom/memory/sync.py
+++ b/headroom/memory/sync.py
@@ -30,10 +30,13 @@ from datetime import datetime, timezone
from pathlib import Path
from 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.py
index bf06add0f..e89851c80 100644
--- a/headroom/perf/analyzer.py
+++ b/headroom/perf/analyzer.py
@@ -13,11 +13,12 @@ from __future__ import annotations
import logging
import re
from dataclasses import dataclass, field
-from pathlib import Path
+
+from headroom import paths as _paths
log = 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.py
index 556048196..70c2773d7 100644
--- a/headroom/providers/anthropic.py
+++ b/headroom/providers/anthropic.py
@@ -20,9 +20,10 @@ import json
import logging
import os
import warnings
-from pathlib import Path
from typing import Any, cast
+from headroom import paths as _paths
+
from .base import Provider, TokenCounter
LITELLM_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_models
if config_file.exists():
try:
with open(config_file) as f:
diff --git a/headroom/providers/openai.py b/headroom/providers/openai.py
index b2af317b5..beaa43644 100644
--- a/headroom/providers/openai.py
+++ b/headroom/providers/openai.py
@@ -13,9 +13,10 @@ import os
import warnings
from datetime import date
from functools import lru_cache
-from pathlib import Path
from typing import Any, cast
+from headroom import paths as _paths
+
from .base import Provider, TokenCounter
logger = 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_models
if 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 precedence
diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.py
index a130aa909..45659ff38 100644
--- a/headroom/proxy/handlers/anthropic.py
+++ b/headroom/proxy/handlers/anthropic.py
@@ -12,7 +12,6 @@ import logging
import os
import time
from datetime import datetime
-from pathlib import Path
from typing import TYPE_CHECKING, Any
if TYPE_CHECKING:
@@ -1073,7 +1072,9 @@ class AnthropicHandlerMixin:
# Dump full request details to debug file
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/handlers/openai.py b/headroom/proxy/handlers/openai.py
index a23d81c61..eb127ed71 100644
--- a/headroom/proxy/handlers/openai.py
+++ b/headroom/proxy/handlers/openai.py
@@ -14,7 +14,6 @@ import logging
import os
import time
from datetime import datetime
-from pathlib import Path
from typing import TYPE_CHECKING, Any
if 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.py
index e4d857133..f3e8b93b8 100644
--- a/headroom/proxy/helpers.py
+++ b/headroom/proxy/helpers.py
@@ -13,6 +13,8 @@ import logging
from pathlib import Path
from 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 RotatingFileHandler
try:
- _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.py
index 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 exist
self._native_memory_dir.mkdir(parents=True, exist_ok=True)
diff --git a/headroom/proxy/savings_tracker.py b/headroom/proxy/savings_tracker.py
index 6ffe263cc..1d115b53a 100644
--- a/headroom/proxy/savings_tracker.py
+++ b/headroom/proxy/savings_tracker.py
@@ -19,9 +19,11 @@ from io import StringIO
from pathlib import Path
from 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_ENV
DEFAULT_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.py
index 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__.py
index e9d9558dc..60632acd5 100644
--- a/headroom/rtk/__init__.py
+++ b/headroom/rtk/__init__.py
@@ -10,8 +10,10 @@ import platform
import shutil
from 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_NAME
diff --git a/headroom/subscription/tracker.py b/headroom/subscription/tracker.py
index 33dccab51..ce0bf9237 100644
--- a/headroom/subscription/tracker.py
+++ b/headroom/subscription/tracker.py
@@ -29,6 +29,7 @@ import threading
from pathlib import Path
from typing import Any
+from headroom import paths as _paths
from headroom.subscription.base import QuotaTracker
from headroom.subscription.client import SubscriptionClient
from 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.10
def _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.py
index eb800e1c7..cf72fab2d 100644
--- a/headroom/telemetry/reporter.py
+++ b/headroom/telemetry/reporter.py
@@ -29,6 +29,8 @@ from typing import TYPE_CHECKING, Any
import 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 days
GRACE_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()
@dataclass
diff --git a/headroom/telemetry/toin.py b/headroom/telemetry/toin.py
index 191b48efb..f6ef9f8be 100644
--- a/headroom/telemetry/toin.py
+++ b/headroom/telemetry/toin.py
@@ -50,7 +50,6 @@ import threading
import time
from collections.abc import Callable
from dataclasses import dataclass, field
-from pathlib import Path
from typing import Any, Literal
from .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