How the Claude Code Hook Enables Automatic Caveman Activation from the First Message

The Claude Code SessionStart hook (caveman-activate.js) automatically injects the Caveman ruleset into the initial prompt context before any user input is processed, ensuring the selected mode is active immediately.

The Caveman project (JuliusBrussee/caveman) provides a Claude Code integration that activates specialized behavior patterns from the moment a chat session begins. By leveraging Claude Code's SessionStart hook mechanism, the system ensures that the Caveman ruleset is present in the model's context before the first user message arrives.

How the SessionStart Hook Works

The activation logic resides in src/hooks/caveman-activate.js, which Claude Code executes automatically whenever a new chat session starts. This hook performs three critical operations to establish the Caveman environment.

Determining the Intensity Level

First, the hook reads the default mode from caveman-config.js by calling getDefaultMode(). If the configuration returns off, the hook short-circuits and exits without further action. This check occurs early in the execution flow (lines 25–33), preventing unnecessary processing when Caveman is disabled.

Persisting the Active State

When a valid mode is detected, the hook writes a flag file to $CLAUDE_CONFIG_DIR/.caveman-active using the safeWriteFlag() utility. This file records the current mode for persistence across the session. Additionally, the hook calls recordModeChange() to append a timestamped entry to the transition log (lines 35–38), enabling audit trails and status-line synchronization.

Injecting the Ruleset

The core functionality loads the canonical SKILL.md file from one of three possible locations within the repository. The hook strips any YAML frontmatter and filters the intensity table to emit only the rows matching the active mode (lines 59–86). If the skill file cannot be located—such as in a standalone installation—the hook falls back to a built-in ruleset (lines 20–40). Because this execution happens before Claude Code processes any user input, the filtered ruleset becomes part of the initial system prompt.

Configuration and Status Line Detection

Beyond ruleset injection, the hook ensures the user interface reflects the active state.

Detecting Missing Status Line Configuration

The hook inspects settings.json to verify the presence of a statusLine entry. If the configuration is absent, the script adds a non-blocking notification suggesting how to configure the status-line badge (lines 42–67). This ensures users are aware of the active mode without interrupting the session start.

Key Files and Implementation Details

The automatic activation relies on several coordinated components:

• src/hooks/caveman-activate.js: The SessionStart hook that orchestrates activation, flag persistence, and ruleset emission.
• src/hooks/caveman-config.js: Provides getDefaultMode(), safeWriteFlag(), and recordModeChange() utilities.
• src/hooks/caveman-statusline.sh: Renders the [CAVEMAN] badge in the Claude Code UI.
• skills/caveman/SKILL.md: The human-editable source of truth for Caveman behavior patterns.

Configuration Examples

To customize the default intensity level, set the CAVEMAN_DEFAULT_MODE environment variable before starting Claude Code:

export CAVEMAN_DEFAULT_MODE=ultra   # Options: off | lite | full | ultra | commit | review | compress | wenyan

After the first session activates, verify the flag file:

cat $HOME/.claude/.caveman-active

# → "ultra"

To enable the status-line badge permanently, add the following to your Claude Code settings:

{
  "statusLine": {
    "type": "command",
    "command": "bash \"$HOME/.claude/hooks/caveman-statusline.sh\""
  }
}

Summary

• The SessionStart hook (caveman-activate.js) executes automatically before the first user message, ensuring zero-latency activation.
• Mode determination relies on getDefaultMode() from caveman-config.js, with immediate exit if set to off.
• The hook persists state via safeWriteFlag() and logs transitions via recordModeChange().
• Ruleset injection filters SKILL.md content by intensity level, with a built-in fallback for standalone installs.
• Status-line detection provides optional UI configuration without blocking session initialization.

Frequently Asked Questions

What triggers the Caveman activation hook?

The hook runs automatically when Claude Code initializes a new chat session. Claude Code's hook system executes src/hooks/caveman-activate.js before processing any user input, ensuring the ruleset is present in the initial context.

Can I disable automatic activation while keeping the hook installed?

Yes. Set the CAVEMAN_DEFAULT_MODE environment variable to off, or configure the default mode in caveman-config.js. When getDefaultMode() returns off, the hook exits immediately without emitting the ruleset or creating the flag file.

Where does the Caveman ruleset come from?

The hook prioritizes skills/caveman/SKILL.md within the repository, stripping frontmatter and filtering by intensity. If this file is unavailable, the hook emits a built-in fallback ruleset hardcoded in caveman-activate.js (lines 20–40).

How does the status line know which mode is active?

The hook writes the current mode to $CLAUDE_CONFIG_DIR/.caveman-active using safeWriteFlag(). The caveman-statusline.sh script reads this file to display the [CAVEMAN] badge with the correct intensity level in the Claude Code interface.

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