# OmniRoute Compression Engine Stages: RTK, Caveman, CCR, and Headroom Explained

> Discover OmniRoute's compression engine stages: RTK, Caveman, CCR, and Headroom. Learn how these stages efficiently reduce token count while preserving crucial context for LLM messages.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: internals
- Published: 2026-07-03

---

**OmniRoute’s prompt-compression pipeline processes LLM messages through four specialized stages—RTK (Rule-aware Tool-output Kernels), Caveman (semantic shrinker), Headroom (statistical sampler), and CCR (Content-Compression-Retrieve)—that execute in a configurable order to reduce token count while preserving critical context.**

The `diegosouzapw/OmniRoute` repository implements a modular compression architecture that chains independent engines to minimize prompt size without losing information essential for LLM reasoning. Each stage applies distinct transformations to message payloads, with the default execution order running RTK → Caveman → Headroom → CCR as determined by the [`strategySelector.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/strategySelector.ts) logic.

## RTK (Rule-aware Tool-output Kernels): Intelligent Tool Output Filtering

The **RTK** engine, implemented in [`open-sse/services/compression/engines/rtk/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/compression/engines/rtk/index.ts), serves as the first line of defense against verbose shell-tool results. It detects blocks containing output from commands like `bash`, `git`, or `docker` and applies declarative **filters** stored under the `rtk/filters` catalog.

Key capabilities include:
- **Pattern matching** against command-specific output formats
- **Smart truncation** via [`rtk/smartTruncate.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/rtk/smartTruncate.ts) to retain only relevant log sections
- **Line deduplication** handled by [`rtk/lineFilter.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/rtk/lineFilter.ts) and [`rtk/deduplicator.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/rtk/deduplicator.ts)
- **Raw-output retention** for blocks that require exact preservation
- **Analytics generation** that produces a list of applied techniques for the `engineBreakdown`

When RTK disables a block (for example, due to an unrecognized command), downstream stages receive the original text unchanged, ensuring safety.

## Caveman: The Semantic Shrinker

Located in [`open-sse/services/compression/caveman.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/compression/caveman.ts), the **Caveman** engine functions as a fast, rule-based "semantic shrinker" that strips superficial noise without affecting LLM reasoning. It operates on both plain-text messages and code blocks when enabled.

The engine applies rules defined in [`cavemanRules.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/cavemanRules.ts) to:
- Remove or shorten **identifiers** and **variable names**
- Strip **version strings** (e.g., converting `v2.3.1-abc123` to shorter representations)
- Eliminate **hash-like fragments** and other non-semantic tokens

Because Caveman is computationally cheap, it runs after RTK in the default pipeline. This ordering ensures RTK has already removed large log clutter, making Caveman’s work lighter and more efficient.

## Headroom: Statistical Sampling for Large Arrays

The **Headroom** engine, found in [`open-sse/services/compression/engines/headroom/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/compression/engines/headroom/index.ts), targets very large homogeneous JSON arrays—such as tool-result tables or log dumps—that would otherwise consume excessive tokens.

Headroom implements **head-plus-tail sampling** via [`headroom/sample.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/headroom/sample.ts):
- Keeps a configurable number of rows from the start and end of arrays (default **100 rows each**)
- Replaces the original array with a compact marker containing metadata

The marker format follows this pattern:

```

[ionizer: kept <kept>/<total> rows; full → CCR retrieve hash=<24-hex> chars=<N>]

```

The full original array is stored in the **CCR store** for later retrieval, making Headroom safe for lossy compression of massive datasets.

## CCR (Content-Compression-Retrieve): Lossless Recovery Store

The final stage, **CCR**, lives in [`open-sse/services/compression/engines/ccr/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/compression/engines/ccr/index.ts) and guarantees **lossless recoverability** for any data aggressively reduced by previous engines. When a block is replaced by a short marker, the original text is stored in a bounded in-memory **CCR store**.

Implementation details:
- Keys are generated using **SHA-256 hashes** of the block content combined with the request’s principal (API-key ID)
- The store caps at **`MAX_CCR_ENTRIES = 5,000`** and evicts entries **FIFO** to prevent unbounded memory growth
- Retrieval is available via the **MCP "compression-ccr" tools** at `/api/mcp/.../ccrRetrieve` or through the [`ccr/ccrQuery.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/ccr/ccrQuery.ts) helpers

This ensures that even after extreme compression, the full original context remains accessible via cheap hash lookups.

## Pipeline Execution and Strategy Selection

The [`open-sse/services/compression/strategySelector.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/compression/strategySelector.ts) file orchestrates which engines run and in what sequence. Each engine advertises a `stackPriority` value, and the selector sorts them accordingly:

