headroom
Evaluate or integrate Headroom for large repetitive tool outputs, JSON, logs, or retrieved context. Use when the user names Headroom or asks to measure context compression in an application they control. Start with a local library trial; not a default proxy, provider switch, prose-shortening mode, or solution for an ordinary small command result.
- License 许可
- Unlicense
- 所属仓库
- saski/arnesto
- 最近更新
- 2026-11-12
- Stars
- ★ 6
- Forks
- 0
01 前言 Front Matter
- name
- headroom
- description
- Evaluate or integrate Headroom for large repetitive tool outputs, JSON, logs, or retrieved context. Use when the user names Headroom or asks to measure context compression in an application they control. Start with a local library trial; not a default proxy, provider switch, prose-shortening mode, or solution for an ordinary small command result.
02 资源文件 2
- 脚本references/local-smoke.py2.7 KB
- 参考文档references/local-trial.md3.4 KB
03 SKILL.md 正文
Headroom
Treat compression as a transformation that must preserve task-critical evidence. Start with a synthetic local example, then compare representative payloads before changing any running agent's request path.
Choose the integration
- Prefer upstream query filtering, bounded reads, or RTK for simple shell output. Avoid stacking compressors without measuring the combined result.
- Use the Python library when the application owns the request payload. The
reviewed package is
headroom-ai==0.39.1, requiring Python 3.10 or newer. - A proxy,
headroom wrap, or MCP installation is a separate integration: those paths can change provider routing, credentials handling, configuration, and stored context. Inspect those changes before applying them; this skill does not authorize a client migration or imply desktop-client compatibility.
Start locally
Use the project's dependency manager, or an isolated environment for a trial.
Install the pinned base package, not [all], for the example in
local trial. Disable telemetry and update checks
before running it. The example uses no API key and makes no LLM request.
from headroom import CompressConfig, compress
result = compress(
messages,
model="gpt-4o", # Tokenizer selection for this example; no model request.
config=CompressConfig(
kompress_model="disabled",
compress_system_messages=False,
compress_user_messages=False,
protect_recent=4,
),
)
Use the actual target model's supported tokenizer for a real evaluation. A first tokenizer load can require a vocabulary download. Do not report estimated counts as measured tokens. Disabling Kompress avoids its ML-model download; it does not make initial package/tokenizer installation offline.
Check evidence preservation
- Retain the original payload separately. Library compression is lossy; full retrieval requires a working retained store and retrieval integration.
- Verify system instructions, current user intent, and recent messages remain intact. Protect tool-call IDs, relevant errors, rare outliers, and exact data needed by the task. Do not truncate away permission or policy information.
- Compare downstream answers and required assertions with and without compression. Token reduction alone is not success.
- If data is missing, counts are estimates, the store is unavailable, or correctness regresses, use the original payload and report the limitation.
Report and contain the trial
Report package version, configuration, original and compressed token counts, preservation checks, and whether a provider was actually tested. Keep cache, logs, retained payloads, and databases outside Git. In-memory retrieval ends with the process; do not promise reversible recovery after it exits.
Arnesto supplies this optional runbook. It does not enable a proxy, install an MCP server, change OmniRoute, or claim end-to-end savings from a local fixture.
04 同仓库更多 Skills
visualize
Use /visualize for creating compact charts, diagrams, or other visuals inline as part of the conversation itself. It chooses among Markdown tables, Mermaid, inline HTML, and other supported in-transcript forms. Use Canvas for durable artifacts outside the transcript that users may revisit, refine, or share.
update-cursor-settings
Modify Cursor/VSCode user settings in settings.json. Use when you want to change editor settings, preferences, configuration, themes, font size, tab size, format on save, auto save, keybindings, or any settings.json values.
update-cli-config
View and modify Cursor CLI configuration settings in ~/.cursor/cli-config.json. Use when the user wants to change CLI settings, configure permissions, switch approval mode, enable vim mode, toggle display options, configure sandbox, or manage any CLI preferences.
statusline
Configure a custom status line in the CLI. Use when the user mentions status line, statusline, statusLine, CLI status bar, prompt footer customization, or wants to add session context above the prompt.
split-to-prs
Split current work into small reviewable PRs. Use when the user asks to split a chat, set of changes, branch, or PR.
shell
Runs the rest of a /shell request as a literal shell command. Use only when the user explicitly invokes /shell and wants the following text executed directly in the terminal.