Caveman Installation Script for macOS and Linux: Complete Setup Guide

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)

Located at 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)

The file 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:

# 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:

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.

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 (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)

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 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 (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 and 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}