How to Install the Caveman AI Coding Assistant: Complete Setup Guide

Install Caveman by running a one-liner curl command on macOS/Linux or an Invoke-Expression command on Windows, which downloads the shell shim and delegates to the Node-based installer at bin/install.js to automatically configure your detected AI agents.

The Caveman AI coding assistant is an open-source project hosted at JuliusBrussee/caveman that adds a terse, caveman-style interaction mode to popular AI coding agents like Claude Code and Gemini CLI. Installing Caveman requires only a single terminal command that detects your existing tooling and applies the appropriate configuration automatically.

One-Liner Installation Methods

Caveman provides platform-specific installer scripts that handle the entire setup process from the repository root.

macOS, Linux, WSL, and Git Bash

Run the official install script using curl:

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

Windows PowerShell 5.1+

Execute the PowerShell installer:

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

What the Installer Does

When you run the one-liner, the shell script (install.sh or install.ps1) performs several automated steps according to the repository's source code in JuliusBrussee/caveman.

Node.js Verification: The installer first checks that Node.js ≥ 18 is available on your system, as the core installation logic is implemented in bin/install.js.

Agent Detection: The Node installer scans for supported AI coding agents including Claude Code, Gemini CLI, opencode, and OpenClaw. For each detected agent, it executes the appropriate installation command:

• Claude Code: claude plugin install caveman@caveman
• Gemini CLI: gemini extensions install
• opencode: npx skills add

Offline-First Design: After the initial installation, all components run offline. The installer downloads assets from the pinned release tag and verifies them using a SHA-256 manifest as documented in INSTALL.md.

Installation Flags and Options

The installer supports several flags to customize the behavior. Pass these after the bash command or directly to bin/install.js.

Preview Changes: Use --dry-run to see every command the installer would execute without modifying any files:

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

Selective Installation: Install for a specific agent only:

node bin/install.js --only opencode

Or install for all detected agents (default behavior):

node bin/install.js --all

Static Rule Files: Add --with-init to drop static rule files into the current repository, which enables Caveman mode on agents that lack a hook system.

Uninstall: Remove all Caveman components:

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

Verification Steps

Confirm the installation succeeded using these methods from the INSTALL.md documentation.

List Detected Agents: Run the following to see which agents were found and what was installed:

node bin/install.js --list

Test in Claude Code: Open Claude Code and type /caveman. You should receive a terse, caveman-style reply confirming the integration is active.

Check Flag Files: Verify the activation flag exists in your agent's configuration directory:

cat ~/.claude/.caveman-active

Summary

• Caveman installs via a one-liner shell script that delegates to bin/install.js in the JuliusBrussee/caveman repository
• The installer requires Node.js ≥ 18 and automatically detects Claude Code, Gemini CLI, opencode, and other supported agents
• Use --dry-run to preview changes, --only <id> to target specific agents, and --uninstall to remove components
• Verify installation by running node bin/install.js --list or testing the /caveman command in Claude Code

Frequently Asked Questions

Does Caveman work offline after installation?

Yes. According to the INSTALL.md documentation in the JuliusBrussee/caveman repository, all components are fully offline after the initial run. The installer only downloads assets during setup and verifies them with a SHA-256 manifest. No telemetry or network calls occur during normal usage.

Can I install Caveman for only one specific AI agent?

Yes. Use the --only flag followed by the agent identifier. For example, to install only for opencode, run node bin/install.js --only opencode. By default, the installer detects and configures all supported agents found on your system using the logic in bin/install.js.

What if I don't have Node.js installed?

The installer requires Node.js version 18 or higher because the core installation logic resides in bin/install.js. If Node is not available, the shell script will fail with a clear error message. Install Node.js first, then re-run the Caveman installer.

How do I completely remove Caveman from my system?

Run the uninstall command: npx -y github:JuliusBrussee/caveman -- --uninstall. This removes all hook files, rule files, and configuration flags that the installer added to your AI agents and home directory, reversing the changes made by bin/install.js.

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