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

> Discover the purpose of the .caveman-active flag file in Caveman. Learn how it controls the tool-chain's active state and operating mode for efficient workflows.

- Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman)
- Tags: explanation
- Published: 2026-08-22

---

**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](https://github.com/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-config.js) module provides utilities to interact with the flag file programmatically:

```javascript
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`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-activate.js) and [`caveman-mode-tracker.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/test_caveman_stats.js)) verifies that operations return to default behavior when the flag is missing.