What Is the .caveman-active Flag File in Caveman?

The .caveman-active flag file acts as the central state marker that indicates whether the Caveman tool-chain is active and which operating mode (such as full, ultra, or lite) it should use.

The .caveman-active flag file serves as the single source of truth for session state in the JuliusBrussee/caveman project. Located in $CLAUDE_CONFIG_DIR/.caveman-active (falling back to ~/.claude/.caveman-active), this file enables coordination between various hooks and plugins by persistently tracking whether Caveman is turned on and what mode configuration applies.

How the .caveman-active Flag File Works

Activation and Mode Selection

When a user invokes a Caveman command such as /caveman, the system writes the selected mode into the flag file. According to src/hooks/README.md, the activation hook writes values like full, ultra, lite, or wenyan-ultra to $CLAUDE_CONFIG_DIR/.caveman-active via the symlink-safe safeWriteFlag() helper.

The default location follows this resolution order:

1. $CLAUDE_CONFIG_DIR/.caveman-active (if environment variable is set)
2. ~/.claude/.caveman-active (fallback location)

Mode Tracking Across Hooks

The mode-tracker hook in src/hooks/caveman-mode-tracker.js calls readFlag() to obtain the current mode from the file. This allows the system to determine which behavior to apply, such as whether to prepend /caveman instructions or which model overrides to load during the session.

Deactivation Behavior

Removing the file signals that Caveman is off for the current session. The test suite verifies this behavior—test_caveman_stats.js explicitly checks that "No .caveman-active flag — caveman is off at stats time" to ensure proper state detection.

Security and Atomicity

Symlink-Safe Writing with safeWriteFlag

All writes to the .caveman-active flag file use safeWriteFlag(), defined in src/hooks/caveman-config.js, which implements several security measures:

• Refuses symlinked targets to prevent path hijacking
• Uses O_NOFOLLOW where available to avoid following symbolic links
• Performs atomic rename operations to eliminate race conditions

These protections ensure the flag file remains a trustworthy indicator of user intent and prevents symlink-clobber attacks.

Working with the .caveman-active Flag File in Code

The src/hooks/caveman-config.js module provides utilities to interact with the flag file programmatically:

const { safeWriteFlag, readFlag } = require('./caveman-config');
const path = require('path');
const fs = require('fs');

// Define the flag path
const flagPath = path.join(process.env.CLAUDE_CONFIG_DIR || '~/.claude', '.caveman-active');

// Activate Caveman in "full" mode
safeWriteFlag(flagPath, 'full');

// Check current mode anywhere in the codebase
const currentMode = readFlag(flagPath);
console.log('Caveman mode:', currentMode); // → "full"

// Deactivate Caveman by removing the flag
fs.unlinkSync(flagPath);

These helpers are consumed throughout the hook suite, including caveman-activate.js and caveman-mode-tracker.js, to maintain consistent state management.

Summary

• The .caveman-active flag file stores the activation state and selected mode (e.g., full, ultra, lite) for Caveman sessions
• Located at $CLAUDE_CONFIG_DIR/.caveman-active with fallback to ~/.claude/.caveman-active
• safeWriteFlag() and readFlag() in src/hooks/caveman-config.js manage atomic, symlink-safe operations
• Mode tracker hooks read this file to coordinate behavior across the tool-chain
• Deletion of the file immediately disables Caveman for the current session

Frequently Asked Questions

Where is the .caveman-active flag file located?

The file resides at $CLAUDE_CONFIG_DIR/.caveman-active by default. If the CLAUDE_CONFIG_DIR environment variable is unset, it falls back to ~/.claude/.caveman-active as documented in src/hooks/README.md.

What values can be stored in the .caveman-active flag file?

The file contains mode identifiers such as full, ultra, lite, or wenyan-ultra. These values determine which behavior the Caveman hooks apply during the session, such as specific instruction prepending or model overrides.

How does Caveman prevent security issues with the flag file?

The safeWriteFlag() function in src/hooks/caveman-config.js implements symlink protection by refusing symlinked targets, using O_NOFOLLOW where available, and performing atomic rename operations to prevent race conditions and symlink-clobber attacks.

What happens if the .caveman-active file is deleted?

Deleting the file deactivates Caveman for the current session. The mode-tracker hook interprets the absence of the file as an "off" state, and the test suite (including test_caveman_stats.js) verifies that operations return to default behavior when the flag is missing.

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