How Caveman Is Installed for Different AI Agents: Complete Setup Guide

Caveman uses a single unified installer (bin/install.js) that auto-detects which AI coding agents are present on your machine and executes the appropriate agent-specific installation routine.

The JuliusBrussee/caveman repository provides a cross-platform installation system designed to integrate with diverse AI coding agents ranging from Claude Code to Cursor. Whether you are using native plugin systems or rule-based configurations, the installer handles the complexity of setting up each environment through one unified entry point.

The Unified Installation Architecture

At the heart of Caveman's distribution strategy lies bin/install.js, a Node.js script that serves as the single entry point for all installation methods. The script implements a provider matrix pattern that maps AI agents to their specific installation requirements.

Provider Matrix Detection

Inside bin/install.js, a PROVIDERS array defines every supported agent with three key properties:

1. Detection rules – Uses patterns like command:<binary>, vscode-ext:<needle>, or dir:<path> to check if an agent exists on the system
2. Installation commands – The exact CLI command executed when that agent is detected (e.g., claude plugin install caveman@caveman)
3. Activation mechanism – Whether the agent auto-activates or requires per-session invocation

The installer walks this matrix automatically, detecting agents present on your PATH or in recognizable config directories, then queues the appropriate installation commands.

Installation Entry Points

You can invoke the installer through multiple methods:

• macOS/Linux/WSL one-liner: Forwards all flags to node bin/install.js
• PowerShell one-liner: irm ... | iex pattern for Windows environments
• Direct execution: node bin/install.js after cloning the repository
• npx execution: npx -y github:JuliusBrussee/caveman for temporary usage without cloning

Installation Methods by Agent Category

Caveman categorizes AI agents based on their integration capabilities and detection reliability. The installer handles each category differently according to the logic defined in bin/install.js.

Auto-Activating Agents

These agents support native plugin or extension systems that allow Caveman to activate immediately upon installation:

• Claude Code (claude): Installs via claude plugin marketplace add JuliusBrussee/caveman && claude plugin install caveman@caveman. Copies hook scripts from src/hooks/ to ~/.claude/hooks/ for activate, mode-tracker, stats, and statusline functionality.
• Gemini CLI (gemini): Executes gemini extensions install https://github.com/JuliusBrussee/caveman
• opencode (opencode): Registers the plugin via node bin/install.js --only opencode and exposes Caveman as a native skill through the AGENTS.md file
• OpenClaw (openclaw): Installs workspace skills and creates SOUL.md via npx -y github:JuliusBrussee/caveman -- --only openclaw
• Hermes Agent (hermes): Adds native skills using npx -y github:JuliusBrussee/caveman -- --only hermes

Per-Session Agents with Optional Persistence

Agents like Cursor, Windsurf, and Cline use npx skills add JuliusBrussee/caveman -a <agent> by default, activating only for the current session. To make these permanent, add the --with-init flag:

node bin/install.js --with-init --only cursor --only windsurf

This flag copies the static rule file from src/rules/caveman-activate.md into agent-specific directories (e.g., .cursor/rules/caveman.mdc), creating "always-on" rules that persist across sessions.

Soft-Probe Agents

GitHub Copilot and similar agents require explicit installation because they lack reliable auto-detection signals. Install these using:

npx -y github:JuliusBrussee/caveman -- --only copilot --with-init

These "soft probe" agents only install when requested via --only <id> and typically require --with-init for repository-wide activation.

Command-Line Flags and Usage Patterns

The installer in bin/install.js supports several flags that control its behavior, parsed through the parseArgs function:

Targeted Installation

Install specific agents only, skipping auto-detection:

# Install only for opencode

node bin/install.js --only opencode

# Install for multiple specific agents

node bin/install.js --only cursor --only windsurf

Safety and Preview Modes

• --dry-run: Prints every command that would execute without writing files or running installers
• --force: Forces re-installation even if Caveman is already present
• --no-hooks: Disables Claude Code hook installation while keeping the plugin

Installation Scope Control

• --all: Bypasses auto-detection and attempts installation for all supported agents
• --minimal: Installs only essential components, skipping optional features
• --with-mcp-shrink: Registers the optional MCP proxy for additional functionality

Listing Providers

View the complete provider matrix with detection status:

node bin/install.js --list

How the Installer Works Internally

The installation process follows a three-phase pipeline defined in bin/install.js:

1. Argument Parsing

The parseArgs function (around line 55) builds an options object from CLI flags, handling boolean switches like --dry-run, --all, and --minimal, as well as array flags like --only.

2. Detection Phase

The script iterates over the PROVIDERS array, executing each detection rule:

• command:<bin>: Checks if a binary exists on PATH
• vscode-ext:<needle>: Checks for VS Code extension installations
• dir:<path>: Validates configuration directories

When a provider matches, the corresponding installation command is queued for execution.

3. Execution Phase

For each queued provider, the installer performs one of three actions:

• CLI invocation: Runs agent-specific commands (e.g., claude plugin install)
• Skill registration: Executes npx skills add JuliusBrussee/caveman -a <agent>
• File deployment: Copies static rule files from src/rules/caveman-activate.md to agent-specific directories when --with-init is specified

Uninstalling Caveman

To remove all Caveman installations, hooks, plugins, and rule files:

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

This invokes bin/install.js with the --uninstall flag, which reverses the installation process by removing hook files from ~/.claude/hooks/, uninstalling plugins, and deleting rule files from repository directories.

Summary

• Caveman uses a unified installer (bin/install.js) that auto-detects AI agents via a provider matrix system
• Auto-detecting agents (Claude Code, Gemini CLI, opencode) install immediately when their binaries are found on PATH
• Per-session agents (Cursor, Windsurf, Cline) require --with-init to create permanent rule files in directories like .cursor/rules/caveman.mdc
• Soft-probe agents (GitHub Copilot) install only when explicitly requested with --only <id>
• The --dry-run flag lets you preview changes before executing them
• Uninstallation is handled by the same script using the --uninstall flag

Frequently Asked Questions

How do I install Caveman for just one specific AI agent?

Use the --only flag followed by the agent ID. For example, to install only for Cursor, run node bin/install.js --only cursor or npx -y github:JuliusBrussee/caveman -- --only cursor. You can repeat this flag multiple times to target several specific agents while ignoring others.

What is the difference between --all and the default auto-detect behavior?

The default behavior scans your system and installs Caveman only for agents it detects on your PATH or in standard configuration directories. The --all flag bypasses this detection and attempts to run the installation routine for every supported agent in the provider matrix, regardless of whether they appear to be installed.

Why does Caveman require --with-init for some agents but not others?

Agents like Claude Code and Gemini CLI support native plugin systems that allow Caveman to hook into their execution automatically. However, agents like Cursor, Windsurf, and Cline operate on a per-session basis by default. The --with-init flag tells the installer to drop static rule files (from src/rules/caveman-activate.md) into the repository, creating permanent "always-on" rules for agents that lack persistent plugin architectures.

Can I see what the installer will do before it makes changes?

Yes, run any installation command with the --dry-run flag. This prints every command that would be executed and every file that would be copied without actually performing the installation. For example: curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash -s -- --dry-run.

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