# How to Install and Set Up the Caveman Project for AI Coding Agents

> Install and set up the Caveman project with a single command. It auto-detects and configures agents like Claude Code, Gemini, and Cursor for AI coding.

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

---

**Run a single command to auto-detect and configure Caveman for Claude Code, Gemini, Cursor, and other supported agents on your system.**

Caveman is a lightweight skill that plugs into AI coding agents to rewrite their responses in terse "caveman-speak." The JuliusBrussee/caveman repository provides a cross-platform installer that handles detection, plugin installation, and hook configuration automatically. This guide covers the complete installation process using the official Node.js-based installer.

## Prerequisites

Before running the installer, ensure your environment meets the following requirements:

- **Node.js >= 18** – The `checkNodeVersion()` function in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) enforces this minimum version.
- **AI agents on PATH** – The target agents (e.g., `claude`, `gemini`, `cursor`, `opencode`) must be accessible from your shell.
- **Windows PowerShell execution policy** – On Windows, allow script execution with `Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass` before running the PowerShell one-liner.

## One-Command Installation

The fastest way to install Caveman uses a single command that downloads and executes the appropriate installer for your platform.

### macOS, Linux, and WSL

Run the bash one-liner to auto-detect all supported agents and configure them:

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

```

This command downloads [`install.sh`](https://github.com/JuliusBrussee/caveman/blob/main/install.sh), which delegates to [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) to detect agents, run native install commands (e.g., `claude plugin install`, `gemini extensions install`), and copy hook files.

### Windows PowerShell

For Windows environments, use the PowerShell one-liner:

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

```

The `install.ps1` script performs the same detection logic as the Unix version but installs Windows-specific hooks like `caveman-statusline.ps1`.

## Manual Installation for Auditing

If you prefer to review the code before execution, clone the repository and run the installer locally:

```bash
git clone https://github.com/JuliusBrussee/caveman.git
cd caveman
node bin/install.js --list    # Preview detected agents

node bin/install.js --all     # Install for all detected agents

```

Manual installation allows you to use flags like `--dry-run` to preview changes or `--only <agent>` to target specific agents.

## How the Installer Works

The core logic in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) follows a multi-step architecture to ensure idempotent configuration across different agent ecosystems.

### Agent Detection Matrix

The installer defines a `PROVIDERS` array that maps each agent to a detection rule. According to the source code, it checks for:
- **Command existence** – e.g., `command:claude` verifies the `claude` binary is on PATH.
- **VS Code extensions** – e.g., `vscode-ext:cursor` detects Cursor via VS Code extension metadata.
- **Configuration directories** – e.g., `dir:$HOME/.openclaw/workspace` locates OpenClaw installations.

The installer automatically selects all detected agents unless you specify `--only <id>`.

### Native Plugin Installation

Depending on the detected agent, the installer invokes the appropriate native command:
- **Claude Code** – `claude plugin install`
- **Gemini CLI** – `gemini extensions install`
- **Cursor, OpenClaw, Opencode** – `npx skills add JuliusBrussee/caveman -a <agent>`

### Hook Wiring for Claude Code

For Claude Code specifically, the installer copies JavaScript 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)) into `$CLAUDE_CONFIG_DIR/hooks/` and merges them into [`settings.json`](https://github.com/JuliusBrussee/caveman/blob/main/settings.json). This ensures the "SessionStart" and "UserPromptSubmit" events trigger caveman mode. The installer backs up existing configurations (e.g., `settings.json.bak`) before overwriting.

### Persistent Rule Files

Agents that lack a dynamic hook system (Cursor, Windsurf, Cline, Copilot) receive a static rule file. When using `--with-init`, the installer copies [`src/rules/caveman-activate.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md) into:
- `.cursor/rules/`
- `.windsurf/rules/`
- `.clinerules/`
- [`.github/copilot-instructions.md`](https://github.com/JuliusBrussee/caveman/blob/main/.github/copilot-instructions.md)

These files enable caveman mode persistently without global configuration changes.

## Advanced Installation Options

### Preview Changes with Dry Run

To see what the installer would do without making changes:

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

```

This outputs the detection results and planned file operations without writing to disk.

### Install for Specific Agents Only

Target a single agent to avoid modifying others:

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

```

Or manually:

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

```

### MCP-Shrink Proxy

Enable the optional MCP proxy for token compression in downstream tools:

```bash
curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash -s -- --with-mcp-shrink="npx @modelcontextprotocol/server-filesystem /tmp"

```

This registers `caveman-shrink` in the Opencode MCP configuration.

## Verify Your Installation

Confirm the setup succeeded by checking the following:

1. **List detected agents** – Run `node bin/install.js --list` and verify checkmarks appear next to your installed agents.
2. **Test the command** – Open Claude Code (or your configured agent) and type `/caveman`. You should receive a terse response like "Got it. Caveman mode on."
3. **Check Claude Code flag file** – Verify the activation marker exists:
   ```bash
   cat "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/.caveman-active"
   ```

## Uninstalling Caveman

Remove all Caveman configurations and plugins with:

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

```

This command cleans up hook files, rule files, and agent-specific plugin registrations.

## Summary

- **Single-command install** – Use `curl ... | bash` on Unix or `irm ... | iex` on Windows to auto-detect and configure all agents.
- **Manual control** – Clone the repo and run `node bin/install.js` with `--dry-run`, `--only`, or `--all` for granular control.
- **Hook vs. Rule files** – Claude Code uses dynamic hooks in `$CLAUDE_CONFIG_DIR/hooks/`, while Cursor and others use static rule files in repository-specific directories.
- **Safe and idempotent** – The installer backs up existing configs and only overwrites with `--force`.
- **Node.js 18+ required** – The `checkNodeVersion()` function enforces this minimum before any installation steps.

## Frequently Asked Questions

### What is the minimum Node.js version required to install Caveman?

Caveman requires Node.js version 18 or higher. The `checkNodeVersion()` function in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) validates your environment before proceeding with installation and will exit with an error if your Node version is insufficient.

### Can I install Caveman for only one specific AI agent?

Yes. Use the `--only <agent>` flag with the installer to target a single agent. For example, `bash -s -- --only cursor` installs only for Cursor, skipping detection and configuration for other agents like Claude Code or Gemini.

### Where does Caveman store its configuration files?

For Claude Code, Caveman writes hook files to `$CLAUDE_CONFIG_DIR/hooks/` (typically `~/.claude/hooks/`). For agents like Cursor, Windsurf, and Cline, it drops rule files into repository-specific directories such as `.cursor/rules/` or `.windsurf/rules/`. The installer always backs up existing files before modifying them.

### How do I remove Caveman from my system?

Run the uninstall command `npx -y github:JuliusBrussee/caveman -- --uninstall` to remove all Caveman configurations, hook files, and plugin registrations from your detected agents. This command reverses the installation process while preserving your backed-up configuration files.