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

> Troubleshoot Caveman installation issues. Verify agent detection, check PATH, and use --force to fix Claude Code or other AI agent recognition problems with this complete guide.

- Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman)
- Tags: how-to-guide
- Published: 2026-07-06

---

**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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/settings.json). For agents without hook systems (Cursor, Windsurf, Copilot), the **`--with-init`** flag drops a static markdown rule file ([`caveman-activate.md`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-activate.js)
2. Verify **`$CLAUDE_CONFIG_DIR/.caveman-active`** contains `full`
3. Re-run the installer with **`--force`** to rewrite the hooks:

```bash
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:

```powershell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

```

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

### Corrupted [`settings.json`](https://github.com/JuliusBrussee/caveman/blob/main/settings.json) After Reinstall

**Symptom:** Claude Code configuration broke after running the installer.

**Cause:** A malformed merge overwrote the original [`settings.json`](https://github.com/JuliusBrussee/caveman/blob/main/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:

```bash
node bin/install.js --list

```

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

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

```

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

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

```

Force a reinstall of specific components:

```bash

# 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:

```bash
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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-activate.js) (session start) and [`caveman-mode-tracker.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-mode-tracker.js) (post-prompt)
- **[`src/rules/caveman-activate.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md)**: Static markdown rule for agents without hook systems
- **[`src/plugins/opencode/plugin.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`.