# How to Switch Caveman Compression Levels: Ultra, Full, and Off Mode Commands

> Easily switch Caveman compression levels with simple slash commands like /caveman ultra, /caveman full, or /caveman off. Control compression aggressiveness effortlessly.

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

---

**You switch Caveman compression levels by issuing slash commands like `/caveman ultra`, `/caveman full`, or `/caveman off`, which the mode-tracker hook persists to a hidden flag file that the compression script reads to determine compression aggressiveness.**

The Caveman open-source text compression utility supports multiple preset levels that control how aggressively content is shortened. Switching between these levels allows you to balance readability against brevity depending on your context. This guide explains exactly how the compression level system works in the `JuliusBrussee/caveman` repository, where levels are stored, and how to change them via commands or code.

## Understanding the Caveman Compression Level Architecture

The compression level system relies on two core components working in tandem: a mode-tracker hook that handles user commands and a Python compressor that executes the actual text transformation.

### The Mode-Tracker Hook ([`src/hooks/caveman-mode-tracker.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-mode-tracker.js))

When you type a slash command, the **mode-tracker hook** ([`src/hooks/caveman-mode-tracker.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-mode-tracker.js)) intercepts the input, validates the requested level, and writes the value to a hidden flag file (`.caveman-active`). This file acts as the single source of truth for the current session's compression settings.

### The Compression Script ([`skills/caveman-compress/scripts/compress.py`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/scripts/compress.py))

The **compressor** ([`skills/caveman-compress/scripts/compress.py`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/scripts/compress.py)) reads the `.caveman-active` flag file at runtime to determine which algorithm to apply. If the file contains `ultra`, the script applies the most aggressive compression rules; `full` applies standard compression; an `off` value or missing file skips compression entirely.

## Switching Caveman Compression Levels via Slash Commands

The primary interface for changing levels is the `/caveman` slash command prefix followed by the desired level.

- `/caveman ultra` – Activates maximum compression, aggressively shortening text with minimal preservation of original formatting.
- `/caveman full` – Sets the default compression level, balancing size reduction with readability.
- `/caveman off` – Disables compression entirely, passing text through unchanged.

These commands are processed by the mode-tracker hook and immediately persisted to the `.caveman-active` file in your home directory.

## Programmatically Changing Compression Levels

You can also switch levels from automation scripts by piping the slash command to the mode-tracker hook and subsequently invoking the compressor:

```python
import subprocess

# Set compression level to ultra via the mode-tracker hook

command = "/caveman ultra"
subprocess.run(
    ["node", "src/hooks/caveman-mode-tracker.js"],
    input=f'{{"prompt":"{command}"}}'.encode(),
    check=True
)

# Run the compressor - it will read the ultra setting from .caveman-active

subprocess.run(
    ["python", "skills/caveman-compress/scripts/compress.py", "input.md", "output.md"],
    check=True
)

```

This pattern is validated in [`tests/test_mode_tracker.py`](https://github.com/JuliusBrussee/caveman/blob/main/tests/test_mode_tracker.py), specifically in the `test_slash_caveman_level_switch` test case, which ensures that level changes are correctly persisted and read by the compressor.

## Verifying Your Current Compression Level

To confirm which level is currently active without running a compression job, inspect the hidden flag file directly:

```bash
cat ~/.caveman-active

```

This outputs the current level (e.g., `ultra`, `full`, or `off`) that the compressor will use on the next invocation.

## Summary

- **Slash commands** (`/caveman ultra`, `/caveman full`, `/caveman off`) are the primary interface for switching Caveman compression levels.
- The **mode-tracker hook** ([`src/hooks/caveman-mode-tracker.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-mode-tracker.js)) parses these commands and writes the level to the `.caveman-active` flag file.
- The **compressor script** ([`skills/caveman-compress/scripts/compress.py`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/scripts/compress.py)) reads this flag to determine which compression algorithm to apply.
- Levels persist across sessions until explicitly changed or disabled.
- The test suite in [`tests/test_mode_tracker.py`](https://github.com/JuliusBrussee/caveman/blob/main/tests/test_mode_tracker.py) validates the level-switching mechanism, ensuring reliability between the hook and compressor.

## Frequently Asked Questions

### What are the available Caveman compression levels?

Caveman supports three primary compression levels: **ultra** (maximum compression), **full** (standard compression), and **off** (no compression). These correspond to different algorithms in [`skills/caveman-compress/scripts/compress.py`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/scripts/compress.py) that control how aggressively text is shortened.

### Where does Caveman store the current compression level?

The active compression level is stored in a hidden flag file named `.caveman-active`, typically located in your home directory. The mode-tracker hook ([`src/hooks/caveman-mode-tracker.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-mode-tracker.js)) writes to this file whenever you issue a `/caveman` command, and the compressor reads it to determine which preset to apply.

### How do I completely disable Caveman compression?

To disable compression, issue the `/caveman off` slash command. This writes `off` to the `.caveman-active` file, signaling the compressor in [`skills/caveman-compress/scripts/compress.py`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/scripts/compress.py) to pass text through unchanged. You can verify the deactivation by checking that the flag file contains "off" or by running the compressor and observing that input matches output.

### Can I switch compression levels mid-session?

Yes, you can change levels at any time by issuing a new `/caveman` command. The mode-tracker hook updates the `.caveman-active` file immediately, and subsequent calls to the compressor will use the new level without requiring a restart or reinitialization of the environment.