# How to Install Caveman for Claude Code, Cursor, and Other AI Agents

> Easily install Caveman for Claude Code, Cursor, and AI agents with a universal script that auto-detects and configures your tools for seamless integration.

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

---

**Caveman installs via a single universal script that auto-detects your AI coding agents and wires the appropriate plugins, extensions, or rule files to each environment.**

`JuliusBrussee/caveman` is an open-source compatibility layer that adds a "caveman mode" skill to Claude Code, Cursor, Gemini CLI, and other AI agents. The installation is idempotent, meaning you can safely rerun it multiple times without duplicate configurations.

## Universal One-Liner Installation

The fastest way to install Caveman across all detected agents uses a thin shell wrapper that downloads and executes the native installer.

**macOS and Linux:**

```bash
curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash

```

**Windows PowerShell 5.1+:**

```powershell
irm https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.ps1 | iex

```

These scripts download [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) and execute it with default settings. The installer reads a hard-coded `PROVIDERS` matrix to detect which AI agent binaries exist on your `PATH`, then runs each agent's native install command automatically.

## Agent-Specific Installation Methods

While the universal installer handles most cases, you can target specific agents manually when you need granular control.

### Claude Code

For Claude Code, the installer adds a JSON plugin and activation hooks to your configuration directory:

```bash
claude plugin marketplace add JuliusBrussee/caveman && claude plugin install caveman@caveman

```

The installer also writes 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)) and a statusline badge script to `$CLAUDE_CONFIG_DIR/plugins/`. It creates a `.caveman-active` flag file to enable automatic activation on every session.

### Cursor

Cursor receives the Caveman skill via the Vercel skills registry:

```bash
npx skills add JuliusBrussee/caveman -a cursor

```

Alternatively, you can drop the static rule file directly into your repository:

```bash
curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/src/rules/caveman-activate.md \
  > .cursor/rules/caveman.mdc

```

Static rules in [`src/rules/caveman-activate.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md) do not auto-activate; you must invoke `/caveman` each session unless you use the `--with-init` flag.

### Gemini CLI, OpenCode, and OpenClaw

The installer handles these agents automatically when detected:

- **Gemini CLI**: Installs to `~/.gemini/extensions/` and activates immediately.
- **OpenCode**: Places the plugin in `~/.config/opencode/plugins/caveman/` and adds an [`AGENTS.md`](https://github.com/JuliusBrussee/caveman/blob/main/AGENTS.md) block.
- **OpenClaw**: Creates a skill folder in `~/.openclaw/workspace/` with a [`SOUL.md`](https://github.com/JuliusBrussee/caveman/blob/main/SOUL.md) marker.

## Advanced Installation Options

The native installer ([`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js)) supports several flags for customized deployments.

### Preview Installation Commands

Use `--dry-run` to see exactly what commands would execute without modifying your system:

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

```

### Install for a Single Agent

To bypass auto-detection and target only one agent:

```bash

# Via the installer directly

node bin/install.js --only claude

# Via the one-liner with arguments

curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash -s -- --only cursor

```

### Repo-Local Installation Without Global Hooks

For Cursor, Windsurf, Cline, or Copilot (which use static rule files rather than plugins), you can install without global configuration:

```bash
node bin/install.js --with-init --only cursor

```

This drops `.cursor/rules/caveman.mdc`, `.windsurf/rules/`, `.clinerules/`, or [`.github/copilot-instructions.md`](https://github.com/JuliusBrussee/caveman/blob/main/.github/copilot-instructions.md) into your current repository. The [`src/tools/caveman-init.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/tools/caveman-init.js) helper generates these per-repo init files when `--with-init` is supplied.

## Verification and Uninstallation

Verify your installation by listing detected agents and their status:

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

```

For Claude Code specifically, check the activation flag:

```bash
cat "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/.caveman-active"

```

You should see the active level (e.g., `full`) if the hooks are properly configured.

To completely remove Caveman:

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

```

This removes Claude Code hooks and the `.caveman-active` file, uninstalls all plugins/extensions managed by the installer, deletes the opencode plugin directory and [`AGENTS.md`](https://github.com/JuliusBrussee/caveman/blob/main/AGENTS.md) block, removes the OpenClaw skill folder and [`SOUL.md`](https://github.com/JuliusBrussee/caveman/blob/main/SOUL.md) marker, and cleans up the global `caveman` skill folder. Note that skills installed via `npx skills add` remain managed by the `skills` CLI and require separate removal.

## Summary

- **Universal install**: Use the `curl` or `irm` one-liner to auto-detect and configure all agents.
- **Idempotent design**: Re-run the installer safely; it skips already-installed components.
- **Direct installer**: [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) contains the core logic and accepts `--dry-run`, `--only <id>`, and `--with-init` flags.
- **Claude Code**: Receives JSON plugins and activation hooks in `$CLAUDE_CONFIG_DIR/plugins/`.
- **Cursor**: Uses `npx skills add` or static rule files in `.cursor/rules/` depending on your preference.
- **Clean removal**: The `--uninstall` flag removes all global configurations while preserving other skill registries.

## Frequently Asked Questions

### Does Caveman install globally or per-project?

Caveman installs **globally** for CLI agents like Claude Code and Gemini by placing plugins in your home directory configuration folders. For Cursor, Windsurf, and similar agents, it can install **globally** (via `npx skills add`) or **per-project** (via `--with-init` which drops rule files into `.cursor/rules/` or equivalent directories). The `--with-init` flag is specifically designed for repo-local rule file generation without touching global settings.

### Why do I need to run `/caveman` in Cursor but not Claude Code?

**Claude Code** supports hooks and plugins that can auto-activate on session start; the installer writes [`caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-activate.js) and a flag file (`.caveman-active`) to enable this. **Cursor** and similar editors use static Markdown rule files ([`src/rules/caveman-activate.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md)) that cannot execute code or auto-trigger; they require manual invocation. Add `--with-init` during installation to generate permanent rule files that persist across sessions without manual activation.

### Can I install Caveman on a machine without Node.js?

The **universal one-liners** require either `bash` (macOS/Linux) or PowerShell (Windows) to download the installer, but the native installer ([`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js)) itself requires Node.js to execute the `PROVIDERS` matrix logic and dispatch commands. If you cannot install Node.js, you must manually copy the static rule files from [`src/rules/caveman-activate.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md) to your agent's configuration directory.

### How do I update Caveman to the latest version?

Simply **re-run the universal installer**. Because the installation is idempotent, it will detect your existing configuration and update the skill files in `dist/caveman.skill` and plugin directories without duplicating entries or breaking your existing hooks. For agents installed via `npx skills add`, use the `skills` CLI update commands instead.