# Caveman Compression Engine Modes: A Complete Guide to Text Compression Levels

> Explore the nine Caveman compression engine modes from off to ultra including Wenyan and workflow modes. Optimize your text compression today.

- Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman)
- Tags: how-to-guide
- Published: 2026-09-06

---

**The Caveman compression engine supports nine distinct modes ranging from `off` (no compression) to `ultra` (70% token reduction), including specialized classical Chinese (Wenyan) variants and workflow modes like `commit` and `review`.**

The Caveman project by JuliusBrussee provides an intelligent text compression system designed to reduce token costs when sending text to language model providers. These Caveman compression engine modes are defined centrally in the codebase and allow users to control the aggressiveness of text compression based on their specific use case and readability requirements.

## Standard Compression Modes

The primary compression levels control how aggressively the engine processes prose while maintaining intelligibility. These modes are defined in [`src/hooks/caveman-config.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-config.js) within the `VALID_MODES` array.

**`off`**  
Compression is completely disabled. The original text is transmitted unchanged to the language model provider, resulting in **0% token savings**. Use this mode when debugging or when absolute text fidelity is required.

**`lite`**  
Applies light-weight compression by dropping articles, short stop-words, and performing modest paraphrasing. This mode achieves approximately **30% token reduction** while maintaining natural readability.

**`full`**  
The default compression mode that applies the complete set of compression rules while preserving readability. This mode delivers approximately **45% token savings** and serves as the baseline recommendation for most interactions.

**`ultra`**  
Applies maximum compression by aggressively removing filler words, using terse sentence fragments, and compressing tabular data. This mode achieves up to **70% token reduction** and is ideal for cost-sensitive applications where brief, cryptic output is acceptable.

## Classical Chinese (Wenyan) Modes

The engine includes specialized modes that render compressed text in classical Chinese literary style (Wenyan), offering both cultural aesthetic and compression benefits.

**`wenyan-lite`**  
Combines classical Chinese stylistic conventions with light compression, producing shorter, more literary text with approximately **30% token savings**.

**`wenyan`**  
An alias for `wenyan-full`, this mode applies standard Wenyan-style compression rules for approximately **45% token reduction**.

**`wenyan-full`**  
Provides full classical Chinese compression with heavy abbreviation while maintaining the literary feel, achieving roughly **55% token savings**.

**`wenyan-ultra`**  
Delivers extreme classical Chinese compression with maximal abbreviation while preserving the Chinese literary aesthetic. This mode reaches approximately **70% token compression**.

## Utility and Workflow Modes

Beyond standard compression, the engine provides task-specific modes for development workflows. These modes temporarily alter rule sets rather than applying standard compression algorithms.

**`commit`**  
A one-shot "independent" mode that temporarily disables standard prose compression rules while committing code. This mode is not a regular compression level but rather a workflow state optimized for generating commit messages.

**`review`**  
Similar to `commit`, this mode facilitates review-oriented interactions by adjusting the ruleset for code analysis tasks rather than aggressive text compression.

**`compress`**  
An internal helper mode reserved for the compression scripts themselves, used during the engine's internal processing pipeline.

## Configuration Files and Implementation

The mode system relies on several interconnected source files that handle validation, persistence, and ruleset injection.

The canonical list of valid mode strings resides in **[`src/hooks/caveman-config.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-config.js)** (lines 32-36), which exports the `VALID_MODES` array and provides the `writeSessionMode()` and `getDefaultMode()` functions for programmatic mode management.

When a mode is selected, the engine references **[`src/plugins/opencode/commands/caveman-help.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/plugins/opencode/commands/caveman-help.md)**, which contains the human-readable help table displayed in the CLI. This documentation also informs the model's ruleset injection during session initialization.

Internally, the chosen mode determines which rows of the intensity table in **[`skills/caveman/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/SKILL.md)** are preserved when the ruleset is filtered for the active session. The hook in **[`src/hooks/caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-activate.js)** performs this injection at session start, while **[`src/hooks/caveman-mode-tracker.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-mode-tracker.js)** monitors mode changes and updates per-session state throughout the interaction.

## How to Set Compression Modes

You can activate compression modes through the command-line interface or programmatically via the Node.js API.

### CLI Usage

Use the `caveman` command followed by the desired mode name:

```bash

# Activate light compression (~30% tokens saved)

caveman lite

# Switch to the default "full" compression

caveman

# Use the most aggressive compression (~70% tokens saved)

caveman ultra

# Apply classical Chinese (Wenyan) style with full compression

caveman wenyan-full

```

### Programmatic API

For integration with Node.js applications, import the configuration utilities from [`src/hooks/caveman-config.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-config.js):

```js
const { writeSessionMode, getDefaultMode } = require('./src/hooks/caveman-config');

// Set mode for the current session
writeSessionMode(process.env.CLAUDE_CONFIG_DIR, /*sessionId*/ null, 'ultra');

// Retrieve the effective mode (falls back to env / repo config / user config)
const mode = getDefaultMode();
console.log('Current Caveman mode:', mode);

```

## Summary

- **Four standard modes** (`off`, `lite`, `full`, `ultra`) provide progressive compression from 0% to 70% token reduction
- **Four Wenyan variants** offer classical Chinese literary styling with comparable compression levels
- **Three utility modes** (`commit`, `review`, `compress`) support specific development workflows rather than standard text compression
- **Mode definitions** reside in [`src/hooks/caveman-config.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-config.js) with the `VALID_MODES` array governing acceptable values
- **Ruleset filtering** occurs through [`skills/caveman/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/SKILL.md) intensity tables, activated by [`src/hooks/caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-activate.js)
- **Session persistence** is handled by `writeSessionMode()` and tracked via [`src/hooks/caveman-mode-tracker.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-mode-tracker.js)

## Frequently Asked Questions

### What is the default Caveman compression mode?

**The default mode is `full`, which applies the complete set of compression rules while preserving readability for approximately 45% token savings.** If no mode is specified in the CLI command or configuration, the engine automatically selects `full` as the baseline setting.

### How do I completely disable compression in Caveman?

**Set the mode to `off` either via the CLI (`caveman off`) or programmatically using `writeSessionMode(configDir, null, 'off')`.** This mode bypasses all compression algorithms and transmits the original text unchanged, resulting in zero token savings but perfect text fidelity.

### What is the difference between `wenyan` and `wenyan-full` modes?

**`wenyan` is simply an alias that resolves to `wenyan-full`, meaning they apply identical compression logic.** Both modes use classical Chinese literary styling with approximately 45% token reduction, while `wenyan-lite` offers lighter compression (~30%) and `wenyan-ultra` provides maximum abbreviation (~70%).

### Can I programmatically check which mode is currently active?

**Yes, call `getDefaultMode()` imported from [`src/hooks/caveman-config.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-config.js) to retrieve the effective mode.** This function evaluates the session configuration, environment variables, repository settings, and user preferences to return the currently active compression mode.