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

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 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 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) 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.

// 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;
}

// 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.');
}

# 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 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 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 and src/hooks/caveman-mode-tracker.js, bypasses all auto-clarity logic for the entire runtime duration.

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