# How Caveman Is Installed for Different AI Agents: Complete Setup Guide

> Install Caveman for AI agents with our complete setup guide. This unified installer auto-detects your AI coding agents and runs the correct installation routine for seamless integration.

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

---

**Caveman uses a single unified installer ([`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js)) that auto-detects which AI coding agents are present on your machine and executes the appropriate agent-specific installation routine.**

The [JuliusBrussee/caveman](https://github.com/JuliusBrussee/caveman) repository provides a cross-platform installation system designed to integrate with diverse AI coding agents ranging from Claude Code to Cursor. Whether you are using native plugin systems or rule-based configurations, the installer handles the complexity of setting up each environment through one unified entry point.

## The Unified Installation Architecture

At the heart of Caveman's distribution strategy lies **[`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js)**, a Node.js script that serves as the single entry point for all installation methods. The script implements a provider matrix pattern that maps AI agents to their specific installation requirements.

### Provider Matrix Detection

Inside [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js), a **`PROVIDERS`** array defines every supported agent with three key properties:

1. **Detection rules** – Uses patterns like `command:<binary>`, `vscode-ext:<needle>`, or `dir:<path>` to check if an agent exists on the system
2. **Installation commands** – The exact CLI command executed when that agent is detected (e.g., `claude plugin install caveman@caveman`)
3. **Activation mechanism** – Whether the agent auto-activates or requires per-session invocation

The installer walks this matrix automatically, detecting agents present on your `PATH` or in recognizable config directories, then queues the appropriate installation commands.

### Installation Entry Points

You can invoke the installer through multiple methods:

- **macOS/Linux/WSL one-liner:** Forwards all flags to `node bin/install.js`
- **PowerShell one-liner:** `irm ... | iex` pattern for Windows environments
- **Direct execution:** `node bin/install.js` after cloning the repository
- **npx execution:** `npx -y github:JuliusBrussee/caveman` for temporary usage without cloning

## Installation Methods by Agent Category

Caveman categorizes AI agents based on their integration capabilities and detection reliability. The installer handles each category differently according to the logic defined in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js).

### Auto-Activating Agents

These agents support native plugin or extension systems that allow Caveman to activate immediately upon installation:

- **Claude Code** (`claude`): Installs via `claude plugin marketplace add JuliusBrussee/caveman && claude plugin install caveman@caveman`. Copies hook scripts from `src/hooks/` to `~/.claude/hooks/` for activate, mode-tracker, stats, and statusline functionality.
- **Gemini CLI** (`gemini`): Executes `gemini extensions install https://github.com/JuliusBrussee/caveman`
- **opencode** (`opencode`): Registers the plugin via `node bin/install.js --only opencode` and exposes Caveman as a native skill through the [`AGENTS.md`](https://github.com/JuliusBrussee/caveman/blob/main/AGENTS.md) file
- **OpenClaw** (`openclaw`): Installs workspace skills and creates [`SOUL.md`](https://github.com/JuliusBrussee/caveman/blob/main/SOUL.md) via `npx -y github:JuliusBrussee/caveman -- --only openclaw`
- **Hermes Agent** (`hermes`): Adds native skills using `npx -y github:JuliusBrussee/caveman -- --only hermes`

### Per-Session Agents with Optional Persistence

Agents like **Cursor**, **Windsurf**, and **Cline** use `npx skills add JuliusBrussee/caveman -a <agent>` by default, activating only for the current session. To make these permanent, add the **`--with-init`** flag:

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

```

This flag copies the static rule file from [`src/rules/caveman-activate.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md) into agent-specific directories (e.g., `.cursor/rules/caveman.mdc`), creating "always-on" rules that persist across sessions.

### Soft-Probe Agents

**GitHub Copilot** and similar agents require explicit installation because they lack reliable auto-detection signals. Install these using:

```bash
npx -y github:JuliusBrussee/caveman -- --only copilot --with-init

```

These "soft probe" agents only install when requested via `--only <id>` and typically require `--with-init` for repository-wide activation.

## Command-Line Flags and Usage Patterns

The installer in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) supports several flags that control its behavior, parsed through the `parseArgs` function:

