headroom-check

name	headroom-check
description	Run `headroom perf` and act on its recommendations — flag long/unstable conversations, surface uncompressed stale reads, and publish eligible TOIN patterns

Run:

headroom perf --hours 0

Read the report and act on each section:

Cache Performance — if Unstable requests are a non-trivial share of total requests, or Last 5 avg cache_write/read is much larger than First 5 avg, the current conversation has grown too long or its prefix is getting rewritten. Recommend the user /clear or compact between unrelated tasks rather than continuing to grow the session.

Content Router Routing — if Excluded (Read/Glob output) is a large share of routed messages, that content is sitting in context uncompressed. Recommend leaning on CodeGraph/sem/tokensave lookups instead of re-Reading files, and call headroom_compress on large results once you're done reasoning over them.

TOIN Learning / TOIN Highlights — if the report lists patterns eligible for publishing (samples above some threshold shown in the output), run:

python -m headroom.cli.toin_publish --min-observations <n>

using the observation threshold perf reported as eligible, not the tool's default of 50. Locate the headroom binary's own Python if the system python/python3 doesn't have the headroom package installed — it's a pipx install, e.g.:

find ~/.local/share/mise/installs/pipx-headroom-ai -maxdepth 3 -name python

Recommendations section — treat these as authoritative and specific; summarize them for the user rather than re-deriving generic advice.

Report findings concisely: what's healthy, what to change, and any command that needs the user's confirmation before running (e.g. toin_publish writes recommendations.toml, which the proxy loads at startup).