# What Hooks Does Caveman Install for Automatic Activation on Claude Code? > Discover the seven hook scripts installed by Caveman for automatic activation on Claude Code. Learn how Caveman registers for SessionStart and UserPromptSubmit events. - Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman) - Tags: internals - Published: 2026-07-12 --- **Caveman installs seven hook scripts and a [`package.json`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/install.sh) (line 40), Caveman copies the following seven files into Claude Code's hooks directory: - **[`package.json`](https://github.com/JuliusBrussee/caveman/blob/main/package.json)** – Minimal Node.js package descriptor required for the hook bundle to load correctly. - **[`caveman-config.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-config.js)** – Provides the `caveman-config` CLI utility that other hooks call to read and write shared state. - **[`caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-statusline.sh)** – Shell script that displays a badge in Claude Code's status bar indicating the active Caveman mode. - **[`cavecrew-model-overrides.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-mode-tracker.js)** – Captures the current mode (lite, ultra, or commit) and updates the visual indicator. - **[`caveman-stats.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-stats.js)** – Listens for the `/caveman-stats` command invocation to return real-time token usage data. ### Status Line Integration The [`caveman-statusline.sh`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-statusline.sh) script is referenced through the `statusLine` entry in [`settings.json`](https://github.com/JuliusBrussee/caveman/blob/main/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: ```bash # 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: ```bash # 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: ```bash # View hook registrations cat ~/.claude/settings.json | jq '.hooks' ``` You should see entries mapping `SessionStart` to [`caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-mode-tracker.js) hook updates the status-line badge via the `UserPromptSubmit` event. 3. **Usage statistics:** Typing `/caveman-stats` triggers [`caveman-stats.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/package.json) plus six scripts) are installed to `~/.claude/hooks` by [`src/hooks/install.sh`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-activate.js) for initial activation) and `UserPromptSubmit` (handled by [`caveman-mode-tracker.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-mode-tracker.js) and [`caveman-stats.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/settings.json) registrations without duplicating entries. ### Does Caveman require manual configuration after installation? No. Once the hooks are installed via [`src/hooks/install.sh`](https://github.com/JuliusBrussee/caveman/blob/main/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.