How to Uninstall Caveman from a Specific Agent While Keeping It for Others

To uninstall Caveman from a specific agent while keeping it for others, run the global uninstall command to remove all traces, then reinstall only the agents you want to keep using the --only <agent-id> flag.

Caveman is a multi-agent development tool by JuliusBrussee that integrates with Claude Code, Opencode, Gemini, and OpenClaw. While the installer provides a global --uninstall flag that wipes every supported agent simultaneously, the source code in bin/install.js reveals that selective removal requires a specific workflow. This guide explains how to remove Caveman from just one agent while preserving functionality for the rest.

The Global Uninstall Limitation

The bin/install.js script implements an all-or-nothing uninstall routine (lines 1150–1320) that removes hook files, plugin entries, and configuration blocks across all supported agents simultaneously. There is no --uninstall <agent> flag. This design ensures complete cleanup of the .caveman-active flag and prevents configuration drift, but it means you cannot remove Caveman from just one agent without initially affecting the others.

According to the JuliusBrussee/caveman source code, the global uninstall wipes:

• Claude Code hook entries in settings.json and scripts in ~/.claude/hooks/
• The Claude plugin and Gemini extension
• Opencode’s plugin folder, opencode.json entries, skill files, and the fenced block in AGENTS.md
• OpenClaw’s skill folder and the <!-- caveman-begin -->...<!-- caveman-end --> block in SOUL.md

Step-by-Step Removal for a Single Agent

Because the uninstall routine is global, the reliable workflow is to clean everything and then reinstall selectively.

Step 1: Execute the Global Uninstall

First, remove all Caveman artifacts to ensure no stray configuration interferes with the agents you keep.

# Using npx

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

# Or using the local script

node bin/install.js --uninstall

This command deletes the .caveman-active flag and all hook, plugin, and skill files across every supported agent.

Step 2: Reinstall for Specific Agents Only

Use the --only flag documented in INSTALL.md to reinstall Caveman for just the agents you want to keep. Valid agent IDs include claude, opencode, gemini, and openclaw.

# Reinstall only for Claude Code

node bin/install.js --only claude

# Reinstall only for Opencode

node bin/install.js --only opencode

# Reinstall for multiple specific agents (run separately)

node bin/install.js --only gemini
node bin/install.js --only openclaw

This approach uses the same code paths as the original installer, ensuring compatibility with future updates to hook filenames or agent configurations.

Step 3: Verify the Configuration (Optional)

Confirm that the unwanted agent no longer contains Caveman hooks or plugin entries while the desired agents retain them. Check that agent-specific directories like ~/.claude/hooks/ no longer contain Caveman files on the removed agent, but remain present on the kept agents.

Manual Removal Reference

If you prefer not to run a global uninstall, you can manually prune the files that belong to the unwanted agent. The uninstall logic in bin/install.js (lines 1150–1290) targets these specific paths:

Claude Code Artifacts

Remove the hook scripts and strip their entries from settings.json:

# Delete the hook scripts

rm ~/.claude/hooks/caveman-activate.js
rm ~/.claude/hooks/caveman-mode-tracker.js

# Remove entries from settings.json while preserving user-defined hooks

jq 'del(.hooks[] | select(. | includes("caveman-activate.js") or includes("caveman-mode-tracker.js")))' \
   ~/.claude/settings.json > ~/.claude/settings.tmp && mv ~/.claude/settings.tmp ~/.claude/settings.json

Opencode Components

Delete the plugin directory and clean the JSON configuration:

# Remove the plugin directory

rm -rf ~/.config/opencode/plugins/caveman

# Clean opencode.json entries

jq 'del(.plugin[] | select(. == "caveman")) | del(.mcp["caveman-shrink"])' \
   ~/.config/opencode/opencode.json > ~/.config/opencode/opencode.tmp \
   && mv ~/.config/opencode/opencode.tmp ~/.config/opencode/opencode.json

OpenClaw Integration

Remove the skill folder and edit SOUL.md to delete the fenced block marked with <!-- caveman-begin --> and <!-- caveman-end -->.

Summary

• Caveman's installer only supports global uninstallation via --uninstall in bin/install.js (lines 1150–1320)
• To keep Caveman for select agents, run the global uninstall then reinstall with --only <agent-id>
• Manual removal requires deleting specific hook files (caveman-activate.js, caveman-mode-tracker.js), plugin folders (~/.config/opencode/plugins/caveman/), and configuration entries
• The reinstall workflow ensures no stray configuration interferes with remaining installations and stays synchronized with future Caveman updates

Frequently Asked Questions

Can I uninstall Caveman from just one agent without touching others?

No, the installer does not support selective uninstallation. You must run the global uninstall to remove all Caveman artifacts, then reinstall for the specific agents you want to keep using the --only flag.

What files does the global uninstall actually remove?

According to bin/install.js, the global uninstall removes Claude hooks from ~/.claude/hooks/, Opencode plugins from ~/.config/opencode/plugins/caveman/, OpenClaw skills, and associated configuration entries in settings.json, opencode.json, and SOUL.md.

Is there a risk of breaking my agent configuration when reinstalling?

No, because the reinstall uses the same code paths as the original installation in bin/install.js, ensuring compatibility with current agent versions and future changes to hook filenames or directory structures.

How do I verify Caveman was completely removed from a specific agent?

Check that the agent's configuration files no longer reference Caveman hooks or plugins, and verify that agent-specific directories like ~/.claude/hooks/ no longer contain caveman-activate.js or caveman-mode-tracker.js. For Opencode, confirm that ~/.config/opencode/plugins/caveman/ no longer exists.

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