What Hooks Does Caveman Install for Automatic Activation on Claude Code?

Caveman installs seven hook scripts and a package.json manifest that automatically activate the tool inside Claude Code by registering for SessionStart and UserPromptSubmit events.

The open-source project JuliusBrussee/caveman extends Claude Code's capabilities through a suite of JavaScript and shell hooks. These files are copied into ~/.claude/hooks and wired into ~/.claude/settings.json to enable automatic activation, mode tracking, and token statistics without manual intervention.

The Seven Hook Files Installed by Caveman

According to the installer script at src/hooks/install.sh (line 40), Caveman copies the following seven files into Claude Code's hooks directory:

• package.json – Minimal Node.js package descriptor required for the hook bundle to load correctly.
• caveman-config.js – Provides the caveman-config CLI utility that other hooks call to read and write shared state.
• caveman-activate.js – SessionStart hook that runs once when Claude Code starts a new session, injecting the caveman-activate command into the system context.
• caveman-mode-tracker.js – UserPromptSubmit hook that tracks which Caveman mode (lite, ultra, commit, etc.) is active and updates the status-line badge.
• caveman-stats.js – UserPromptSubmit hook that reads the Claude Code session log and returns token-usage statistics when users run /caveman-stats.
• caveman-statusline.sh – Shell script that displays a badge in Claude Code's status bar indicating the active Caveman mode.
• cavecrew-model-overrides.js – Supplies model-override metadata for the built-in cavecrew agents (reviewer, investigator, builder).

How the Hooks Register for Claude Code Events

Automatic activation relies on event-based hook registration. The installer (src/hooks/install.sh, lines 61-78) idempotently injects entries into ~/.claude/settings.json that map specific events to the hook scripts.

SessionStart Activation

The caveman-activate.js script registers for the SessionStart event. When Claude Code launches a new session, this hook executes automatically and exposes the /caveman slash command family.

UserPromptSubmit Tracking

Two hooks register for the UserPromptSubmit event:

• caveman-mode-tracker.js – Captures the current mode (lite, ultra, or commit) and updates the visual indicator.
• caveman-stats.js – Listens for the /caveman-stats command invocation to return real-time token usage data.

Status Line Integration

The caveman-statusline.sh script is referenced through the statusLine entry in settings.json, displaying a real-time "Caveman ⚡" badge in the Claude Code UI.

Installing and Verifying the Hooks

Install the hooks by running the installer script from the repository root:

# Standard installation

bash src/hooks/install.sh

# Force reinstall (overwrites existing hooks)

bash src/hooks/install.sh --force

Verify the installation by checking the hooks directory and settings configuration:

# List installed Caveman hooks

ls ~/.claude/hooks | grep caveman

Expected output:

package.json
caveman-config.js
caveman-activate.js
caveman-mode-tracker.js
caveman-stats.js
caveman-statusline.sh
cavecrew-model-overrides.js

Inspect the event registrations in Claude Code's settings:

# View hook registrations

cat ~/.claude/settings.json | jq '.hooks'

You should see entries mapping SessionStart to caveman-activate.js and UserPromptSubmit to the tracker and stats scripts.

How Automatic Activation Works in Practice

Once installed, Caveman operates silently in the background:

1. First session after install: Claude Code automatically executes caveman-activate.js on SessionStart, making the /caveman command family available immediately.
2. Mode switching: When you run /caveman lite, /caveman ultra, or /caveman-commit, the caveman-mode-tracker.js hook updates the status-line badge via the UserPromptSubmit event.
3. Usage statistics: Typing /caveman-stats triggers caveman-stats.js to parse the session log and return token consumption data.

This architecture ensures that Caveman's functionality is available from the moment Claude Code starts, without requiring manual activation commands.

Summary

• Seven hook files (package.json plus six scripts) are installed to ~/.claude/hooks by src/hooks/install.sh.
• Event-based activation occurs through SessionStart (for initial activation) and UserPromptSubmit (for mode tracking and statistics).
• Configuration injection happens automatically in ~/.claude/settings.json during installation.
• Status line integration displays the active mode via caveman-statusline.sh.
• Zero manual configuration is required after running the install script.

Frequently Asked Questions

What Claude Code events does Caveman hook into?

Caveman registers hooks for two primary events: SessionStart (handled by caveman-activate.js for initial activation) and UserPromptSubmit (handled by caveman-mode-tracker.js and caveman-stats.js for mode tracking and statistics collection).

Where are the Caveman hook files installed?

The installer copies all seven files to ~/.claude/hooks/ and updates ~/.claude/settings.json to register the event handlers. This location is the standard Claude Code configuration directory on macOS and Linux systems.

How do I reinstall or update the Caveman hooks?

Run bash src/hooks/install.sh --force from the repository root. The --force flag overwrites existing hook files and refreshes the settings.json registrations without duplicating entries.

Does Caveman require manual configuration after installation?

No. Once the hooks are installed via src/hooks/install.sh, activation is fully automatic. The SessionStart hook initializes Caveman when Claude Code launches, and subsequent interactions are handled through the UserPromptSubmit event listeners.

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