# What Is the Caveman Auto-Clarity Feature and When Does It Disable Itself for Safety?

> Discover the Caveman auto-clarity feature, a CLI tool safety mechanism that compresses LLM outputs and its safety disabling conditions. Learn when it turns off automatically.

- Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman)
- Tags: deep-dive
- Published: 2026-07-12

---

**Auto-clarity is a built-in safety mechanism in the Caveman CLI tool that automatically compresses verbose LLM outputs without user intervention, and it disables itself when it detects safety-critical content, explicit user override commands, environment flags, or repeated compression failures.**

The `JuliusBrussee/caveman` repository provides a command-line utility that compresses LLM-generated text into concise "caveman mode" summaries. Understanding the auto-clarity feature and its safety disable conditions ensures you maintain control over output compression while preventing accidental truncation of critical information.

## Understanding the Auto-Clarity Feature in Caveman

Auto-clarity operates as an automatic compression layer that triggers when the underlying language model produces overly verbose or ambiguous responses. Unlike manual activation via the `/caveman` command, this feature intervenes automatically when specific verbosity thresholds are met.

### Detection and Compression Pipeline

The implementation in [`src/hooks/caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-activate.js) follows a three-stage process:

1. **Verbosity detection** scans raw model output for length-based thresholds and filler patterns that indicate unnecessary elaboration.
2. **Compression injection** applies the same algorithms used by the `/caveman full` command to reduce token count.
3. **State persistence** creates a flag file (`.caveman-auto-clarity`) in the workspace to maintain compression mode across subsequent interaction turns.

## When Does Caveman Disable Itself for Safety?

Caveman implements four distinct safety layers in [`src/hooks/caveman-mode-tracker.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-mode-tracker.js) that automatically suspend auto-clarity functionality to prevent information loss or safety risks.

### User Override Commands

When you explicitly request full detail using `/caveman off` or any mode-switching command that sets the state to `normal`, the system removes the `.caveman-auto-clarity` flag file and suspends automatic compression for the remainder of the session.

### Safety-Critical Content Detection

The hook analyzes output against a safety-regex list containing patterns like `dangerous`, `execute`, and `delete`. If the LLM generates code that may be executed, instructions that could cause harm, or other risky content, the system writes a "disable-auto-clarity" marker and skips compression to ensure full visibility of safety-relevant details.

### Environment-Level Safety Triggers

The installer script ([`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js)) and CI pipelines can set the environment variable `CAVEMAN_DISABLE_AUTO_CLARITY=1` to bypass all auto-clarity logic for the entire runtime. This global override activates when risky providers are detected during installation or when running in automated testing environments.

### Repeated Failure Protection

The mode-tracker maintains a counter of consecutive compression failures. After **three failures**, the system auto-disables to prevent infinite loops, clears the persistence flag, and displays a warning message to the user.

## Code Implementation Examples

The auto-clarity logic relies on specific file operations and environment checks.

```javascript
// src/hooks/caveman-activate.js – auto-clarity detection
if (output.length > AUTO_CLARITY_MAX_TOKENS && !process.env.CAVEMAN_DISABLE_AUTO_CLARITY) {
  // compress the output the same way `/caveman full` would
  const compressed = compress(output);
  writeFlag('.caveman-auto-clarity');   // remember the state for the next turn
  return compressed;
}

```

```javascript
// src/hooks/caveman-mode-tracker.js – safety-triggered disable
if (/dangerous|execute|delete/.test(output) || process.env.CAVEMAN_DISABLE_AUTO_CLARITY) {
  removeFlag('.caveman-auto-clarity');
  ctx.say('⚠️  Auto-clarity disabled for safety – sending full response.');
}

```

```bash

# User explicitly turns off auto-clarity

/caveman off   # removes the flag and stops auto-compression

```

## Summary

- Auto-clarity automatically compresses verbose LLM outputs in [`src/hooks/caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-activate.js) when token thresholds exceed defined limits.
- The system creates a `.caveman-auto-clarity` flag file to persist compression state across conversation turns.
- Caveman disables auto-clarity when users run `/caveman off`, when safety-regex patterns match risky content, when `CAVEMAN_DISABLE_AUTO_CLARITY=1` is set, or after three consecutive compression failures.
- These safeguards ensure safety-critical instructions and code examples remain fully visible and unmodified.

## Frequently Asked Questions

### What triggers the auto-clarity feature in Caveman?

Auto-clarity triggers when the output length exceeds `AUTO_CLARITY_MAX_TOKENS` and the system detects filler patterns indicating unnecessary verbosity. The hook in [`src/hooks/caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-activate.js) then applies compression automatically without requiring the `/caveman` command.

### How do I manually disable auto-clarity if I need full responses?

Type `/caveman off` in your session. This command removes the `.caveman-auto-clarity` flag file and suspends automatic compression for the remainder of your current session, ensuring you receive complete, uncompressed outputs.

### Why does Caveman disable itself when it detects code examples?

Caveman disables auto-clarity for safety-critical content—including executable code, deletion commands, or dangerous instructions—to prevent accidental truncation of vital implementation details or safety warnings that could lead to system harm if partially hidden.

### Can I disable auto-clarity globally for all Caveman sessions?

Yes. Set the environment variable `CAVEMAN_DISABLE_AUTO_CLARITY=1` in your shell configuration or CI pipeline. This global override, referenced in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) and [`src/hooks/caveman-mode-tracker.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-mode-tracker.js), bypasses all auto-clarity logic for the entire runtime duration.