mirror of https://github.com/headroomlabs-ai/headroom.git synced 2026-08-27 14:17:10 -04:00

chopratejas 053c4a06af feat: add OpenClaw ContextEngine plugin (@headroom-ai/openclaw)

- HeadroomContextEngine: implements ContextEngine interface (bootstrap, ingest,
  assemble, compact, afterTurn, prepareSubagentSpawn, dispose)
- ProxyManager: auto-detects running proxy or spawns one as child process,
  health checks, restart on crash, graceful shutdown
- AgentMessage ↔ OpenAI format conversion (user, assistant/tool_use, toolResult)
- headroom_retrieve CCR tool: agent can retrieve original uncompressed content
- Plugin manifest (openclaw.plugin.json) with config schema
- 11 tests (6 unit + 5 integration), all passing
- Integration tested: 100 servers compressed, 3,735 tokens saved (82%)

2026-03-28 13:43:40 -07:00

1.7 KiB

Raw Blame History

@headroom-ai/openclaw

Context compression plugin for OpenClaw. Compresses tool outputs, code, logs, and structured data — 70-90% token savings with zero LLM calls.

Install

pip install "headroom-ai[proxy]"
openclaw plugins install @headroom-ai/openclaw

Configure

{
  "plugins": {
    "slots": {
      "contextEngine": "headroom"
    }
  }
}

That's it. The plugin auto-starts the Headroom proxy if it's not already running.

How It Works

Every time OpenClaw assembles context for the model, the plugin compresses tool outputs and large messages:

JSON arrays (tool outputs, search results) — statistical selection keeps anomalies, errors, boundaries
Code — AST-aware compression via tree-sitter
Logs — pattern deduplication, keeps errors and boundaries
Text — ML-based token compression

Compression is lossless via CCR (Compress-Cache-Retrieve): originals are stored and the agent gets a headroom_retrieve tool to access full details when needed.

Configuration Options

Option	Default	Description
`proxyUrl`	auto-detected	URL of the Headroom proxy
`autoStart`	`true`	Start proxy automatically if not running
`pythonPath`	auto-detected	Path to Python binary
`proxyPort`	`8787`	Port for auto-started proxy

Comparison with lossless-claw

	lossless-claw	headroom
Compaction method	LLM summarization (DAG)	Content-aware compression (zero LLM)
Cost of compaction	Tokens (LLM calls)	Zero
Best for	Long conversations	Tool-heavy agents with large outputs
Retrieval	`lcm_grep`, `lcm_expand`	`headroom_retrieve` (instant)

License

Apache-2.0

1.7 KiB Raw Blame History