# How to Uninstall Caveman from an AI Agent: Complete Removal Guide > Uninstall Caveman from your AI agent easily. Follow our complete removal guide using npx or node to reverse all installer changes on Claude Code, Gemini CLI, and more. - Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman) - Tags: how-to-guide - Published: 2026-07-08 --- **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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/opencode.json) and rule-file blocks added to [`AGENTS.md`](https://github.com/JuliusBrussee/caveman/blob/main/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: ```bash 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: ```bash 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`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js), the uninstaller performs these six actions in sequence: 1. Remove Caveman hook entries from [`settings.json`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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: ```bash # 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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/INSTALL.md): Documents the `--uninstall` flag and the full removal procedure - [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js): Contains the core `PROVIDERS` matrix and file system operations that perform the uninstall - [`src/hooks/README.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/README.md): Explains the hook files that are added and removed from the Claude configuration - [`SECURITY.md`](https://github.com/JuliusBrussee/caveman/blob/main/SECURITY.md): Confirms that the uninstall command removes all traces of the application ## Summary - The uninstall command is built into [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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.