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
{
"description": "Cases both languages are checked against so Rust's hf_hub_cache_dir() names the directory huggingface_hub would. tests/test_fastembed_pinned_snapshot.py checks them against Python's posixpath/ntpath and huggingface_hub.constants; crates/headroom-core/src/hf_cache.rs checks its port against the same file.",
"expandvars": {
"comment": "posix = posixpath.expandvars, nt = ntpath.expandvars, with env set and unset absent (identical on CPython 3.10, 3.11, 3.13).",
"env": {
"HEADROOM_EV_A": "x",
"HEADROOM_EV_B_C": "y$HEADROOM_EV_A",
"HEADROOM_EV_D-E": "z"
},
"unset": "HEADROOM_EV_UNSET",
"cases": [
{
"input": "plain/path",
"posix": "plain/path",
"nt": "plain/path"
},
{
"input": "$HEADROOM_EV_A",
"posix": "x",
"nt": "x"
},
{
"input": "${HEADROOM_EV_A}",
"posix": "x",
"nt": "x"
},
{
"input": "$HEADROOM_EV_A/$HEADROOM_EV_B_C",
"posix": "x/y$HEADROOM_EV_A",
"nt": "x/y$HEADROOM_EV_A"
},
{
"input": "$$HEADROOM_EV_A",
"posix": "$x",
"nt": "$HEADROOM_EV_A"
},
{
"input": "$",
"posix": "$",
"nt": "$"
},
{
"input": "a$",
"posix": "a$",
"nt": "a$"
},
{
"input": "$/x",
"posix": "$/x",
"nt": "$/x"
},
{
"input": "${HEADROOM_EV_A",
"posix": "${HEADROOM_EV_A",
"nt": "${HEADROOM_EV_A"
},
{
"input": "${}",
"posix": "${}",
"nt": "${}"
},
{
"input": "$HEADROOM_EV_UNSET/x",
"posix": "$HEADROOM_EV_UNSET/x",
"nt": "$HEADROOM_EV_UNSET/x"
},
{
"input": "${HEADROOM_EV_UNSET}/x",
"posix": "${HEADROOM_EV_UNSET}/x",
"nt": "${HEADROOM_EV_UNSET}/x"
},
{
"input": "%HEADROOM_EV_A%/x",
"posix": "%HEADROOM_EV_A%/x",
"nt": "x/x"
},
{
"input": "%%HEADROOM_EV_A%%",
"posix": "%%HEADROOM_EV_A%%",
"nt": "%HEADROOM_EV_A%"
},
{
"input": "%HEADROOM_EV_A",
"posix": "%HEADROOM_EV_A",
"nt": "%HEADROOM_EV_A"
},
{
"input": "%HEADROOM_EV_UNSET%/x",
"posix": "%HEADROOM_EV_UNSET%/x",
"nt": "%HEADROOM_EV_UNSET%/x"
},
{
"input": "'$HEADROOM_EV_A'/$HEADROOM_EV_A",
"posix": "'x'/x",
"nt": "'$HEADROOM_EV_A'/x"
},
{
"input": "'$HEADROOM_EV_A",
"posix": "'x",
"nt": "'$HEADROOM_EV_A"
},
{
"input": "$HEADROOM_EV_D-E",
"posix": "$HEADROOM_EV_D-E",
"nt": "z"
},
{
"input": "${HEADROOM_EV_D-E}",
"posix": "z",
"nt": "z"
},
{
"input": "$HEADROOM_EV_A-x",
"posix": "x-x",
"nt": "$HEADROOM_EV_A-x"
},
{
"input": "~$HEADROOM_EV_A",
"posix": "~x",
"nt": "~x"
},
{
"input": "é/$HEADROOM_EV_A/é",
"posix": "é/x/é",
"nt": "é/x/é"
}
]
},
"cache_dir": {
"comment": "{root} and {home} are temporary directories; HOME and USERPROFILE are set to {home}, every other cache variable is cleared first. expected may be {posix, nt}.",
"probe_vars": [
"HEADROOM_HF_PROBE_ROOT",
"HEADROOM_HF_PROBE_UNSET",
"HF_TOKEN",
"HF_TOKEN_PATH",
"HUGGING_FACE_HUB_TOKEN"
],
"cases": [
{
"name": "HF_HUB_CACHE through ${VAR} (the #4190 review case)",
"env": {
"HEADROOM_HF_PROBE_ROOT": "{root}",
"HF_HUB_CACHE": "${HEADROOM_HF_PROBE_ROOT}/hub"
},
"expected": "{root}/hub"
},
{
"name": "HF_HUB_CACHE through $VAR",
"env": {
"HEADROOM_HF_PROBE_ROOT": "{root}",
"HF_HUB_CACHE": "$HEADROOM_HF_PROBE_ROOT/hub"
},
"expected": "{root}/hub"
},
{
"name": "legacy HUGGINGFACE_HUB_CACHE through ${VAR}",
"env": {
"HEADROOM_HF_PROBE_ROOT": "{root}",
"HUGGINGFACE_HUB_CACHE": "${HEADROOM_HF_PROBE_ROOT}/legacy"
},
"expected": "{root}/legacy"
},
{
"name": "HF_HOME through ${VAR}",
"env": {
"HEADROOM_HF_PROBE_ROOT": "{root}",
"HF_HOME": "${HEADROOM_HF_PROBE_ROOT}/hf-home"
},
"expected": "{root}/hf-home/hub"
},
{
"name": "XDG_CACHE_HOME through ${VAR}",
"env": {
"HEADROOM_HF_PROBE_ROOT": "{root}",
"XDG_CACHE_HOME": "${HEADROOM_HF_PROBE_ROOT}/xdg"
},
"expected": "{root}/xdg/huggingface/hub"
},
{
"name": "HF_HUB_CACHE still wins over an expanded HF_HOME",
"env": {
"HEADROOM_HF_PROBE_ROOT": "{root}",
"HF_HOME": "${HEADROOM_HF_PROBE_ROOT}/hf-home",
"HF_HUB_CACHE": "{root}/explicit"
},
"expected": "{root}/explicit"
},
{
"name": "an unset variable stays literal",
"env": {
"HF_HUB_CACHE": "{root}/${HEADROOM_HF_PROBE_UNSET}/hub"
},
"expected": "{root}/${HEADROOM_HF_PROBE_UNSET}/hub"
},
{
"name": "leading ~ in HF_HUB_CACHE",
"env": {
"HF_HUB_CACHE": "~/models"
},
"expected": "{home}/models"
},
{
"name": "leading ~ in HF_HOME",
"env": {
"HF_HOME": "~/hf"
},
"expected": "{home}/hf/hub"
},
{
"name": "a ~ that a variable produces in HF_HUB_CACHE stays literal (expanduser runs first)",
"env": {
"HEADROOM_HF_PROBE_ROOT": "~/r",
"HF_HUB_CACHE": "${HEADROOM_HF_PROBE_ROOT}/hub"
},
"expected": "~/r/hub"
},
{
"name": "a ~ that a variable produces in HF_HOME expands on the second pass",
"env": {
"HEADROOM_HF_PROBE_ROOT": "~/r",
"HF_HOME": "${HEADROOM_HF_PROBE_ROOT}/hf"
},
"expected": "{home}/r/hf/hub"
},
{
"name": "%VAR% is a variable on Windows only",
"env": {
"HEADROOM_HF_PROBE_ROOT": "{root}",
"HF_HUB_CACHE": "%HEADROOM_HF_PROBE_ROOT%/hub"
},
"expected": {
"posix": "%HEADROOM_HF_PROBE_ROOT%/hub",
"nt": "{root}/hub"
}
},
{
"name": "an empty HF_HUB_CACHE is the working directory, not HF_HOME (the #4438 review case)",
"env": {
"HF_HUB_CACHE": "",
"HF_HOME": "{root}/fallback-home"
},
"expected": ""
},
{
"name": "an empty legacy HUGGINGFACE_HUB_CACHE is the working directory",
"env": {
"HUGGINGFACE_HUB_CACHE": "",
"HF_HOME": "{root}/fallback-home"
},
"expected": ""
},
{
"name": "an empty HF_HUB_CACHE still wins over a set legacy HUGGINGFACE_HUB_CACHE",
"env": {
"HF_HUB_CACHE": "",
"HUGGINGFACE_HUB_CACHE": "{root}/legacy"
},
"expected": ""
},
{
"name": "an empty HF_HOME is hub under the working directory, not XDG_CACHE_HOME",
"env": {
"HF_HOME": "",
"XDG_CACHE_HOME": "{root}/xdg"
},
"expected": "hub"
},
{
"name": "an empty XDG_CACHE_HOME is huggingface/hub under the working directory, not the home default",
"env": {
"XDG_CACHE_HOME": ""
},
"expected": "huggingface/hub"
},
{
"name": "nothing set: the default under the home directory",
"env": {},
"expected": "{home}/.cache/huggingface/hub"
}
]
},
"token": {
"comment": "huggingface_hub.get_token(): env, files written first ({root}/{home} as in cache_dir), expected token or null. HF_TOKEN, HUGGING_FACE_HUB_TOKEN and HF_TOKEN_PATH are cleared with the cache variables.",
"cases": [
{
"name": "HF_TOKEN wins over the login file",
"env": {
"HF_TOKEN": "hf_env"
},
"files": {
"{home}/.cache/huggingface/token": "hf_file"
},
"expected": "hf_env"
},
{
"name": "the legacy HUGGING_FACE_HUB_TOKEN",
"env": {
"HUGGING_FACE_HUB_TOKEN": "hf_legacy"
},
"files": {},
"expected": "hf_legacy"
},
{
"name": "an empty HF_TOKEN falls through to the legacy name",
"env": {
"HF_TOKEN": "",
"HUGGING_FACE_HUB_TOKEN": "hf_legacy"
},
"files": {},
"expected": "hf_legacy"
},
{
"name": "a whitespace-only HF_TOKEN is still the one picked, so the legacy name is skipped",
"env": {
"HF_TOKEN": " ",
"HUGGING_FACE_HUB_TOKEN": "hf_legacy"
},
"files": {
"{home}/.cache/huggingface/token": "hf_file"
},
"expected": "hf_file"
},
{
"name": "the login file under the default HF_HOME, cleaned",
"env": {},
"files": {
"{home}/.cache/huggingface/token": " hf_file\r\n"
},
"expected": "hf_file"
},
{
"name": "the login file under HF_HOME",
"env": {
"HF_HOME": "{root}/hf"
},
"files": {
"{root}/hf/token": "hf_home"
},
"expected": "hf_home"
},
{
"name": "HF_TOKEN_PATH through ${VAR}",
"env": {
"HEADROOM_HF_PROBE_ROOT": "{root}",
"HF_TOKEN_PATH": "${HEADROOM_HF_PROBE_ROOT}/tok"
},
"files": {
"{root}/tok": "hf_path"
},
"expected": "hf_path"
},
{
"name": "moving the hub cache does not move the token",
"env": {
"HF_HUB_CACHE": "{root}/elsewhere/hub"
},
"files": {
"{home}/.cache/huggingface/token": "hf_file",
"{root}/elsewhere/token": "hf_wrong"
},
"expected": "hf_file"
},
{
"name": "a blank login file is no token",
"env": {},
"files": {
"{home}/.cache/huggingface/token": " \n"
},
"expected": null
},
{
"name": "nothing set",
"env": {},
"files": {},
"expected": null
}
]
}
}