How to Troubleshoot Caveman Installation Issues: Complete Guide for AI Coding Agents

Troubleshoot Caveman installation issues by verifying agent detection with node bin/install.js --list, checking PATH variables, and using --force to rewrite hook configurations when Claude Code or other AI agents fail to recognize the plugin.

Caveman is a single-node installer that automatically detects AI coding agents on your machine and wires them with plugins, hooks, or static rule files. When installation fails, the issue typically stems from PATH detection errors, malformed configuration files, or incomplete hook registration in bin/install.js. Understanding the three-stage installation flow helps you pinpoint exactly where the process breaks.

How the Caveman Installer Works

The core installer logic resides in bin/install.js and executes in three distinct phases:

Phase 1: Provider Detection

The installer uses a static PROVIDERS matrix that maps each supported agent to detection rules like command:claude or vscode-ext:cursor. The detectMatch() function (lines 45-66) evaluates these rules to determine which agents are present on the system. If an agent binary is not on your PATH, the installer silently skips it without warning.

Phase 2: Agent-Specific Installation

Each detected agent triggers a dedicated installer function:

• installClaude() invokes claude plugin install for Claude Code
• installOpencode() and installOpenclaw() fall back to the generic Skills CLI using npx skills add for agents that only understand skill files

Phase 3: Hook and Rule File Wiring

For Claude Code, the installer writes JavaScript hook files to $CLAUDE_CONFIG_DIR/hooks and merges SessionStart and UserPromptSubmit entries into settings.json. For agents without hook systems (Cursor, Windsurf, Copilot), the --with-init flag drops a static markdown rule file (caveman-activate.md) into repository-specific directories like .cursor/rules/caveman.mdc.

Common Installation Failures and Solutions

Agent Not Detected Despite Being Installed

Symptom: The caveman command runs but the target agent does not respond to Caveman commands.

Cause: The agent binary is not on your PATH, causing the detectMatch() function to skip it.

Fix: Run node bin/install.js --list to verify detection status. Add the missing binary to your PATH or reinstall the agent.

Claude Code Shows No Caveman Badge

Symptom: The /caveman command does nothing and no Caveman badge appears in Claude Code.

Cause: Hook files were not wired correctly or settings.json points to a missing script.

Fix:

1. Open $CLAUDE_CONFIG_DIR/settings.json and look for a hook entry containing caveman-activate.js
2. Verify $CLAUDE_CONFIG_DIR/.caveman-active contains full
3. Re-run the installer with --force to rewrite the hooks:

node bin/install.js --force --only claude

Windows PowerShell Execution Policy Errors

Symptom: Installer aborts on Windows with "execution policy" errors when running install.ps1.

Cause: PowerShell's default security policy blocks downloaded scripts.

Fix: Run the following command before invoking the installer:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

Alternatively, use the PowerShell 5.1+ version of the script explicitly.

Corrupted settings.json After Reinstall

Symptom: Claude Code configuration broke after running the installer.

Cause: A malformed merge overwrote the original settings.json.

Fix: The installer backs up the original as settings.json.bak before any write. Restore this backup, then re-run with --force.

Missing Hook Files After Uninstall

Symptom: Strange behavior after running --uninstall.

Cause: The uninstaller removes only Caveman-owned files; stray copies may remain.

Fix: Manually delete any leftover caveman-*.js files under $CLAUDE_CONFIG_DIR/hooks.

Opencode JSON Parse Errors

Symptom: Installer reports "unparseable opencode.json".

Cause: The JSONC parser failed due to stray commas or syntax errors in ~/.config/opencode/opencode.json.

Fix: Open the file and fix the JSON syntax, then retry the installer.

Step-by-Step Troubleshooting Workflow

Use these commands to diagnose and repair installation issues:

First, verify what the installer detects:

node bin/install.js --list

Perform a dry-run to preview commands without executing them:

node bin/install.js --dry-run --all

Check Claude Code's hook configuration (replace $HOME with your home directory):

cat "$HOME/.claude/settings.json" | grep caveman-activate
cat "$HOME/.claude/.caveman-active"

Force a reinstall of specific components:

# Force reinstall Claude plugin and hooks

node bin/install.js --force --only claude

# Install only Cursor with always-on rule files, without touching Claude

node bin/install.js --only cursor --with-init

For a complete uninstall and fresh start:

npx -y github:JuliusBrussee/caveman -- --uninstall

Key Files to Inspect During Debugging

When troubleshooting, examine these specific files from the JuliusBrussee/caveman repository:

• bin/install.js: The unified installer that parses flags, detects providers, and delegates to per-agent installers
• src/hooks/*: Hook scripts including caveman-activate.js (session start) and caveman-mode-tracker.js (post-prompt)
• src/rules/caveman-activate.md: Static markdown rule for agents without hook systems
• src/plugins/opencode/plugin.js: Opencode plugin entry point connecting Caveman skills
• ~/.claude/settings.json: Claude Code configuration file containing hook entries
• ~/.config/opencode/opencode.json: Opencode configuration (JSONC format)

Summary

• Detection depends on PATH: If node bin/install.js --list misses an agent, verify the binary is in your system PATH
• Claude Code requires hook verification: Check $CLAUDE_CONFIG_DIR/settings.json for caveman-activate.js entries and use --force to regenerate
• Windows requires special handling: Use Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass before running PowerShell installers
• Backups exist: The installer creates settings.json.bak before modification; restore it if corruption occurs
• Agent-specific debugging: Use --only <agent> and --dry-run flags to isolate and test individual installations without affecting working configurations

Frequently Asked Questions

Why does Caveman say my agent is not detected when I have it installed?

The installer relies on the detectMatch() function in bin/install.js to check for agent binaries using the PROVIDERS matrix rules. If the agent executable is not in your shell's PATH environment variable, Caveman cannot find it. Run node bin/install.js --list to see exactly which agents are visible to the installer, then add the missing installation directory to your PATH.

How do I fix Claude Code when it does not recognize Caveman commands?

First, verify that $CLAUDE_CONFIG_DIR/.caveman-active contains full and that $CLAUDE_CONFIG_DIR/settings.json includes a SessionStart hook pointing to caveman-activate.js. If these entries are missing or corrupted, run node bin/install.js --force --only claude to rewrite the configuration. The --force flag ensures the installer overwrites existing hook files even if previous installations partially succeeded.

What should I do if the installer corrupts my Claude Code settings.json?

The installer automatically creates a backup at settings.json.bak before modifying the original file. If a merge operation corrupts your configuration, restore the backup manually by copying it back to settings.json, then re-run the installer with --force to attempt a clean installation. Check the JSON syntax using a validator before restarting Claude Code.

How can I preview what Caveman will install before actually running it?

Use the --dry-run flag to simulate the installation without executing any commands. Run node bin/install.js --dry-run --all to see every command that would be executed across all detected agents, or add --only <agent> to preview changes for a specific agent. This is particularly useful for verifying PATH detection and understanding which hook files will be written to $CLAUDE_CONFIG_DIR.

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