How to Verify Caveman Installation: 5 Steps to Confirm Your Setup

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. It registers each detected CLI binary found on your PATH.

Listing Detected Agents

Run the following command to display the detection matrix:

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, caveman-mode-tracker.js, and caveman-stats.js. These write to $CLAUDE_CONFIG_DIR/hooks/ and merge into settings.json via the tolerant parser in bin/lib/settings.js.

Triggering the Caveman Command

Open Claude Code and enter:

/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 hook failed to fire. The underlying rule logic lives in 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:

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:

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:

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:

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 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 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.
• 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 exists in $CLAUDE_CONFIG_DIR/hooks/ and that settings.json includes the hook entries merged by 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, caveman-mode-tracker.js, and 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. To restore, copy this backup file over settings.json and delete the three caveman-*.js files from the hooks directory. Then remove the .caveman-active flag file to complete the uninstallation.

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