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

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 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 (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, 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 are preserved when the ruleset is filtered for the active session. The hook in src/hooks/caveman-activate.js performs this injection at session start, while 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:

# 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:

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 with the VALID_MODES array governing acceptable values
• Ruleset filtering occurs through skills/caveman/SKILL.md intensity tables, activated by src/hooks/caveman-activate.js
• Session persistence is handled by writeSessionMode() and tracked via 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}