# OmniRoute Compression Engines: A Complete Guide to Available Engines and Stacking Strategies

> Explore OmniRoute compression engines rtk caveman lite headroom. Learn how to stack them in configurable pipelines to reduce token usage and optimize your LLM prompts.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-08-16

---

**OmniRoute provides four built-in compression engines (`rtk`, `caveman`, `lite`, and `headroom`) that can be used individually or stacked in configurable pipelines to reduce token usage before prompts reach language models.**

The OmniRoute repository (diegosouzapw/OmniRoute) ships with a **Prompt-Compression subsystem** designed to rewrite user prompts before they are transmitted to upstream language models. This system centers on a catalog of interchangeable compression engines and a flexible pipeline model that determines how those engines combine. Understanding these engines and their stacking behavior helps developers optimize token budgets without sacrificing answer quality.

## Available Compression Engines in OmniRoute

According to the source code in [`open-sse/services/compression/engineCatalog.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/compression/engineCatalog.ts), OmniRoute defines four distinct engines through the `ENGINE_IDS` enum. Each engine targets different trade-offs between compression ratio and output fidelity.

| Engine ID | Strategy | Quality Impact | Best For |
|-----------|----------|---------------|----------|
| `rtk` | Lossless token reduction via common-prefix sharing and whitespace compaction | None | Safe default when token limits are tight |
| `caveman` | Aggressive heuristic pruning of "less-important" tokens | Lossy | Maximum reduction when some fidelity loss is acceptable |
| `lite` | Rule-based removal of obvious redundancy (duplicate stop words, etc.) | Minimal | Moderate reduction without full lossy compression |
| `headroom` | Tail-trimming based on remaining token budget | Context-dependent | Automatic guard-rail for strict provider caps |

### Engine Implementation Details

New engines can be added by extending the `ENGINE_IDS` enum in [`engineCatalog.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/engineCatalog.ts) and providing a concrete implementation in `open-sse/services/compression/engines/`. The existing four engines cover the majority of production use cases.

## How OmniRoute Compression Engines Stack

The compression system operates in **two distinct modes** controlled by user settings in [`compressionSettings.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/compressionSettings.ts):

- **Heuristic (single-engine) mode**: One engine processes the prompt
- **Stacked mode**: Multiple engines execute sequentially as a pipeline

### Pipeline Structure and Execution

In stacked mode, the pipeline is stored as an ordered array of `{ engine: string }` objects defined in [`compressionPipelineModel.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/compressionPipelineModel.ts). Each engine receives the output of the previous engine, creating **compositional token reduction**.

A typical three-step pipeline configuration:

```json
[
  { "engine": "lite" },
  { "engine": "caveman" },
  { "engine": "rtk" }
]

```

Execution flow: **lite → caveman → rtk**

Token savings accumulate at each stage. The final token count reflects the cumulative effect of all transformations. The UI renders this as a flow diagram (see `docs/diagrams/compression-pipeline.svg`) where users can reorder, add, or remove steps.

The pipeline graph structure follows a verified formula: **1 input node + N engine nodes + 1 output node**. Tests in [`compressionFlowModel.test.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/compressionFlowModel.test.ts) and [`compressionPipelineModel.test.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/compressionPipelineModel.test.ts) validate this graph construction.

## Configuring Engine Stacks in OmniRoute

### Via the React UI Component

The `CompressionPanel` component (`open-sse/components/compression/compressionPanel`) provides interactive pipeline editing:

```tsx
import { ENGINE_IDS } from "@/open-sse/services/compression/engineCatalog";
import { CompressionPanel } from "@/open-sse/components/compression/compressionPanel";

<CompressionPanel
  initialPipeline={[
    { engine: ENGINE_IDS.rtk },
    { engine: ENGINE_IDS.caveman, enabled: true, intensity: "full" },
  ]}
/>

```

