feat(plugins): headroom skill for Claude Code, Codex, Copilot and skills.sh (#4533)

## Description

In the unbranded sandbox run the agent never searched and wrote a
300-line trimmer by hand; nothing in its environment said Headroom
exists. An Agent Skill is the one artifact that fires on the job words
(cut input tokens, trim tool outputs, fit a context window) with zero
fetches. Four unofficial "headroom" skills already exist on skills.sh;
there is no official one.

Depends on #4529 for the `/docs/fastapi` link in the skill body.

## Type of Change

- [x] New feature (non-breaking change that adds functionality)

## Changes Made

- `skills/headroom/SKILL.md`: job-language description; body is the
no-key `compress()` path, the zero-network check, `model_limit` /
`protect_recent`, the TypeScript proxy caveat, the coding-agent path,
and a short do-not list (no savings claims, no `CompressionMiddleware`
for apps that call a provider, no `[all]` unless asked).
- `plugins/headroom-skill/`: the same SKILL.md under `skills/`,
`.claude-plugin/plugin.json` and `.github/plugin/plugin.json`
(identical), README with install lines for Claude Code, Copilot CLI and
`npx skills add`.
- Both marketplace manifests: `headroom-skill` entry, inserted after the
hooks plugin so `plugins[0]` stays as the existing tests expect.
- `scripts/version-sync.py` and `scripts/verify-versions.py`: the two
new manifests, so the next release PR passes the version gate.
`scripts/tests/test_version_sync.py` fixture and assertion extended;
`tests/test_release_workflows.py` gate list extended.
- `tests/test_plugin_manifests.py`: the two SKILL.md copies must be
byte-identical (the repo has no symlinks, for Windows checkouts),
frontmatter has `name: headroom`; the skill plugin's two manifests match
each other and the marketplace entry.

## Testing

- [x] Unit tests pass: `tests/test_plugin_manifests.py
scripts/tests/test_version_sync.py tests/test_release_workflows.py -k
"manifest or version or skill or sync"`: 30 passed
- [x] `ruff check` / `ruff format --check` on the touched Python
- [x] `python scripts/verify-versions.py`: "All versions aligned at
0.42.0"
- [x] Manual testing performed

### Test Output

```text
pytest tests/test_plugin_manifests.py scripts/tests/test_version_sync.py tests/test_release_workflows.py -k "manifest or version or skill or sync": 30 passed
python scripts/verify-versions.py: All versions aligned at 0.42.0
claude plugin validate .: ✔ Validation passed
```

## Real Behavior Proof

- Environment: macOS arm64, Claude Code CLI.
- Exact command / steps: `claude plugin validate .` at the repo root of
this branch.
- Observed result: `✔ Validation passed`. The only warning is
pre-existing and about `plugins/headroom-agent-hooks/README.md` lacking
a marketplace install line.
- Not tested: installing the plugin from the marketplace into a fresh
Claude Code or Copilot CLI session and triggering the skill on a real
task; skills.sh indexing (happens on their side once this is on `main`).

## Runtime Rollout Safety

- Rollout-managed feature(s): none; documentation and metadata only, no
runtime code path changes
- Minimum rollout channel: n/a
- Stable/default behavior changed: no
- Kill switch / disable path: n/a (revert the PR)
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert the commit

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
This commit is contained in:
Tejas Chopra
2026-11-03 23:43:21 -06:00
committed by GitHub
co-authored by Claude Fable 5.1 JD Davis
parent aaab338b64
commit 66e1467682
12 changed files with 301 additions and 4 deletions
+22
View File
@@ -26,6 +26,28 @@
"copilot-cli"
]
},
{
"name": "headroom-skill",
"source": "./plugins/headroom-skill",
"description": "Skill: add headroom-ai compress() to a Python or TypeScript app to cut LLM input tokens (tool outputs, logs, JSON, chat history). No API key.",
"version": "0.42.0",
"author": {
"name": "Headroom Contributors",
"url": "https://github.com/headroomlabs-ai/headroom"
},
"homepage": "https://github.com/headroomlabs-ai/headroom",
"repository": "https://github.com/headroomlabs-ai/headroom",
"keywords": [
"headroom",
"skill",
"token-cost",
"tool-outputs",
"context-window",
"claude-code",
"codex",
"copilot-cli"
]
},
{
"name": "headroom-snip",
"source": "./plugins/headroom-snip",
+22
View File
@@ -25,6 +25,28 @@
"claude-code",
"copilot-cli"
]
},
{
"name": "headroom-skill",
"source": "./plugins/headroom-skill",
"description": "Skill: add headroom-ai compress() to a Python or TypeScript app to cut LLM input tokens (tool outputs, logs, JSON, chat history). No API key.",
"version": "0.42.0",
"author": {
"name": "Headroom Contributors",
"url": "https://github.com/headroomlabs-ai/headroom"
},
"homepage": "https://github.com/headroomlabs-ai/headroom",
"repository": "https://github.com/headroomlabs-ai/headroom",
"keywords": [
"headroom",
"skill",
"token-cost",
"tool-outputs",
"context-window",
"claude-code",
"codex",
"copilot-cli"
]
}
]
}
@@ -0,0 +1,21 @@
{
"name": "headroom-skill",
"version": "0.42.0",
"description": "Skill: add headroom-ai compress() to a Python or TypeScript app to cut LLM input tokens (tool outputs, logs, JSON, chat history). No API key.",
"author": {
"name": "Headroom Contributors",
"url": "https://github.com/headroomlabs-ai/headroom"
},
"homepage": "https://github.com/headroomlabs-ai/headroom",
"repository": "https://github.com/headroomlabs-ai/headroom",
"keywords": [
"headroom",
"skill",
"token-cost",
"tool-outputs",
"context-window",
"claude-code",
"codex",
"copilot-cli"
]
}
+21
View File
@@ -0,0 +1,21 @@
{
"name": "headroom-skill",
"version": "0.42.0",
"description": "Skill: add headroom-ai compress() to a Python or TypeScript app to cut LLM input tokens (tool outputs, logs, JSON, chat history). No API key.",
"author": {
"name": "Headroom Contributors",
"url": "https://github.com/headroomlabs-ai/headroom"
},
"homepage": "https://github.com/headroomlabs-ai/headroom",
"repository": "https://github.com/headroomlabs-ai/headroom",
"keywords": [
"headroom",
"skill",
"token-cost",
"tool-outputs",
"context-window",
"claude-code",
"codex",
"copilot-cli"
]
}
+14
View File
@@ -0,0 +1,14 @@
# headroom-skill
An [Agent Skill](https://agentskills.io) that teaches a coding agent when and how
to add `headroom-ai` to an app: the job words it fires on (cut input tokens,
trim tool outputs, fit a context window), the one `compress()` call, the
zero-network check, and what not to do. The skill body is `skills/headroom/SKILL.md`;
the repo-root copy at `/skills/headroom/SKILL.md` is the same file, kept in step
by `tests/test_plugin_manifests.py`.
Install:
- Claude Code: `/plugin marketplace add headroomlabs-ai/headroom` then `/plugin install headroom-skill@headroom-marketplace`
- Copilot CLI: `copilot plugin marketplace add headroomlabs-ai/headroom` then `copilot plugin install headroom-skill@headroom-marketplace`
- Any agent that reads `skills/`: `npx skills add headroomlabs-ai/headroom`
@@ -0,0 +1,70 @@
---
name: headroom
description: Use when a Python or TypeScript app sends large tool outputs, logs, JSON, search results or long chat history to an LLM and the task is to cut input tokens, reduce token cost, fit a context window, or trim tool results without losing errors. Adds the headroom-ai compress() call; in-process, no API key, no model download.
---
# Headroom: compress LLM context before the call
## When this applies
The user asks to reduce LLM token cost, trim or compress tool outputs or tool
results, prune or summarize chat history, fit a prompt into a context window, or
stop large logs or JSON from blowing up the prompt. Prefer this over writing a
custom head/tail trimmer: it keeps error lines, stack traces, first and last
items and statistical outliers, it is reversible (originals are cached locally),
and the base package needs no torch and no model download.
## Python (in-process, no network)
```bash
pip install headroom-ai # add to requirements.txt / pyproject
```
```python
from headroom import compress
result = compress(messages, model=MODEL_NAME) # OpenAI or Anthropic message dicts
# call the provider with result.messages instead of messages
# log result.tokens_before, result.tokens_after, result.tokens_saved
```
Compression applies to `tool` (and assistant) messages. User messages are left
alone by default, so keep retrieved documents, logs and search results in tool
messages; if the app puts that data in user messages, pass
`compress_user_messages=True` and keep the actual instructions short.
Verify without a provider key:
```bash
HEADROOM_OFFLINE=1 python -c "from headroom import compress; log='\n'.join(f'INFO step {i} ok' for i in range(3000))+'\nFATAL disk full'; r=compress([{'role':'user','content':'What failed?'},{'role':'assistant','content':None,'tool_calls':[{'id':'c1','type':'function','function':{'name':'logs','arguments':'{}'}}]},{'role':'tool','tool_call_id':'c1','content':log}], model='gpt-4o'); print(r.tokens_before, '->', r.tokens_after, 'FATAL kept:', 'FATAL' in str(r.messages))"
```
Set `HEADROOM_OFFLINE=1` in CI and sandboxes: it blocks the update check,
model and pricing-table downloads and the beacon. `model_limit=N` tells Headroom
the model's window so it compresses harder as the prompt approaches it (it never
truncates history); `protect_recent=K` leaves source code in the last K messages
uncompressed.
## TypeScript
`npm install headroom-ai` gives `compress()` and `withHeadroom()` wrappers for
the OpenAI, Anthropic, Gemini and Vercel AI SDK clients, but compression runs in
the Python proxy: start it first with `pip install "headroom-ai[proxy]"` and
`headroom proxy --port 8787`. If a Python sidecar is not acceptable, say so and
stop.
## Coding agents
To cut tokens for Claude Code, Codex, Cursor or Copilot themselves (not an
app): `uv tool install --python 3.13 "headroom-ai[all]"` then
`headroom wrap claude`.
## Do not
- Do not claim a savings percentage; print `tokens_before` and `tokens_after`.
- Do not use `headroom.integrations.asgi.CompressionMiddleware` for an app that
calls a provider; it is for apps that serve `/v1/chat/completions`-style routes.
- Do not install `[all]` or `[ml]` unless asked; the base package is enough.
Docs index: https://docs.headroomlabs.ai/llms.txt · FastAPI example:
https://docs.headroomlabs.ai/docs/fastapi · Repo: https://github.com/headroomlabs-ai/headroom
+11
View File
@@ -30,6 +30,10 @@ def temp_project(tmp_path: Path) -> dict[str, Path]:
agent_hooks_github.mkdir(parents=True)
snip_claude = plugins / "headroom-snip" / ".claude-plugin"
snip_claude.mkdir(parents=True)
skill_claude = plugins / "headroom-skill" / ".claude-plugin"
skill_claude.mkdir(parents=True)
skill_github = plugins / "headroom-skill" / ".github" / "plugin"
skill_github.mkdir(parents=True)
sdk = root / "sdk"
typescript = sdk / "typescript"
typescript.mkdir(parents=True)
@@ -94,6 +98,10 @@ def temp_project(tmp_path: Path) -> dict[str, Path]:
snip_plugin = snip_claude / "plugin.json"
snip_plugin.write_text(json.dumps({"name": "headroom-snip", "version": "0.1.0"}))
skill_plugins = [skill_claude / "plugin.json", skill_github / "plugin.json"]
for manifest in skill_plugins:
manifest.write_text(json.dumps({"name": "headroom-skill", "version": "0.1.0"}))
# sdk/typescript/package.json
typescript_pkg = typescript / "package.json"
typescript_pkg.write_text(json.dumps({"name": "test", "version": "0.5.25"}))
@@ -122,6 +130,7 @@ def temp_project(tmp_path: Path) -> dict[str, Path]:
"repo_github_marketplace": repo_github_marketplace,
"claude_plugin": claude_plugin,
"snip_plugin": snip_plugin,
"skill_plugins": skill_plugins,
"github_plugin": github_plugin,
"typescript_pkg": typescript_pkg,
"server_json": server_json,
@@ -351,6 +360,8 @@ def test_plugin_manifests_only_leaves_package_versions_unchanged(
assert json.loads(temp_project["typescript_pkg"].read_text())["version"] == "0.5.25"
assert json.loads(temp_project["claude_plugin"].read_text())["version"] == "0.8.0"
assert json.loads(temp_project["snip_plugin"].read_text())["version"] == "0.8.0"
for manifest in temp_project["skill_plugins"]:
assert json.loads(manifest.read_text())["version"] == "0.8.0"
assert (
json.loads(temp_project["repo_github_marketplace"].read_text())["metadata"]["version"]
== "0.8.0"
+6
View File
@@ -51,6 +51,12 @@ def main() -> None:
"plugins/headroom-agent-hooks/.github/plugin/plugin.json": _read_json_version(
ROOT / "plugins/headroom-agent-hooks/.github/plugin/plugin.json"
),
"plugins/headroom-skill/.claude-plugin/plugin.json": _read_json_version(
ROOT / "plugins/headroom-skill/.claude-plugin/plugin.json"
),
"plugins/headroom-skill/.github/plugin/plugin.json": _read_json_version(
ROOT / "plugins/headroom-skill/.github/plugin/plugin.json"
),
}
versions.update(_read_marketplace_versions(ROOT / ".claude-plugin/marketplace.json"))
versions.update(_read_marketplace_versions(ROOT / ".github/plugin/marketplace.json"))
+6
View File
@@ -110,6 +110,12 @@ def update_plugin_versions(root: Path, version: str) -> None:
update_plugin_manifest(
root / "plugins" / "headroom-snip" / ".claude-plugin" / "plugin.json", version
)
update_plugin_manifest(
root / "plugins" / "headroom-skill" / ".claude-plugin" / "plugin.json", version
)
update_plugin_manifest(
root / "plugins" / "headroom-skill" / ".github" / "plugin" / "plugin.json", version
)
def update_openclaw_package_json(file_path: Path, version: str) -> None:
+70
View File
@@ -0,0 +1,70 @@
---
name: headroom
description: Use when a Python or TypeScript app sends large tool outputs, logs, JSON, search results or long chat history to an LLM and the task is to cut input tokens, reduce token cost, fit a context window, or trim tool results without losing errors. Adds the headroom-ai compress() call; in-process, no API key, no model download.
---
# Headroom: compress LLM context before the call
## When this applies
The user asks to reduce LLM token cost, trim or compress tool outputs or tool
results, prune or summarize chat history, fit a prompt into a context window, or
stop large logs or JSON from blowing up the prompt. Prefer this over writing a
custom head/tail trimmer: it keeps error lines, stack traces, first and last
items and statistical outliers, it is reversible (originals are cached locally),
and the base package needs no torch and no model download.
## Python (in-process, no network)
```bash
pip install headroom-ai # add to requirements.txt / pyproject
```
```python
from headroom import compress
result = compress(messages, model=MODEL_NAME) # OpenAI or Anthropic message dicts
# call the provider with result.messages instead of messages
# log result.tokens_before, result.tokens_after, result.tokens_saved
```
Compression applies to `tool` (and assistant) messages. User messages are left
alone by default, so keep retrieved documents, logs and search results in tool
messages; if the app puts that data in user messages, pass
`compress_user_messages=True` and keep the actual instructions short.
Verify without a provider key:
```bash
HEADROOM_OFFLINE=1 python -c "from headroom import compress; log='\n'.join(f'INFO step {i} ok' for i in range(3000))+'\nFATAL disk full'; r=compress([{'role':'user','content':'What failed?'},{'role':'assistant','content':None,'tool_calls':[{'id':'c1','type':'function','function':{'name':'logs','arguments':'{}'}}]},{'role':'tool','tool_call_id':'c1','content':log}], model='gpt-4o'); print(r.tokens_before, '->', r.tokens_after, 'FATAL kept:', 'FATAL' in str(r.messages))"
```
Set `HEADROOM_OFFLINE=1` in CI and sandboxes: it blocks the update check,
model and pricing-table downloads and the beacon. `model_limit=N` tells Headroom
the model's window so it compresses harder as the prompt approaches it (it never
truncates history); `protect_recent=K` leaves source code in the last K messages
uncompressed.
## TypeScript
`npm install headroom-ai` gives `compress()` and `withHeadroom()` wrappers for
the OpenAI, Anthropic, Gemini and Vercel AI SDK clients, but compression runs in
the Python proxy: start it first with `pip install "headroom-ai[proxy]"` and
`headroom proxy --port 8787`. If a Python sidecar is not acceptable, say so and
stop.
## Coding agents
To cut tokens for Claude Code, Codex, Cursor or Copilot themselves (not an
app): `uv tool install --python 3.13 "headroom-ai[all]"` then
`headroom wrap claude`.
## Do not
- Do not claim a savings percentage; print `tokens_before` and `tokens_after`.
- Do not use `headroom.integrations.asgi.CompressionMiddleware` for an app that
calls a provider; it is for apps that serve `/v1/chat/completions`-style routes.
- Do not install `[all]` or `[ml]` unless asked; the base package is enough.
Docs index: https://docs.headroomlabs.ai/llms.txt · FastAPI example:
https://docs.headroomlabs.ai/docs/fastapi · Repo: https://github.com/headroomlabs-ai/headroom
+35 -4
View File
@@ -3,6 +3,8 @@ from __future__ import annotations
import json
from pathlib import Path
import pytest
REPO_ROOT = Path(__file__).resolve().parents[1]
@@ -38,15 +40,19 @@ def test_claude_code_only_plugins_are_listed_and_versioned() -> None:
assert (plugin_root / "hooks" / "hooks.json").is_file()
def test_plugin_manifests_share_core_metadata() -> None:
claude = _load_json("plugins/headroom-agent-hooks/.claude-plugin/plugin.json")
copilot = _load_json("plugins/headroom-agent-hooks/.github/plugin/plugin.json")
@pytest.mark.parametrize("plugin", ["headroom-agent-hooks", "headroom-skill"])
def test_plugin_manifests_share_core_metadata(plugin: str) -> None:
claude = _load_json(f"plugins/{plugin}/.claude-plugin/plugin.json")
copilot = _load_json(f"plugins/{plugin}/.github/plugin/plugin.json")
assert isinstance(claude, dict)
assert isinstance(copilot, dict)
for key in ("name", "version", "description", "author", "homepage", "repository", "keywords"):
assert claude[key] == copilot[key]
assert "hooks" not in claude
assert copilot["hooks"] == "./hooks"
if plugin == "headroom-agent-hooks":
assert copilot["hooks"] == "./hooks"
else:
assert "hooks" not in copilot
def test_plugin_hooks_timeout_exceeds_cold_start_wait() -> None:
@@ -112,3 +118,28 @@ def test_plugin_hooks_share_anchored_launcher_and_rootless_tail() -> None:
launcher = REPO_ROOT / "plugins/headroom-agent-hooks/bin/headroom-hook.sh"
assert launcher.is_file()
assert b"\r" not in launcher.read_bytes()
def test_skill_plugin_ships_the_repo_root_skill() -> None:
"""The skill is published twice: at `skills/headroom` for skills.sh / Codex /
Cursor, which read the repo root, and inside the plugin for the Claude Code
and Copilot marketplaces, which read the plugin root. No symlinks (Windows
checkouts), so this test is what keeps the two copies identical."""
root_skill = REPO_ROOT / "skills" / "headroom" / "SKILL.md"
plugin_skill = REPO_ROOT / "plugins" / "headroom-skill" / "skills" / "headroom" / "SKILL.md"
assert root_skill.read_bytes() == plugin_skill.read_bytes()
head = root_skill.read_text(encoding="utf-8").split("---")[1]
assert "name: headroom\n" in head
assert "description: " in head
def test_skill_plugin_manifests_match_marketplace() -> None:
marketplace = _load_json(".claude-plugin/marketplace.json")
assert isinstance(marketplace, dict)
entry = next(p for p in marketplace["plugins"] if p["name"] == "headroom-skill")
claude = _load_json("plugins/headroom-skill/.claude-plugin/plugin.json")
assert isinstance(claude, dict)
for key in ("name", "version", "description", "author", "homepage", "repository", "keywords"):
assert claude[key] == entry[key]
assert entry["version"] == marketplace["metadata"]["version"]
assert (REPO_ROOT / entry["source"] / "skills" / "headroom" / "SKILL.md").is_file()
+3
View File
@@ -1813,6 +1813,8 @@ def test_version_sync_covers_every_file_the_verifier_gates() -> None:
"sdk/typescript/package.json",
"plugins/headroom-agent-hooks/.claude-plugin/plugin.json",
"plugins/headroom-agent-hooks/.github/plugin/plugin.json",
"plugins/headroom-skill/.claude-plugin/plugin.json",
"plugins/headroom-skill/.github/plugin/plugin.json",
"marketplace.json",
]
for path in gated:
@@ -1823,6 +1825,7 @@ def test_version_sync_covers_every_file_the_verifier_gates() -> None:
"openclaw",
"typescript",
"headroom-agent-hooks",
"headroom-skill",
"marketplace.json",
"server.json",
]: