hrun — Headroom-Wrapped Command Runner

hrun is a Hyraxknot Division CLI tool that wraps any command, captures the full raw output, and — when Headroom compression is available — produces a compressed version for LLM context. Design goal: 64%+ savings on structured tool output before it reaches the LLM context.

Live status (2026-08-03): compression is ACTIVE on the Hermes host. headroom-ai 0.33.0 is installed in the Hermes venv; both script gates pass (a headroom CLI binary ships with the package, and from headroom import compress imports). Verified with a live run: hrun cat /tmp/kanban-export.json (1.44 MB, 200 tasks) compressed to 508 KB — 65% byte savings, 53% token savings (468K → 218K tokens, ratio 0.534, router:mixed transform). The 64%+ design goal is confirmed on real structured data.

Quick Start

export PATH="$PATH:/root/workspace/bin"
hrun mvn test        # JSON test report (64%+ savings confirmed on structured data)
hrun pnpm build      # Build logs
hrun cat report.json # Any file you want compressed

Every run saves to ~/.cache/headroom/runs/hrun-<ts>-<pid>/:

• raw-output.txt — the real output (always written)
• compressed-output.txt — compressed version; falls back to a raw copy when headroom-ai is missing
• metadata.json — run command, exit code, sizes, savings %, retrieval path (always written)
• metrics.json — token savings + transforms applied; only written when compression actually runs

Installation

The script is already installed on the Hermes host at /root/workspace/bin/hrun.

Compression dependency (INSTALLED 2026-08-03, version 0.33.0 in the Hermes venv at /usr/local/lib/hermes-agent/venv):

pip install headroom-ai

For remote hosts (e.g. workhorse/gpu01):

pip install headroom-ai
scp root@openclaw:/root/workspace/bin/hrun /usr/local/bin/hrun

Both script gates pass with the current package: a headroom executable ships in PATH (/usr/local/lib/hermes-agent/venv/bin/headroom) and the Python module imports (python3 -c "from headroom import compress"). No gate relaxation needed. Compression runs fully offline — no API key, no PyTorch, no onnxruntime required (Headroom logs a harmless magika detection failed warning and falls back to the unidiff tier; the router still picks SmartCrusher/CodeCompressor-style local transforms).

Measured Savings (verified 2026-08-03)

The 64%+ design goal holds on real structured data (kanban export). Smaller or prose-heavy payloads land 41–57%. Prose-only text may see 0–10%.

Configuration

Default config at ~/.config/headroom/default.toml; per-project override at .hermes/headroom.toml in the project root (or nearest ancestor).

enabled_commands = ["mvn", "gradle", "npm", "pnpm", "yarn", "docker compose", "docker build", "cat", "git diff", "git log"]
excluded_commands = ["ls", "pwd", "cd", "echo", "which", "vim", "nano", "code"]
compress_threshold_bytes = 2048  # skip output under 2KB
exclude_patterns = ["^#", "^(error|Error)"]

[projects]
bunsms = "/root/workspace/bunsms"
gestalt = "/root/workspace/gestalt"

Caveat: the config is currently declarative. The script only locates it for metadata; enabled_commands/excluded_commands are not enforced yet, and the small-output threshold is hardcoded at 1024 bytes in the script (vs 2048 in the config).

When to Use

Good for: JSON test reports, build logs, kanban exports, API responses, docker inspect, pip list, any repetitive structured output.

Skip for: Interactive commands, output under the small-output threshold, council sessions (provenance risk), wiki/memory content.

Environment Variables

Related Skills

• hrun devops skill — full documentation
• hyrax-wiki — wiki management
• nei-quartermaster — session digest and wiki capture