What Triggers Cause Caveman to Revert to Normal Mode Automatically

Caveman automatically reverts to normal mode when you issue explicit de‑activation commands, use specific "normal mode" phrasing, complete an independent one‑shot command, or start a new session.

The Caveman extension for Claude Code transforms prose into a prehistoric caveman style, but understanding what triggers cause caveman to revert to normal mode automatically is essential for controlling the conversation flow. In the JuliusBrussee/caveman repository, the mode tracking logic in src/hooks/caveman-mode-tracker.js defines four distinct conditions that disable the caveman persona and restore standard output.

Explicit De‑activation Commands

The most direct trigger relies on regex pattern matching at line 38 of src/hooks/caveman-mode-tracker.js. The wantsOff regex detects phrases that explicitly request deactivation.

When the user prompt matches any of the following patterns, the hook deletes the .caveman-active flag file, immediately reverting to normal mode:

• stop caveman, disable caveman, deactivate caveman, quit caveman, exit caveman, kill caveman
• caveman mode off, caveman off, caveman stop, caveman disabled
• turn off caveman

// From caveman-mode-tracker.js – line 38
// Matches explicit de‑activation commands
const wantsOff = /(stop|disable|deactivate|quit|exit|kill)\s+caveman|caveman\s+(mode\s+)?(off|stop|disabled)|turn\s+off\s+caveman/i;

if (wantsOff.test(prompt)) {
  // Delete .caveman-active flag → normal mode
  fs.unlinkSync(flagPath);
}

Natural Language "Normal Mode" Detection

At lines 42–46, a second regex handles natural language requests to return to standard formatting. This trigger only activates when "normal mode" appears at the start of the prompt (optionally preceded by polite verbs like "please," "go," or "switch to") or when the phrase appears alongside the word "caveman" anywhere in the text.

This positional requirement prevents false positives like "how do I exit vim normal mode" while allowing "go back to normal mode" or "caveman normal mode" to trigger deactivation.

// From caveman-mode-tracker.js – lines 42-46
// Matches command-style normal mode requests
const normalModePattern = /^(please\s+)?(go\s+|back\s+to\s+|switch\s+(back\s+)?to\s+|return\s+to\s+)?normal\s+mode\b/;

if (normalModePattern.test(prompt) || (prompt.includes('caveman') && prompt.includes('normal mode'))) {
  // Delete flag file → revert to normal
}

Independent Mode Completion

Commands such as /caveman-commit, /caveman-review, and /caveman-compress are independent modes that temporarily replace the current prose setting. According to lines 77–91 in caveman-mode-tracker.js, after these one‑shot commands execute, the hook automatically restores the previous mode or disables Caveman entirely if no prior prose mode was active.

The logic reads the saved *.caveman-active.prev state file and either restores it to the primary flag path or removes the flag entirely to revert to normal prose.

// From caveman-mode-tracker.js – lines 77-91
// Restoration logic after independent modes
if (activeMode && INDEPENDENT_MODES.has(activeMode) && !setIndependentThisTurn) {
  const prevPath = flagPath.replace('.caveman-active', '.caveman-active.prev');
  const previousMode = fs.existsSync(prevPath) ? fs.readFileSync(prevPath, 'utf8') : null;
  
  if (previousMode) {
    fs.writeFileSync(flagPath, previousMode); // Restore previous
  } else {
    fs.unlinkSync(flagPath); // No previous mode → normal
  }
}

Session Termination

When a conversation ends or the parent process crashes, the flag file persists on disk, but the next session initialization triggers a default state. The caveman-activate.js hook, located at line 5 of src/hooks/caveman-activate.js, writes the default mode flag (full) when a new session begins.

If the user never reactivates Caveman during this new session, the system effectively operates in normal mode until explicitly enabled again.

Summary

• Explicit commands matching the wantsOff regex at line 38 delete the active flag file.
• "Normal mode" phrasing at the conversation start (or paired with "caveman") triggers reversion via lines 42–46.
• Independent modes (/caveman-commit, /caveman-review, /caveman-compress) auto‑restore previous states or disable the flag after completion (lines 77–91).
• New sessions start with the default mode written by caveman-activate.js unless the user reactivates Caveman.

Frequently Asked Questions

How do I manually disable caveman mode?

You can disable caveman mode by typing any explicit de‑activation command such as "stop caveman", "disable caveman", or "turn off caveman". The hook at src/hooks/caveman-mode-tracker.js detects these phrases and deletes the .caveman-active flag file, immediately restoring normal prose.

Why does caveman ignore "normal mode" in some sentences?

The regex at lines 42–46 specifically requires "normal mode" to appear at the start of the prompt (optionally preceded by verbs like "go" or "switch to") or alongside the word "caveman". This prevents mid‑sentence matches like "how do I exit vim normal mode" from accidentally disabling the extension.

What happens after I run /caveman-commit?

The /caveman-commit, /caveman-review, and /caveman-compress commands operate as independent one‑shot modes. After the command completes, the logic between lines 77–91 of caveman-mode-tracker.js automatically restores the previously active prose mode or removes the caveman flag entirely if no prior mode existed, effectively reverting to normal output.

Where is the caveman mode state stored?

The active state is stored in a .caveman-active flag file in the workspace. When independent modes run, the previous state is temporarily saved to a .caveman-active.prev file. The caveman-mode-tracker.js hook manages these files to track whether caveman is currently enabled or disabled.

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