# How to Verify Caveman Installation: 5 Steps to Confirm Your Setup > Easily verify your Caveman installation in 5 steps. Confirm agent detection, check for the .caveman-active flag, and ensure your setup is working correctly. - Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman) - Tags: how-to-guide - Published: 2026-07-07 --- **Run `node bin/install.js --list` to check agent detection, trigger `/caveman` in Claude Code for a terse response, and confirm the `.caveman-active` flag file exists in your Claude config directory.** The Caveman project by JuliusBrussee/caveman is an AI-coding agent optimizer that hooks into Claude Code and other providers to reduce token usage. After running the installer, you must verify that the three core installation steps—agent detection, hook injection, and flag file creation—completed successfully. This guide walks through five specific verification methods using the actual source files from the repository. ## Check Agent Detection with the Install Script The installer first scans your system for supported AI coding agents using the **PROVIDERS** array defined in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js). It registers each detected CLI binary found on your `PATH`. ### Listing Detected Agents Run the following command to display the detection matrix: ```bash node bin/install.js --list ``` You should see a table of approximately 30 rows with a "✓" next to each detected agent. Missing detections indicate the corresponding CLI binary is not accessible in your `PATH` environment variable. ## Test the Claude Code Integration Caveman modifies Claude Code behavior by installing three JavaScript hooks: [`caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-activate.js), [`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). These write to `$CLAUDE_CONFIG_DIR/hooks/` and merge into [`settings.json`](https://github.com/JuliusBrussee/caveman/blob/main/settings.json) via the tolerant parser in [`bin/lib/settings.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/lib/settings.js). ### Triggering the Caveman Command Open Claude Code and enter: ```text /caveman ``` **Expected behavior:** The response should be terse, such as "Got it. Caveman mode on." or a compressed technical answer like "Wrap object in useMemo". A verbose response indicates the [`caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-activate.js) hook failed to fire. The underlying rule logic lives in [`src/rules/caveman-activate.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md). ## Verify the Flag File and Hook Installation The installer creates a persistent flag to track activation state. Verifying this file and the hook configuration confirms the installation wrote data to disk correctly. ### Inspect the Activation Flag Check the existence and content of the flag file: ```bash cat "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/.caveman-active" ``` The output should read `full` (or `lite`, depending on your selected mode). If the file is missing or empty, the SessionStart hook never executed. Re-run the installer with `--force` or inspect the hook files for syntax errors. ### Confirm Hook Files in settings.json Verify the three hook files exist in the hooks directory: ```bash ls "$CLAUDE_CONFIG_DIR/hooks/caveman-activate.js" \ "$CLAUDE_CONFIG_DIR/hooks/caveman-mode-tracker.js" \ "$CLAUDE_CONFIG_DIR/hooks/caveman-stats.js" ``` Then confirm they are registered in Claude Code's settings: ```bash grep -A2 '"hooks"' "$CLAUDE_CONFIG_DIR/settings.json" ``` Both commands should reference the three `caveman-*.js` filenames. The installer creates a `settings.json.bak` backup before modifying the file, preserving your original configuration. ## Run the Automated Verification Test Suite The repository includes a Python test harness that automates the manual checks above. Run the comprehensive verification suite: ```bash python -m pytest tests/verify_repo.py ``` All tests should pass, confirming that agents are detected, hook files are present, and the flag file contains the expected mode. Failures in this suite point directly to the specific missing component. ## Troubleshooting Common Verification Failures If any verification step fails, check these specific components: - **Missing agent detection**: Ensure the CLI binary (e.g., `claude`, `gemini`, `opencode`) is in your `PATH` before running the installer. - **Missing flag file**: Indicates [`caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-activate.js) did not execute. Check the Claude Code logs for hook execution errors. - **Corrupted settings.json**: Restore from the automatic backup at `settings.json.bak` and re-run `node bin/install.js --force`. ## Summary - Run `node bin/install.js --list` to verify the **PROVIDERS** array detected your AI agents. - Trigger **/caveman** in Claude Code and expect a terse response confirming [`caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-activate.js) fired. - Check **`$CLAUDE_CONFIG_DIR/.caveman-active`** for the mode string (`full` or `lite`). - Confirm the three **hook files** exist in the hooks directory and appear in [`settings.json`](https://github.com/JuliusBrussee/caveman/blob/main/settings.json). - Execute `python -m pytest tests/verify_repo.py` to validate the entire installation chain. ## Frequently Asked Questions ### What should I do if the /caveman command returns a verbose response? A verbose response means the Claude Code hook did not intercept the command. Verify that [`caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-activate.js) exists in `$CLAUDE_CONFIG_DIR/hooks/` and that [`settings.json`](https://github.com/JuliusBrussee/caveman/blob/main/settings.json) includes the hook entries merged by [`bin/lib/settings.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/lib/settings.js). If the files are present, restart Claude Code to reload the configuration. ### Where are the Caveman hook files stored? The three JavaScript hooks—[`caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-activate.js), [`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)—are stored in `$CLAUDE_CONFIG_DIR/hooks/`. The default location for `$CLAUDE_CONFIG_DIR` is `$HOME/.claude`, but you can override this with the environment variable. ### Can I verify Caveman installation without using Claude Code? Yes. While the `/caveman` command test requires Claude Code, you can verify the installation by checking the `.caveman-active` flag file, listing detected agents with `--list`, and running `python -m pytest tests/verify_repo.py`. These steps confirm the installer wrote the hooks and created the flag file regardless of which agents you actively use. ### How do I restore my original Claude Code settings if something goes wrong? The installer automatically creates a backup named `settings.json.bak` in your `$CLAUDE_CONFIG_DIR` before modifying [`settings.json`](https://github.com/JuliusBrussee/caveman/blob/main/settings.json). To restore, copy this backup file over [`settings.json`](https://github.com/JuliusBrussee/caveman/blob/main/settings.json) and delete the three `caveman-*.js` files from the hooks directory. Then remove the `.caveman-active` flag file to complete the uninstallation.