- **RTK**: priority 10
- **Caveman**: priority 20  
- **Headroom**: priority 15
- **CCR**: priority 4

Because each engine implements the `stackable: true` interface in [`engineCatalog.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/engineCatalog.ts), the pipeline can be extended with future engines without breaking existing behavior. Users can override the default order via the `pipeline` field in compression requests or through combo-override settings.

## Code Examples: Working with the Compression Pipeline

The following TypeScript snippets demonstrate how to invoke the compression pipeline directly using the same code path as the API:

```typescript
import { applyCompression } from "@omniroute/open-sse/services/compression";
import { compressionEngineRegistry } from "@omniroute/open-sse/services/compression/engineCatalog";

// Build a request body matching the /chat endpoint format
const body = {
  messages: [
    { role: "assistant", content: "`git diff` output…" },
    { role: "tool", content: "very‑long‑log‑output…" },
  ],
};

// Define pipeline order (optional - otherwise derived from combo config)
const pipeline = ["rtk", "caveman", "headroom", "ccr"];

// Execute compression with per-engine configuration
const result = applyCompression(body, {
  pipeline,
  config: {
    rtk: { enabled: true, intensity: "aggressive" },
    caveman: { enabled: true, level: "full" },
    headroom: { enabled: true, sampleRows: 100 },
    ccr: { enabled: true }
  }
});

// Inspect results
console.log("Compressed?", result.compressed);
console.log("Techniques used:", result.stats?.techniquesUsed);
console.log("Engine breakdown:", result.stats?.engineBreakdown);

```

**Retrieving stored CCR blocks:**

```typescript
import { getCcrBlock } from "@omniroute/open-sse/mcp-server/tools/compressionTools";

const marker = "[ionizer: kept 200/10000 rows; full → CCR retrieve hash=1a2b3c4d5e6f7g8h9i0j1k2l chars=120]";
const hash = marker.match(/hash=([0-9a-f]{24})/)[1];

// Retrieve via MCP tool or REST endpoint:
// GET /api/mcp/compression/ccr/retrieve?hash=<hash>
const fullBlock = await getCcrBlock({ hash });   // Returns original CSV text

```

## Summary

- **RTK** handles tool-specific output filtering and truncation at the entry point, implemented in [`rtk/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/rtk/index.ts) with helpers like [`smartTruncate.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/smartTruncate.ts) and [`deduplicator.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/deduplicator.ts)
- **Caveman** performs fast semantic shrinking of identifiers and version strings via [`caveman.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/caveman.ts) and [`cavemanRules.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/cavemanRules.ts)
- **Headroom** samples large homogeneous arrays (default 100 head/tail rows) and offloads full data to CCR, controlled by [`headroom/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/headroom/index.ts)
- **CCR** provides lossless storage with a 5,000-entry FIFO cache and SHA-256 keyed retrieval, implemented in [`ccr/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/ccr/index.ts)
- The **strategy selector** in [`strategySelector.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/strategySelector.ts) orders execution by `stackPriority` (RTK 10 → Caveman 20 → Headroom 15 → CCR 4) but supports custom pipeline configurations

## Frequently Asked Questions

### What determines the execution order of RTK, Caveman, CCR, and Headroom?

The execution order is determined by the `stackPriority` values defined in each engine’s descriptor and processed by [`strategySelector.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/strategySelector.ts). The default priorities are RTK (10), Caveman (20), Headroom (15), and CCR (4), resulting in the sequence RTK → Caveman → Headroom → CCR. You can override this by specifying a custom `pipeline` array in the compression request configuration.

### How does CCR ensure I don't lose data after aggressive compression?

CCR (Content-Compression-Retrieve) stores the original text of any block replaced by a marker in a bounded in-memory store keyed by SHA-256 hash. With a capacity of `MAX_CCR_ENTRIES = 5,000` and FIFO eviction, it guarantees that recently compressed content remains retrievable via the MCP `ccrRetrieve` tool or the `/api/mcp/compression/ccr/retrieve` endpoint.

### Can I configure the number of rows Headroom keeps when sampling arrays?

Yes. Headroom accepts a `sampleRows` parameter in the engine configuration (default 100). This determines how many rows are kept from both the head and tail of large homogeneous arrays. The total retained rows will be twice this value (head + tail) unless the array is smaller than the combined sample size.

### Why does Caveman run after RTK in the default pipeline?

Caveman runs after RTK because RTK first removes large-scale tool-output clutter (logs, diffs) that would otherwise complicate Caveman’s semantic analysis. By placing the computationally expensive pattern matching of RTK first, Caveman can operate more efficiently on the already-truncated content, reducing the volume of text that needs identifier and version-string processing.