### Targeted Installation

Install specific agents only, skipping auto-detection:

```bash

# Install only for opencode

node bin/install.js --only opencode

# Install for multiple specific agents

node bin/install.js --only cursor --only windsurf

```

### Safety and Preview Modes

- **`--dry-run`**: Prints every command that would execute without writing files or running installers
- **`--force`**: Forces re-installation even if Caveman is already present
- **`--no-hooks`**: Disables Claude Code hook installation while keeping the plugin

### Installation Scope Control

- **`--all`**: Bypasses auto-detection and attempts installation for all supported agents
- **`--minimal`**: Installs only essential components, skipping optional features
- **`--with-mcp-shrink`**: Registers the optional MCP proxy for additional functionality

### Listing Providers

View the complete provider matrix with detection status:

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

```

## How the Installer Works Internally

The installation process follows a three-phase pipeline defined in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js):

### 1. Argument Parsing

The `parseArgs` function (around line 55) builds an options object from CLI flags, handling boolean switches like `--dry-run`, `--all`, and `--minimal`, as well as array flags like `--only`.

### 2. Detection Phase

The script iterates over the `PROVIDERS` array, executing each detection rule:
- **`command:<bin>`**: Checks if a binary exists on `PATH`
- **`vscode-ext:<needle>`**: Checks for VS Code extension installations
- **`dir:<path>`**: Validates configuration directories

When a provider matches, the corresponding installation command is queued for execution.

### 3. Execution Phase

For each queued provider, the installer performs one of three actions:
- **CLI invocation**: Runs agent-specific commands (e.g., `claude plugin install`)
- **Skill registration**: Executes `npx skills add JuliusBrussee/caveman -a <agent>`
- **File deployment**: Copies static rule files from [`src/rules/caveman-activate.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md) to agent-specific directories when `--with-init` is specified

## Uninstalling Caveman

To remove all Caveman installations, hooks, plugins, and rule files:

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

```

This invokes [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) with the `--uninstall` flag, which reverses the installation process by removing hook files from `~/.claude/hooks/`, uninstalling plugins, and deleting rule files from repository directories.

## Summary

- Caveman uses a **unified installer** ([`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js)) that auto-detects AI agents via a provider matrix system
- **Auto-detecting agents** (Claude Code, Gemini CLI, opencode) install immediately when their binaries are found on `PATH`
- **Per-session agents** (Cursor, Windsurf, Cline) require `--with-init` to create permanent rule files in directories like `.cursor/rules/caveman.mdc`
- **Soft-probe agents** (GitHub Copilot) install only when explicitly requested with `--only <id>`
- The **`--dry-run`** flag lets you preview changes before executing them
- Uninstallation is handled by the same script using the **`--uninstall`** flag

## Frequently Asked Questions

### How do I install Caveman for just one specific AI agent?

Use the `--only` flag followed by the agent ID. For example, to install only for Cursor, run `node bin/install.js --only cursor` or `npx -y github:JuliusBrussee/caveman -- --only cursor`. You can repeat this flag multiple times to target several specific agents while ignoring others.

### What is the difference between `--all` and the default auto-detect behavior?

The default behavior scans your system and installs Caveman only for agents it detects on your `PATH` or in standard configuration directories. The `--all` flag bypasses this detection and attempts to run the installation routine for every supported agent in the provider matrix, regardless of whether they appear to be installed.

### Why does Caveman require `--with-init` for some agents but not others?

Agents like Claude Code and Gemini CLI support native plugin systems that allow Caveman to hook into their execution automatically. However, agents like Cursor, Windsurf, and Cline operate on a per-session basis by default. The `--with-init` flag tells the installer to drop static rule files (from [`src/rules/caveman-activate.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md)) into the repository, creating permanent "always-on" rules for agents that lack persistent plugin architectures.

### Can I see what the installer will do before it makes changes?

Yes, run any installation command with the `--dry-run` flag. This prints every command that would be executed and every file that would be copied without actually performing the installation. For example: `curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash -s -- --dry-run`.