Menu
Use when deciding whether to install, enable, or troubleshoot Headroom context compression for local AI agent workflows, especially MCP, proxy, or agent-wrap usage.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | headroom |
| description | Use when deciding whether to install, enable, or troubleshoot Headroom context compression for local AI agent workflows, especially MCP, proxy, or agent-wrap usage. |
Headroom is a local-first context compression layer for AI agents. Use it when you need to reduce tokens before prompts, tool outputs, logs, RAG chunks, files, or conversation history reach the model.
Treat Headroom as model-facing context compression:
Install and enable Headroom only on developer machines where the extra runtime cost is acceptable:
Do not install or enable Headroom on Raspberry Pi or Linux ARM targets unless the user explicitly asks for it.
Manage Headroom through the user-global mise configuration under ~/.config/mise, not through repository-local tool declarations.
Preferred package:
[tools]
"pipx:headroom-ai" = { version = "0.26.0", extras = "mcp,proxy" }
Place that tool only in OS-specific mise config files that target Windows, WSL, or macOS. Keep it out of config.pi.toml.
Use Headroom when the user asks for:
For normal tests, builds, git, package manager, and log commands, prefer raw commands or tool-native quiet options.
headroom learn write to AGENTS.md, CLAUDE.md, or other guidance files without reviewing the exact diff.After installation, verify the local command is available:
headroom --help
For MCP/proxy exploration, prefer a dry, explicit test before wiring it into persistent agent configuration:
headroom proxy --help
headroom mcp --help
Route work in the `~/.apm` global APM workspace: decide what owns a change, which path is the source of truth, and which APM rollout / `mise` task to run. Use for skill update and redistribution requests (`skillアップデートして再配布して`, `再配布`), `apm.yml` / `apm.lock.yaml` and managed catalog rollout, manual-skills package state, orphaned APM packages, checked-out external dependency repositories, optional repository-scoped skill packages, and `apmのバージョンあげて` / pinned `apm` source checks. For skill body, description, script, reference, or asset design itself, coordinate with `skill-creator`; for general mise usage outside the APM workspace (including `mise upgrade TOOL` and `minimum_release_age`), use `mise`.
Use when adding or reviewing CI-stability hooks and gates: Lefthook/pre-commit/pre-push configuration, aligning local push gates with GitHub Actions, deciding commit-vs-push gate scope, or migrating pre-commit to Lefthook. For mise task design itself, use `mise`; for debugging failing PR checks, use `gh-fix-ci`.
Curate external agent collections into this APM workspace. Use when evaluating whether an outside agent repository can be installed through APM, importing selected agents into catalog/agents, recording provenance, or refreshing curated agents from upstream.
Use when creating, rebuilding, or updating a Google Forms survey from a Markdown survey spec such as SURVEY_QUESTIONS.md, especially when the form should stay synchronized with question text, required flags, Google Forms item types, scale labels, and removed-question notes.
Slack app management knowledge for app settings, manifests, OAuth installs, scopes, bot users, Marketplace settings, App Home, display names, sender names, mrkdwn message formatting, and safe workspace-visible changes. Use when diagnosing or changing a Slack app, installed app, bot user, app label, DM header, chat sender, message text decoration, Slack links, block quotes, app approval/install state, token impact, Slack API app settings, Slack Marketplace settings, or stale Slack app name propagation.
Use when planning, requirements, design, estimation, or task decomposition needs pre-implementation failure prediction, blind-spot discovery, planning review, design validation, or answers to "what could go wrong" / "what am I missing". Use before implementation begins.