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

> Learn how to set the default Caveman compression level. Configure automatic compression on startup using the CAVEMAN_DEFAULT_MODE environment variable or a configuration file setting.

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

---

**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](https://github.com/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`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-activate.js) and exposed through the `/caveman-compress` command mapped in [`src/plugins/opencode/plugin.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-config.js):

1. **Environment variable** – `CAVEMAN_DEFAULT_MODE` overrides all other settings.
2. **Repository configuration** – [`./.caveman/config.json`](https://github.com/JuliusBrussee/caveman/blob/main/./.caveman/config.json) or [`./.caveman.json`](https://github.com/JuliusBrussee/caveman/blob/main/./.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.

```bash

# 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`.

```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`](https://github.com/JuliusBrussee/caveman/blob/main/.caveman/config.json) or [`.caveman.json`](https://github.com/JuliusBrussee/caveman/blob/main/.caveman.json) in the working directory and its ancestors.

```json
{
  "defaultMode": "compress"
}

```

Place this file at the repository root:

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

```

## Internal Implementation Details

When Caveman initializes, [`src/hooks/caveman-config.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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.

```bash

# 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`](https://github.com/JuliusBrussee/caveman/blob/main/.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`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-config.js), [`src/hooks/caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-activate.js), and [`src/plugins/opencode/plugin.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-activate.js) and [`src/plugins/opencode/plugin.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/.caveman/config.json) or [`.caveman.json`](https://github.com/JuliusBrussee/caveman/blob/main/.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`).