# Caveman Installation Script for macOS and Linux: Complete Setup Guide

> Install Caveman on macOS Linux with our guide. Use the one-line remote command or clone the repo for automatic AI agent detection and hook configuration.

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

---

**You can install Caveman on macOS or Linux using either a one-line remote command that pipes to bash, or by cloning the repository and running `bash install.sh` locally, both of which delegate to a Node.js installer that detects AI agents and configures hooks automatically.**

The Caveman project provides a unified, single-source-of-truth installer for macOS and Linux systems. According to the JuliusBrussee/caveman source code, the installation process uses a thin Bash shim that forwards to a comprehensive Node.js script capable of detecting multiple AI providers and configuring hooks automatically.

## How the Caveman Installer Works

The installation architecture separates concerns between a minimal Bash wrapper and a robust Node.js implementation.

### The Bash Shim ([`install.sh`](https://github.com/JuliusBrussee/caveman/blob/main/install.sh))

Located at [`install.sh`](https://github.com/JuliusBrussee/caveman/blob/main/install.sh) in the repository root, this script serves as the entry point. It performs three critical tasks before delegating to the Node installer:

1. **Node version check** – Ensures Node.js ≥ 18 is present on the system (lines 22-35)
2. **Repository detection** – Determines if the script is running from a local clone to avoid unnecessary `npx` round-trips (lines 37-44)
3. **Delegation** – For remote installs, invokes `npx -y "github:JuliusBrussee/caveman"` with user-provided arguments (lines 46-55)

### The Node.js Core ([`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js))

The file [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) contains the full installation logic. It pins resources to a fixed release tag (default `v1.9.1`) to guarantee reproducible installs (lines 30-36). The script implements a provider matrix that discovers available AI agents including Claude, Gemini, and OpenClaw, then prepares appropriate installation steps for hooks, skills, and plugins (lines 91-124).

## Installation Methods

You can install Caveman using either remote execution or local cloning.

### Remote One-Line Install

Execute the installer directly from GitHub using curl:

```bash

# Default installation

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

# With explicit flags (installs all components)

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

```

The `bash -s --` syntax allows passing arguments through to the Node installer.

### Local Clone Installation

For development or offline use, clone the repository first:

```bash
git clone https://github.com/JuliusBrussee/caveman.git
cd caveman
bash install.sh --all

```

Running locally skips the `npx` delegation and executes the Node script directly from [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js).

## What the Installer Configures

The Node installer performs several automated configuration tasks beyond simple file copying.

### Node Version Validation

Before proceeding, the Bash shim validates that Node.js version 18 or higher is installed. This check prevents runtime errors from incompatible Node versions during the provider detection phase.

### Agent Detection and Provider Matrix

The installer scans the host system to identify which AI agents are available. As implemented in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) (lines 91-124), it prepares installation steps for:

- **Claude** – Configures hooks and settings
- **Gemini** – Sets up relevant integrations
- **OpenClaw** – Installs skills and SOUL.md bootstrap (via [`bin/lib/openclaw.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/lib/openclaw.js))

### Hook Installation and Integrity Verification

For Claude installations, the script copies hook scripts from `src/hooks/` into the user's Claude configuration directory. It validates file integrity using SHA-256 hashes from `src/hooks/checksums.sha256` before merging hook definitions into `~/.claude/settings.json` (lines 12-28 and 84-110). The helper functions in [`bin/lib/settings.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/lib/settings.js) handle reading and writing the settings file safely.

### Optional MCP Shrink Proxy

When specified, the installer registers a local proxy called `caveman-shrink` that forwards commands to a user-specified upstream tool (lines 430-470). This feature allows for compressed or filtered MCP (Model Context Protocol) communications.

## Summary

- **Two entry points**: Use `curl | bash` for quick remote installs or `bash install.sh` from a local clone.
- **Node.js requirement**: The installer requires Node.js ≥ 18 and pins to release tag `v1.9.1` for reproducibility.
- **Multi-agent support**: Automatically detects Claude, Gemini, OpenClaw, and other providers.
- **Secure hook installation**: Validates SHA-256 checksums before modifying `~/.claude/settings.json`.
- **Optional components**: Supports `--all`, `--minimal`, and `--list` flags to control installation scope.

## Frequently Asked Questions

### What are the system requirements for running the Caveman installer?

The installer requires macOS or Linux with Node.js version 18 or higher installed. The Bash shim checks for this requirement in [`install.sh`](https://github.com/JuliusBrussee/caveman/blob/main/install.sh) (lines 22-35) before delegating to the Node.js implementation.

### How do I install specific components instead of everything?

Pass the `--minimal` flag for a lightweight setup that installs only essential hooks, or use `--list` to see which agents are detected before installing. The `--all` flag installs all supported agents, hooks, and the optional `caveman-shrink` proxy.

### Is it safe to pipe curl directly to bash?

The Caveman installer fetches from a trusted GitHub URL and delegates to `npx` with the `-y` flag to execute the package. For enhanced security, you can clone the repository and inspect [`install.sh`](https://github.com/JuliusBrussee/caveman/blob/main/install.sh) and [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) before running `bash install.sh` locally.

### How does the installer verify the integrity of downloaded files?

The Node installer validates hook scripts against SHA-256 hashes stored in `src/hooks/checksums.sha256` before copying them to the Claude configuration directory. This ensures the downloaded files match the pinned release tag.