How to Set a Default Caveman Compression Level: Complete Configuration Guide

Caveman does not use numeric compression levels; instead, you set the default mode to compress using the CAVEMAN_DEFAULT_MODE environment variable or a defaultMode field in your configuration file to enable automatic compression on startup.

Caveman, an MCP server developed in the JuliusBrussee/caveman repository, manages context through discrete operational modes rather than traditional compression sliders. To make the aggressive context reduction of the /caveman-compress command automatic, you must configure the tool to start in compress mode by default.

How Caveman Handles Compression

Unlike standard compression utilities that accept numeric levels (e.g., 1–9), Caveman implements a deterministic compression algorithm that operates in a binary fashion: either compression is applied via the compress mode, or it is not. The compress mode triggers the context-shrinking logic implemented in src/hooks/caveman-activate.js and exposed through the /caveman-compress command mapped in src/plugins/opencode/plugin.js.

Configuration Resolution Priority

Caveman resolves the startup mode through a cascading priority system defined in src/hooks/caveman-config.js:

1. Environment variable – CAVEMAN_DEFAULT_MODE overrides all other settings.
2. Repository configuration – ./.caveman/config.json or ./.caveman.json in the project directory.
3. User configuration – $XDG_CONFIG_HOME/caveman/config.json (or platform-specific equivalent).
4. Built-in default – Falls back to full mode if no configuration is found.

Setting the Default Compression Mode

Method 1: Environment Variable

Set the CAVEMAN_DEFAULT_MODE environment variable to compress before launching Caveman. This method takes precedence over all file-based configurations.

# Linux/macOS

export CAVEMAN_DEFAULT_MODE=compress

# Windows PowerShell

$env:CAVEMAN_DEFAULT_MODE = "compress"

# Windows CMD

set CAVEMAN_DEFAULT_MODE=compress

Method 2: User-Level Configuration

Create or edit the user configuration file to apply the default across all projects. On Linux and macOS, this is typically located at ~/.config/caveman/config.json. On Windows, use %APPDATA%\caveman\config.json.

{
  "defaultMode": "compress"
}

Method 3: Repository-Level Configuration

To enable compression by default for a specific project only, add a configuration file to the repository root. Caveman checks for .caveman/config.json or .caveman.json in the working directory and its ancestors.

{
  "defaultMode": "compress"
}

Place this file at the repository root:

mkdir -p .caveman
echo '{"defaultMode": "compress"}' > .caveman/config.json

Internal Implementation Details

When Caveman initializes, src/hooks/caveman-config.js aggregates settings from the cascade above and returns the resolved mode. The activation logic in src/hooks/caveman-activate.js then initializes the compression engine if the resolved mode is compress. The command interface in src/plugins/opencode/plugin.js maps the string /caveman-compress to this same activation logic, meaning the default mode setting effectively automates what would otherwise be a manual command invocation.

Because the compression algorithm is fixed, there is no additional "compression level" parameter to tune within these files—the compress mode applies the same reduction strategy regardless of how it was triggered.

Temporarily Overriding the Default

Even when compress is set as the default, you can explicitly switch modes for a single session. Caveman accepts commands that change modes on the fly, bypassing the configured default without modifying your settings.

# Switch to lite mode temporarily

/caveman lite

# Switch to full mode temporarily

/caveman full

# Switch to ultra mode

/caveman ultra

Summary

• Caveman uses modes, not numeric compression levels—the compress mode is either on or off.
• Set CAVEMAN_DEFAULT_MODE=compress for a global environment-based default.
• Use defaultMode: "compress" in ~/.config/caveman/config.json for persistent user-level configuration.
• Use repository-specific configs (.caveman/config.json) to scope the default to individual projects.
• Configuration resolution follows the order: environment → repo → user → built-in (full).
• Core files implementing this behavior are src/hooks/caveman-config.js, src/hooks/caveman-activate.js, and src/plugins/opencode/plugin.js.

Frequently Asked Questions

Does Caveman support numeric compression levels like 1–9?

No. According to the source code in src/hooks/caveman-activate.js and src/plugins/opencode/plugin.js, Caveman implements a deterministic compression algorithm that does not accept intensity parameters. The compress mode applies a fixed context-reduction strategy.

Can I set different default modes for different repositories?

Yes. Create a .caveman/config.json or .caveman.json file in the root of specific repositories. Caveman checks these locations before falling back to user-level configuration, allowing per-project defaults that override your global settings.

How do I temporarily disable compression if it is set as the default?

You can invoke alternative modes explicitly using slash commands such as /caveman lite or /caveman full to override the default mode for that specific session without changing your configuration files.

Where does Caveman store its user-level configuration on Windows?

Caveman follows the XDG Base Directory Specification where possible, but on Windows it stores user configuration in %APPDATA%\caveman\config.json (typically C:\Users\<Username>\AppData\Roaming\caveman\config.json).

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