The panel renders validation feedback through test suites in [`compressionPanel.test.tsx`](https://github.com/diegosouzapw/OmniRoute/blob/main/compressionPanel.test.tsx).

### Programmatic Pipeline Construction

For server-side or automated configurations, use the pipeline builder:

```ts
import { buildCompressionPipeline } from "@/open-sse/services/compression/pipelineBuilder";

const pipeline = buildCompressionPipeline([
  { engine: "lite" },
  { engine: "caveman", intensity: "aggressive" },
  { engine: "rtk" },
]);

await handleChatCore(request, { compressionPipeline: pipeline });

```

The builder validates engine IDs against the catalog and normalizes intensity parameters per [`compressionPipelineModel.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/compressionPipelineModel.ts).

### CLI Configuration

Compression settings persist in SQLite and can be manipulated via CLI:

```bash

# View current configuration

omniroute compression get-settings

# Update pipeline directly

omniroute compression set-pipeline '{"pipeline":[{"engine":"rtk"},{"engine":"caveman"}]}'

```

Implementation resides in `bin/cli/commands/compression.mjs`.

## Automatic Stack Selection with Combo Predicates

The system supports dynamic pipeline switching through **compression combo predicates** defined in [`compressionComboPredicates.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/compressionComboPredicates.ts). These predicates automatically adjust the active stack based on routing context.

Common automatic triggers include:

- **Provider token limits**: Automatically enable `headroom` when approaching strict caps
- **Model-specific rules**: Switch to `rtk`-only for models with known sensitivity
- **Request characteristics**: Apply `caveman` for long context windows where tail loss is acceptable

The default configuration uses `"stacked"` mode with a single `rtk` engine, providing lossless baseline compression while preserving user flexibility to extend the stack.

## Database Persistence and API Layer

Compression configurations survive application restarts through SQLite migrations:

- [`102_compression_engines_map.sql`](https://github.com/diegosouzapw/OmniRoute/blob/main/102_compression_engines_map.sql): Engine catalog mapping
- [`043_default_compression_combo_pipeline.sql`](https://github.com/diegosouzapw/OmniRoute/blob/main/043_default_compression_combo_pipeline.sql): Default pipeline storage

The REST API under `/api/compression/*` exposes CRUD operations for engine settings, with comprehensive test coverage in [`api/compression-engines-route.test.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/api/compression-engines-route.test.ts).

## Performance Considerations for Stacked Compression

When stacking OmniRoute compression engines, consider these factors:

- **Order matters**: Place lossless engines (`rtk`, `lite`) before aggressive ones (`caveman`) to preserve maximum information for heuristic decisions
- **Intensity cascading**: Later engines operate on already-reduced text, amplifying both savings and potential quality degradation
- **Latency**: Each engine adds processing time; monitor `handleChatCore` execution when using deep stacks

## Summary

- OmniRoute provides **four compression engines** (`rtk`, `caveman`, `lite`, `headroom`) with distinct loss/performance trade-offs
- Engines stack sequentially in **configurable pipelines** where each stage receives the previous stage's output
- The **default configuration** uses single-engine `rtk` mode for safe, lossless compression
- **Combo predicates** enable automatic pipeline switching based on routing context and provider constraints
- All configurations persist through **SQLite migrations** and expose **CLI and API** interfaces

## Frequently Asked Questions

### What is the safest OmniRoute compression engine for production use?

The `rtk` engine is explicitly designed as the safe default. It performs **lossless** token reduction through common-prefix sharing and whitespace compaction, meaning it never degrades answer quality. This is why `rtk` occupies the default position in fresh installations.

### Can I create custom compression engines in OmniRoute?

Yes. Extend the `ENGINE_IDS` enum in [`engineCatalog.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/engineCatalog.ts) and implement your engine in `open-sse/services/compression/engines/`. The pipeline builder automatically recognizes new enum values, and the UI will display them in the `CompressionPanel` without additional frontend changes.

### How does the `headroom` engine differ from other OmniRoute compressors?

Unlike content-aware engines (`rtk`, `caveman`, `lite`), `headroom` is a **budget-aware trimmer**. It evaluates the remaining token allowance for a specific provider and truncates prompt tails to fit. The `headroom` engine is primarily invoked by the auto-combo routing layer rather than user pipelines, serving as a last-resort guard against hard token limits.

### What happens if I disable all engines in a stacked pipeline?

OmniRoute treats an empty pipeline as a **pass-through**: prompts transmit unmodified to upstream models. The [`compressionSettings.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/compressionSettings.ts) model permits this configuration, though the UI may display a warning that no compression is active.