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

> Easily install Caveman for Claude Code, Cursor, and AI agents with a single command. Auto-detects and configures plugins for seamless integration.

- Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman)
- Tags: getting-started
- Published: 2026-07-06

---

**Caveman installs via a universal one-liner that auto-detects your AI coding agents and wires the appropriate plugin, extension, or rule file to each supported environment.**

The **Caveman** project (`JuliusBrussee/caveman`) provides a cross-platform installer that eliminates manual configuration for supported AI agents. Whether you use Claude Code, Cursor, Gemini CLI, or other coding assistants, the installer handles agent detection, native command execution, and file placement through a single entry point.

## Three-Layer Installation Architecture

The installation system works through three coordinated layers defined in the source code:

1. **Universal one-liner** – Shell scripts ([`install.sh`](https://github.com/JuliusBrussee/caveman/blob/main/install.sh) or `install.ps1`) download and execute the native installer
2. **[`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js)** – The core installer that reads a `PROVIDERS` matrix, detects agents on your `PATH`, and executes per-agent install commands
3. **Agent-specific assets** – Plugin files for Claude Code, extension directories for Gemini CLI, or static rule files (`.cursor/rules/caveman.mdc`) for agents like Cursor, Windsurf, and Cline

The installer is **idempotent**, meaning you can safely rerun it without duplicating components. It automatically skips already-installed agents and can be run with flags like `--dry-run` to preview actions or `--only <id>` to target specific agents.

## Quick Start: Install All Detected Agents

Run the universal installer to automatically detect and configure every supported agent on your system.

**macOS, Linux, WSL, or Git Bash:**

```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

```

This script executes the following actions according to the source in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js):

- Scans your `PATH` for installed agents (Claude Code, Cursor, Gemini CLI, etc.)
- Runs native install commands (e.g., `claude plugin install`, `gemini extensions install`)
- Writes Claude Code 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))
- Places the compiled skill (`dist/caveman.skill`) into appropriate plugin directories
- Optionally generates permanent rule files if you pass `--with-init`

## Installing Specific Agents Only

To install Caveman for just one agent instead of all detected environments, use the `--only` flag.

**Claude Code only:**

```bash
node bin/install.js --only claude

```

**Cursor only (via the Vercel skills registry):**

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

```

**Via the one-liner with arguments:**

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

```

The `--only` flag filters the `PROVIDERS` array in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) to execute installation logic for a single agent ID, skipping the auto-detection phase entirely.

## Installation Options and Flags

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

- **`--dry-run`** – Preview all commands without executing them
- **`--with-init`** – Generate permanent rule files (e.g., `.cursor/rules/caveman.mdc`) in the current repository for repo-local activation
- **`--only <id>`** – Install for a specific agent only (e.g., `claude`, `cursor`, `gemini`)
- **`--all`** – Force installation for all supported agents regardless of detection (used when running the installer directly)

**Repo-local installation without global hooks:**

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

```

This command drops the activation rule from [`src/rules/caveman-activate.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md) into `.cursor/rules/caveman.mdc` without modifying global configuration directories.

## Agent-Specific Installation Paths

Each agent receives Caveman through a different mechanism based on its architecture:

**Claude Code**
- **Location:** `$CLAUDE_CONFIG_DIR/plugins/` (JSON plugin format)
- **Auto-activate:** Yes – writes `.caveman-active` flag file and hooks
- **Command:** `claude plugin install caveman@caveman`

**Cursor, Windsurf, Cline, Copilot**
- **Location:** Repo-local rule directories (`.cursor/rules/`, `.windsurf/rules/`, `.clinerules/`, [`.github/copilot-instructions.md`](https://github.com/JuliusBrussee/caveman/blob/main/.github/copilot-instructions.md))
- **Auto-activate:** No – requires typing `/caveman` each session unless you use `--with-init`
- **Source:** Static rule file from [`src/rules/caveman-activate.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md)

**Gemini CLI**
- **Location:** `~/.gemini/extensions/`
- **Auto-activate:** Yes

**opencode**
- **Location:** `~/.config/opencode/plugins/caveman/`
- **Auto-activate:** Yes – includes plugin and [`AGENTS.md`](https://github.com/JuliusBrussee/caveman/blob/main/AGENTS.md) block

**OpenClaw**
- **Location:** `~/.openclaw/workspace/` (skill folder with [`SOUL.md`](https://github.com/JuliusBrussee/caveman/blob/main/SOUL.md) block)
- **Auto-activate:** Yes

## Verification Steps

Confirm your installation succeeded by checking these specific artifacts:

**List installed agents:**

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

```

**Verify Claude Code activation:**

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

```

This should output the active level (e.g., `full`).

**Check statusline badge:**
Open Claude Code – you should see `[CAVEMAN]` in the bottom status bar if the hook files ([`caveman-statusline.sh`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-statusline.sh) or `caveman-statusline.ps1`) were correctly written to the config directory.

## Uninstalling Caveman

Remove all Caveman components using the built-in uninstall routine:

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

```

This command removes:

- Claude Code hook entries and the `.caveman-active` flag file
- All plugins/extensions installed by the original installer
- The opencode plugin directory and its [`AGENTS.md`](https://github.com/JuliusBrussee/caveman/blob/main/AGENTS.md) block
- The OpenClaw skill folder and [`SOUL.md`](https://github.com/JuliusBrussee/caveman/blob/main/SOUL.md) marker
- The global `caveman` skill folder

Note that skills installed via `npx skills add` are managed by the separate `skills` CLI and must be removed using that tool's native commands.

## Summary

- **Caveman** installs through a universal shell script that downloads [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) and executes the `PROVIDERS` matrix
- Use **`curl | bash`** for macOS/Linux or **`irm | iex`** for Windows to auto-detect all agents
- Add **`--only <agent>`** to target specific agents like Claude Code or Cursor
- Include **`--with-init`** to generate permanent rule files in repo-local directories for agents that don't support auto-activation
- The installer manages different asset types: **plugins** for Claude Code, **extensions** for Gemini CLI, and **static rules** for Cursor/Windsurf
- Verify installation by checking the `.caveman-active` file or running `node bin/install.js --list`

## Frequently Asked Questions

### How do I install Caveman for Cursor specifically?

For Cursor, you have two options. Run the universal installer with the `--only` flag: `curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash -s -- --only cursor`. Alternatively, use the Vercel skills registry: `npx skills add JuliusBrussee/caveman -a cursor`. Unlike Claude Code, Cursor requires either typing `/caveman` each session or using the `--with-init` flag to create a permanent rule file at `.cursor/rules/caveman.mdc`.

### Is the Caveman installer safe to run multiple times?

Yes, the installer is **idempotent**. According to the logic in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js), rerunning the installation safely skips components that are already present. You can use this behavior to update your installation or add new agents without worrying about duplicate files or configurations.

### What is the difference between `--with-init` and standard installation?

Standard installation configures global agent settings (like Claude Code plugins or Gemini extensions). The **`--with-init`** flag specifically generates repo-local rule files from [`src/rules/caveman-activate.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md) into directories like `.cursor/rules/` or `.windsurf/rules/`. This is necessary for agents like Cursor that don't support automatic activation through hooks, allowing you to commit the activation rule to your repository.

### Where does Caveman store its configuration files?

Claude Code plugins live in `$CLAUDE_CONFIG_DIR/plugins/`, while Gemini CLI extensions reside in `~/.gemini/extensions/`. The opencode plugin is stored at `~/.config/opencode/plugins/caveman/`. For agents requiring static rules (Cursor, Windsurf, Cline), files are placed in repo-local directories (e.g., `.cursor/rules/caveman.mdc`) unless you manually copy them to global locations.