Boundaries and Exceptions for Caveman Mode: A Complete Technical Guide

Caveman mode is a session-wide style compression skill that rewrites every agent reply in terse "caveman" prose while preserving all technical content, governed by explicit activation triggers in src/hooks/caveman-mode-tracker.js and safety exceptions defined in skills/caveman/SKILL.md that automatically disable the style for code blocks, security warnings, and ambiguous instructions.

The JuliusBrussee/caveman repository implements a sophisticated prose compression system that persists across entire user sessions. Understanding the boundaries and exceptions for caveman mode is essential for developers integrating this tooling, as the system carefully balances brevity against clarity and safety constraints.

How Activation and Deactivation Work

Caveman mode operates as a persistent session state rather than a temporary toggle. Once activated, it remains active until explicitly disabled through specific trigger phrases or direct flag manipulation.

Session-Wide Persistence

According to the implementation in skills/caveman/SKILL.md (lines 13-18), the mode maintains its state across all subsequent turns in a conversation. Unlike temporary formatting requests, caveman mode never auto-reverts after a few exchanges. The hook writes a flag file that persists until a deactivation command is detected or the session ends.

Deactivation Triggers and Phrases

The runtime hook in src/hooks/caveman-mode-tracker.js (lines 38-46) monitors for specific case-insensitive phrases to disable the mode instantly:

• stop caveman, disable caveman, deactivate caveman, quit caveman, exit caveman, kill caveman
• caveman mode off, caveman mode stop, caveman mode disabled
• turn off caveman
• normal mode (only when appearing at the start of the prompt or together with "caveman")

When any of these phrases are detected, the hook removes the flag file immediately, causing subsequent responses to revert to standard prose.

Questions That Bypass Activation

Not all mentions of "caveman" trigger the mode. The parser specifically ignores questions to prevent accidental activation during informational queries. As implemented in src/hooks/caveman-mode-tracker.js (lines 48-52), prompts like "what is caveman mode?" or "does caveman lite drop articles?" are classified as isQuestion and receive descriptive answers instead of toggling the state.

Automatic Activation Triggers

Natural language triggers in src/hooks/caveman-mode-tracker.js (lines 59-65) automatically enable the default mode when the user says:

• "activate caveman"
• "turn on caveman mode"
• "talk like caveman"
• Brevity requests such as "less tokens" or "be brief"

Important: These activations are suppressed if a deactivation phrase appears simultaneously in the same prompt.

Operational Boundaries and Content Restrictions

The system enforces strict boundaries regarding where caveman compression applies, ensuring technical accuracy and safety are never compromised by stylistic brevity.

Code and Technical Content Protection

As specified in skills/caveman/SKILL.md (lines 11-26 and the "Boundaries" paragraph at lines 76-78), caveman compression never touches:

• Code blocks and syntax-highlighted content
• CLI commands and shell instructions
• Error strings and stack traces
• Version-control messages (commits, PRs, diffs)

All technical artifacts remain in standard formal prose regardless of the active mode.

Self-Reference Restrictions

The agent must never announce the mode change with phrases like "Caveman mode on" or similar meta-commentary. The only exception occurs when the user explicitly asks "what is caveman mode?"—in this specific case, the skill is permitted to provide a descriptive explanation.

Safety Exceptions and Auto-Clarity

The "Auto-Clarity" section in skills/caveman/SKILL.md (lines 58-65) mandates automatic disabling of caveman mode for replies containing:

• Security warnings and vulnerability disclosures
• Irreversible-action confirmations (e.g., destructive database operations)
• Multi-step instructions where missing conjunctions could cause dangerous ambiguity
• Potentially unclear compression (e.g., "migrate table drop column backup first" where brevity risks misinterpretation)

Additionally, the style applies only to the language the user is currently speaking; the system never forces English or adds introductory phrasing (lines 23-24).

Independent One-Shot Skills vs. Persistent Mode

The repository provides several standalone skills that operate independently of the session-wide mode state.

Temporary Mode Preservation

Skills such as /caveman-commit, /caveman-review, and /caveman-compress are classified as independent modes in src/hooks/caveman-mode-tracker.js (lines 11-14 and 101-115). When these execute:

1. The current prose mode is saved to a temporary prev flag
2. The one-shot skill runs with its specific compression level
3. The original mode is automatically restored on the next regular turn

This architecture ensures that using a commit-specific caveman style does not permanently alter the session's default prose setting.

{
  "prompt": "/caveman-commit"
}

This command runs the commit message generator in caveman style while preserving whatever mode was active before the command.

Security and Validation Mechanisms

The hook implements defensive programming to prevent mode flag corruption from affecting system behavior.

Flag File Validation

When reading the mode status, src/hooks/caveman-mode-tracker.js (lines 71-73 and 174-176) employs a safe helper that validates:

• File size limits (prevents DoS via massive flag files)
• Symlink resolution (prevents directory traversal attacks)
• VALID_MODES whitelist (ensures only recognized mode strings are processed)

If the flag file is corrupted, contains invalid data, or fails security checks, the mode is ignored entirely, defaulting to standard prose to avoid injecting untrusted instructions into the context.

Summary

• Caveman mode persists for the entire session once activated, only deactivating upon explicit command or session end.
• Deactivation requires specific phrases like "stop caveman" or "normal mode" parsed by src/hooks/caveman-mode-tracker.js.
• Technical content including code blocks, CLI commands, and commits are permanently exempt from compression.
• Safety overrides automatically disable the mode for security warnings, destructive operations, and ambiguous multi-step instructions.
• Independent skills (/caveman-commit, /caveman-review, /caveman-compress) temporarily override the mode without changing persistent session state.
• Flag validation ensures corrupted or malicious mode files cannot compromise the system via whitelist checking in caveman-config.js.

Frequently Asked Questions

What happens if I ask "what is caveman mode"?

The system treats this as an informational question (isQuestion detection in src/hooks/caveman-mode-tracker.js lines 48-52) rather than an activation command. The agent will provide a descriptive explanation of the feature without toggling the mode flag or changing your current session state.

Does caveman mode affect code snippets and terminal commands?

No. According to the boundaries defined in skills/caveman/SKILL.md (lines 76-78), code blocks, CLI commands, error strings, and version-control messages are always rendered in normal formal style. The compression applies only to conversational prose and explanations.

Can I use caveman style for just one commit message without changing my session mode?

Yes. Use the /caveman-commit command (or /caveman-review, /caveman-compress). These independent skills temporarily save your current mode, apply caveman compression for that specific task, and restore your previous setting on the next turn, as implemented in the INDEPENDENT_MODES logic of caveman-mode-tracker.js (lines 101-115).

Why did the agent switch back to normal mode during a security warning?

The Auto-Clarity safety mechanism in skills/caveman/SKILL.md (lines 58-65) automatically suppresses caveman compression for any content containing security warnings, irreversible actions, or complex multi-step instructions where brevity could create dangerous ambiguity. This ensures critical safety information is communicated with full clarity and conjunctions.

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