Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
npx agentmods add skills/rhtevan/agentfs/headroom-litellm-proxynpx skills add rhtevan/agentfs --skill headroom-litellm-proxygit clone --depth 1 https://github.com/rhtevan/agentfsWrote this? Show the measurements
A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.
[](https://agentmods.dev/skills/rhtevan/agentfs/headroom-litellm-proxy)<a href="https://agentmods.dev/skills/rhtevan/agentfs/headroom-litellm-proxy"><img src="https://agentmods.dev/badge/skills/rhtevan/agentfs/headroom-litellm-proxy.svg" alt="Measured on agentmods" height="20"></a>What it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5.1 | $0.00021 | $0.02492 |
| Opus 5 | $0.00010 | $0.01246 |
| Sonnet 5 | $0.00004 | $0.00498 |
| Haiku 4.5 | $0.00002 | $0.00249 |
Grade C, and why
headroom-litellm-proxy scanned grade C with 2 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 6d ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Downloads and executes remote codehighSupply chain
curl | sh runs whatever the server returns today, which is not necessarily what it returned when this was reviewed.
- `uv` package manager installed (`curl -LsSf https://astral.sh/uv/install.sh | sh`) Makes network callslowCapability
Not a fault in itself. Listed so you know the mod talks to something, and to what.
- `uv` package manager installed (`curl -LsSf https://astral.sh/uv/install.sh | sh`) How it starts
The opening of the file, as written. The whole thing — 283 lines — stays where its author put it; the contents beside it link to each section on GitHub.
Headroom Proxy — Installation & Systemd Setup
Install the Headroom context-optimization proxy and run it as a systemd user-scope service, chained to a local LiteLLM proxy for upstream LLM access.
Traffic Chain
Any OpenAI-compatible client → Headroom Proxy (:8787) → LiteLLM (:4000) → Vertex AI (Claude)
↑ context compression ↑ model routing
Headroom exposes OpenAI-compatible endpoints (/v1/chat/completions) and
Anthropic-compatible endpoints (/v1/messages), so any client that
speaks either protocol can use it.
Prerequisites
- LiteLLM proxy running locally on port 4000 (see skill
litellm-vertex-ai-proxyto set one up; verify withlitellm-proxy-statusskill) uvpackage manager installed (curl -LsSf https://astral.sh/uv/install.sh | sh)
Workflow
Step 1 — Install Headroom
Install Headroom using uv:
uv tool install 'headroom-ai[proxy]'
Verify:
headroom --version
headroom proxy --help
If uv is not installed:
curl -LsSf https://astral.sh/uv/install.sh | sh
Step 2 — Create the Headroom Systemd Service
File: ~/.config/systemd/user/headroom-proxy.service
[Unit]
Description=Headroom Proxy - Context optimization layer for LLM traffic
After=litellm-proxy.service
Wants=litellm-proxy.service
[Service]
Type=simple
ExecStart=/home/<USER>/.local/bin/headroom proxy \
--host 127.0.0.1 \
--port 8787 \
--openai-api-url http://localhost:4000 \
--no-ccr-inject-tool \
--no-ccr-marker \
--no-telemetry \
--no-rate-limit \
--request-timeout-seconds 600 \
--mode token \
--target-ratio 0.5 \
--intercept-tool-results
Restart=on-failure
RestartSec=5
Environment=OPENAI_TARGET_API_URL=http://localhost:4000
Environment=HEADROOM_TELEMETRY=off
[Install]
WantedBy=default.target
Replace <USER> with your username.
Key Service Flags Explained
| Flag | Purpose |
|---|---|
--openai-api-url http://localhost:4000 |
Route upstream traffic to LiteLLM |
--no-ccr-inject-tool |
Don't inject CCR retrieve tool (downstream clients can't resolve it) |
--no-ccr-marker |
Don't add CCR markers to compressed content |
--no-telemetry |
Disable anonymous telemetry |
--no-rate-limit |
Disable rate limiting (local use) |
--mode token |
Prioritize token compression savings |
--target-ratio 0.5 |
Kompress compression target — keep ~50% of tokens in compressed turns (lower = more aggressive) |
--intercept-tool-results |
Compress stale tool result blocks (file reads, shell output, etc.) |
--request-timeout-seconds 600 |
10-minute timeout for long-running requests |
What ships with it
1 file beside SKILL.md in the same directory: the scripts, references and assets a skill reads on demand. Not counted in the per-session cost; read them before you install if any of them is executable.
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 6d ago First seen · 283 lines · 21 tokens per session scan C 29ea3b4cfcf8
headroom-litellm-proxy is a skill published in the GitHub repository rhtevan/agentfs (2 stars, last pushed yesterday), licensed Apache-2.0. It adds 21 tokens to every session and 2,492 once invoked, about $0.0001 per session on Opus 5. A static security scan graded it C with 2 findings (downloads and executes remote code, makes network calls). No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.
Other skills, from other repositories
tensorrt-llm
High-throughput LLM inference on NVIDIA GPUs.
agent-platform-tuning
Agent Platform Model Tuning. Use when you need to fine-tune open models or Gemini models using Agent Platform infrastructure. Don't use for model training outside Agent Platform, model deployment to endpoints (use agent-platform-deploy), or managing serving endpoints (use agent-platform-endpoint-management).
google-cloud-solution-guided-gke-ai-migration
Guides the migration of existing AI workloads (Cloud Run, Gemini API, Gemini Enterprise Agent Platform) to self-hosted GKE inference using gcloud and kubectl. Use when the user has an existing AI inference workload (on Cloud Run, the Gemini API, Gemini Enterprise Agent Platform, or a custom VM) and wants to move it to…
agent-platform-endpoint-management
Manages Agent Platform serving endpoints. Use when you need to create, list, describe, update, or delete serving endpoints for model deployment on Agent Platform. Also use when troubleshooting endpoint permission, quota, or resource busy errors. Don't use for deploying models to endpoints or for running model…
gke-inference
Deploys and optimizes AI/ML inference workloads on GKE, using GPUs, TPUs, and model servers. Use when deploying GKE inference servers, configuring GKE GPU resources for inference, or deploying LLMs on GKE. Don't use for generic batch jobs or HPC task queues (use gke-batch-hpc instead).
modal
Modal is a serverless cloud platform for running Python on demand, including on-demand GPUs. Use when deploying or serving AI/ML models, running GPU-accelerated workloads (training, fine-tuning, inference), serving web endpoints, scheduling batch jobs, or scaling Python code to cloud containers with the Modal SDK.