Caveman Installation Commands for macOS, Linux, WSL, and Windows

Caveman provides one-line installation commands for every major OS: a curl pipe for macOS/Linux/WSL and an irm/iex pipe for Windows PowerShell, both delegating to a unified Node.js installer that auto-detects AI coding agents and installs the appropriate plugins.

The JuliusBrussee/caveman repository distributes a cross-platform AI coding assistant configuration tool. Whether you are on macOS, Linux, WSL, or Windows, you can install Caveman using a single shell command that downloads a thin shim script, checks for Node.js ≥ 18, and executes the unified installer at bin/install.js.

macOS, Linux, and WSL Installation

For Unix-like systems, Caveman ships install.sh, a Bash shim located at the repository root that detects your Node.js version and forwards all arguments to the core installer.

Run the one-liner to download and execute the script:

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

If you have already cloned the repository, you can invoke the shim directly:

bash install.sh

Running from a Local Clone

When executed inside a cloned repository, install.sh invokes the local bin/install.js directly via Node. Without a local copy, the shim uses npx -y "github:JuliusBrussee/caveman" to pull the package remotely and execute the installation logic.

Windows Installation (PowerShell)

Windows users utilize install.ps1, a PowerShell shim that performs the same Node version verification before delegating to the unified installer.

Execute the installation using the Invoke-RestMethod (irm) and Invoke-Expression (iex) pattern:

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

This requires PowerShell 5.1 or newer. The script checks that Node.js is present, then calls npx to execute the installation logic from bin/install.js.

Installation Flags and Options

Both shim scripts forward all flags to bin/install.js, the platform-agnostic installer that handles agent detection and plugin installation.

Common flags include:

• --dry-run – Preview actions without making changes
• --only <agent> – Install only for a specific agent (e.g., opencode, claude)
• --all – Force installation for all detected agents
• --force – Re-install even if already present
• --with-init – Add per-repository rule files (creates .cursor/rules/, .windsurf/rules/, etc.)

Preview installation actions on macOS or Linux:

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

Install only for the opencode agent without cloning:

npx -y github:JuliusBrussee/caveman -- --only opencode

Force re-installation for all detected agents:

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

How the Installer Works

The bin/install.js script serves as the single source of truth for Caveman installations. According to the JuliusBrussee/caveman source code, it performs three main operations:

1. Agent Detection – Scans for installed AI coding tools including Claude Code, Gemini CLI, opencode, and OpenClaw
2. Plugin Installation – Installs the appropriate Caveman plugin or extension for each detected agent
3. Rule File Setup – Optionally adds per-repo configuration files when --with-init is passed

The shim scripts (install.sh and install.ps1) act as thin wrappers that ensure Node.js ≥ 18 is available before executing the installer.

Summary

• macOS/Linux/WSL: Use curl -fsSL ...install.sh | bash to run the Bash shim
• Windows: Use irm ...install.ps1 | iex to run the PowerShell shim
• Requirements: Node.js version 18 or higher must be installed
• Flags: Pass --dry-run, --only <agent>, --all, or --force via the shim to control installation behavior
• Source: All installation logic resides in bin/install.js, referenced by both platform-specific shims

Frequently Asked Questions

Do I need to install Node.js before running Caveman installation commands?

Yes. Both install.sh and install.ps1 check that Node.js version 18 or higher is present. If Node is missing, the scripts print a helpful hint and exit. You must install Node.js manually before retrying the installation command.

Can I install Caveman for only one specific AI agent?

Yes. Use the --only <agent> flag followed by the agent name. For example, to install only for opencode, run npx -y github:JuliusBrussee/caveman -- --only opencode or pass the flag through the shim: bash install.sh --only opencode.

How do I preview what Caveman will install before making changes?

Add the --dry-run flag to your installation command. This executes the detection logic in bin/install.js but prevents any actual file system modifications, showing you which agents were found and what would be installed.

Is there a difference between running the install script and cloning the repository?

Yes. When you run the one-liner (curl or irm), the shim uses npx to download and execute the installer remotely. When you clone the repository and run bash install.sh or node bin/install.js, the shim invokes the local copy of bin/install.js directly without fetching from GitHub.

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