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

> Uninstall Caveman from a specific agent easily. Learn how to remove traces and reinstall only the agents you need with the --only flag.

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

---

**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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/settings.json) and scripts in `~/.claude/hooks/`
- The Claude plugin and Gemini extension
- Opencode’s plugin folder, [`opencode.json`](https://github.com/JuliusBrussee/caveman/blob/main/opencode.json) entries, skill files, and the fenced block in [`AGENTS.md`](https://github.com/JuliusBrussee/caveman/blob/main/AGENTS.md)
- OpenClaw’s skill folder and the `<!-- caveman-begin -->...<!-- caveman-end -->` block in [`SOUL.md`](https://github.com/JuliusBrussee/caveman/blob/main/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.

```bash

# 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`](https://github.com/JuliusBrussee/caveman/blob/main/INSTALL.md) to reinstall Caveman for just the agents you want to keep. Valid agent IDs include `claude`, `opencode`, `gemini`, and `openclaw`.

```bash

# 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`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) (lines 1150–1290) targets these specific paths:

### Claude Code Artifacts

Remove the hook scripts and strip their entries from [`settings.json`](https://github.com/JuliusBrussee/caveman/blob/main/settings.json):

```bash

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

```bash

# 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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-activate.js), [`caveman-mode-tracker.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/settings.json), [`opencode.json`](https://github.com/JuliusBrussee/caveman/blob/main/opencode.json), and [`SOUL.md`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-activate.js) or [`caveman-mode-tracker.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-mode-tracker.js). For Opencode, confirm that `~/.config/opencode/plugins/caveman/` no longer exists.