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

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)

When you type a slash command, the mode-tracker hook (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)

The compressor (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:

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

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) parses these commands and writes the level to the .caveman-active flag file.
• The compressor script (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 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 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) 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 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.

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