How to Uninstall Caveman from an AI Agent: Complete Removal Guide

Run npx -y github:JuliusBrussee/caveman -- --uninstall or node bin/install.js --uninstall to completely remove Caveman from Claude Code, Gemini CLI, Opencode, and OpenClaw, reversing every configuration change the installer originally made.

The Caveman toolkit provides a built-in uninstall routine that lives in the same bin/install.js script used for installation. When you need to uninstall Caveman from an AI agent, the --uninstall flag triggers an idempotent cleanup process that walks the same PROVIDERS matrix used during detection and removes every component it previously added.

What the Uninstall Command Removes

The uninstall logic in bin/install.js systematically reverses each modification made during installation:

• Claude Code configuration: Substring-matched caveman entries are stripped from $CLAUDE_CONFIG_DIR/settings.json
• Hook files: All caveman-*.js, caveman-*.sh, and caveman-*.ps1 files are deleted from $CLAUDE_CONFIG_DIR/hooks/
• Claude Code plugin and Gemini CLI extension: Both are uninstalled if they were originally installed by the script
• Opencode native plugin: The entire ~/.config/opencode/plugins/caveman/ directory is removed, along with related entries in opencode.json and rule-file blocks added to AGENTS.md
• OpenClaw workspace skill: The skill folder and the fenced marker block appended to ~/.openclaw/workspace/SOUL.md are stripped
• Activation flag: The .caveman-active file is deleted from the system

How to Uninstall Caveman from an AI Agent

You have two methods to trigger the uninstall process, depending on whether you have a local clone of the repository.

Global Uninstall (No Repository Clone Required)

This command works from any directory and does not require you to keep a local copy of the Caveman repository:

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

Local Uninstall (From Repository Clone)

If you have the repository cloned locally and want to see the exact steps being executed:

node bin/install.js --uninstall

Both commands perform identical cleanup operations and are completely idempotent—running the command a second time will simply report that nothing remains to be removed.

Step-by-Step Uninstall Process

According to the source code in bin/install.js, the uninstaller performs these six actions in sequence:

1. Remove Caveman hook entries from settings.json using substring matching
2. Delete all Caveman hook scripts in the Claude configuration directory hooks folder
3. Uninstall the Claude plugin and Gemini extension (if present)
4. Delete the Opencode plugin folder and related configuration entries
5. Remove the OpenClaw workspace skill and its SOUL.md marker block
6. Delete the .caveman-active flag file

Manual Cleanup for Rule Files

If you originally installed Caveman using the --with-init flag to add rule files to specific repositories, those files are not removed automatically during uninstallation. You must delete these manually:

# Example: remove the rule file added to a Cursor repository

rm .cursor/rules/caveman.mdc

Check your project directories for any .cursor/rules/caveman.mdc or similar files that may have been copied from src/rules/caveman-activate.md during the initial setup.

Key Source Files

Understanding these files helps verify that the uninstall process has completed successfully:

• INSTALL.md: Documents the --uninstall flag and the full removal procedure
• bin/install.js: Contains the core PROVIDERS matrix and file system operations that perform the uninstall
• src/hooks/README.md: Explains the hook files that are added and removed from the Claude configuration
• SECURITY.md: Confirms that the uninstall command removes all traces of the application

Summary

• The uninstall command is built into bin/install.js and triggered by the --uninstall flag
• Use npx -y github:JuliusBrussee/caveman -- --uninstall for global removal without a local clone
• The process removes all hooks, plugins, extensions, and configuration entries from Claude Code, Gemini CLI, Opencode, and OpenClaw
• Rule files installed with --with-init require manual deletion from your project directories
• The uninstaller is idempotent and safe to run multiple times

Frequently Asked Questions

Does uninstalling Caveman delete my AI agent's existing configuration?

No, the uninstaller only removes entries that match the substring caveman in your configuration files. According to the implementation in bin/install.js, it specifically targets Caveman-related hooks in $CLAUDE_CONFIG_DIR/settings.json and preserves all other settings and customizations you may have added.

What happens if I run the uninstall command twice?

The uninstall process is deliberately idempotent. If you run node bin/install.js --uninstall after Caveman has already been removed, the script will detect that no components remain and report that nothing needs to be removed, without throwing errors or modifying unrelated files.

Why are my rule files still present after uninstalling Caveman?

Files installed using the --with-init flag, such as those copied from src/rules/caveman-activate.md into your project directories, are intentionally excluded from automatic removal. These reside in your working repositories (e.g., .cursor/rules/caveman.mdc) and must be deleted manually to avoid affecting your project's version control history.

Do I need to keep the repository clone to uninstall Caveman?

No, you do not need to keep a local clone. The npx -y github:JuliusBrussee/caveman -- --uninstall command downloads and executes the uninstaller temporarily without leaving files on your system, making it ideal for cleanup even if you have already deleted the original repository.

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