How to Install caveman on POSIX and Windows Systems

caveman installs on POSIX systems via a curl-to-bash one-liner and on Windows via a PowerShell one-liner, both of which bootstrap the Node.js installer at bin/install.js to detect AI agents and configure plugins.

The caveman repository by JuliusBrussee provides a cross-platform installation system that automatically detects AI coding agents on your machine and installs the appropriate plugins, extensions, and optional hooks. Whether you are running macOS, Linux, WSL, or native Windows, the installation process requires only a single command to download the bootstrap script and execute the core installer logic.

POSIX Installation (macOS, Linux, WSL, Git Bash)

On any POSIX-compatible shell, including macOS Terminal, Linux distributions, Windows Subsystem for Linux (WSL), and Git Bash, you can install caveman using the provided shell script.

One-Liner Installation

Run the following command to stream the installer directly to bash:

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

The install.sh script fetches the real installer at bin/install.js and executes it with default flags (--all). This detects all supported AI agents and installs the corresponding components.

Review Before Running

For security-conscious environments, download the script first to inspect its contents before execution:

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

# Inspect install.sh contents here

bash install.sh

Customization Options

The POSIX installer accepts multiple flags to customize behavior. Pass arguments after the -s -- separator when using the pipe method:

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

This example installs only the opencode agent and performs a dry run to preview commands without executing them.

Windows Installation (PowerShell 5.1+)

Windows installations use a PowerShell bootstrap script that provides equivalent functionality to the POSIX version.

One-Liner Installation

Execute the following command in PowerShell to download and run the installer:

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

The install.ps1 script downloads the core bin/install.js logic and executes it with default parameters.

Review Before Running

To inspect the script before execution, save it to disk first:

irm https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.ps1 -OutFile install.ps1

# Review install.ps1 contents here

.\install.ps1

Customization Options

The PowerShell installer supports the same flags as the POSIX version because it forwards all arguments to node bin/install.js. For example, to install only the Cursor agent while skipping global hook modifications:

.\install.ps1 --only cursor --no-hooks

Common Installation Flags

Both installers support identical command-line flags managed by bin/install.js:

Flag	Description
--all	Install plugins, hooks, status-line badges, and per-repo rule files for all detected agents (default behavior).
--only <id>	Install for a single agent only. Repeatable for multiple specific agents.
--dry-run	Print every command that would execute without making actual changes.
--with-init	Drop static rule files (.cursor/rules/caveman.mdc, .windsurf/rules/, etc.) into the current repository.
--with-mcp-shrink="<cmd>"	Register the caveman-shrink proxy MCP server with the specified upstream command.
--no-hooks	Skip installation of Claude Code hooks.
--minimal	Install only plugins/extensions; skip hooks, MCP-shrink, and per-repo rules.
--uninstall	Remove all caveman artifacts from the system.

Verification

After installation completes, verify the setup by listing detected agents and installed components:

node bin/install.js --list

If you use Claude Code, type /caveman to confirm that the short-hand mode is active and properly hooked into the agent.

Manual Installation from Source

For complete control over the installation process or to modify the source, clone the repository and run the installer directly:

git clone https://github.com/JuliusBrussee/caveman.git
cd caveman
node bin/install.js --all

This method allows you to inspect the core logic in bin/install.js, the settings parser in bin/lib/settings.js, and the static rule templates in src/rules/caveman-activate.md before execution.

Summary

• POSIX systems use curl -fsSL .../install.sh | bash to bootstrap the installer, with optional flags passed via bash -s -- [flags].
• Windows systems use irm .../install.ps1 | iex in PowerShell, supporting identical customization flags.
• Both methods ultimately execute bin/install.js, which detects AI agents and installs appropriate plugins, extensions, and optional hooks.
• Use --dry-run to preview changes before applying them, and --only <agent> to limit installation to specific coding agents.

Frequently Asked Questions

How do I install caveman without giving it immediate execution privileges?

Download the bootstrap script to your local machine first, inspect the contents of install.sh (POSIX) or install.ps1 (Windows), and then execute it manually with bash install.sh or .\install.ps1. This ensures you can audit the code that fetches bin/install.js before it runs.

Can I install caveman for only one specific AI agent instead of all detected ones?

Yes. Use the --only <id> flag followed by the agent identifier. For example, bash install.sh --only cursor (POSIX) or .\install.ps1 --only cursor (Windows) installs only the Cursor IDE extension and rules, ignoring other detected agents like Claude Code or Windsurf.

What is the difference between the bootstrap scripts and the core installer?

The bootstrap scripts (install.sh and install.ps1) are thin wrappers that download and execute the core installer at bin/install.js. The bootstrap handles the initial download, while bin/install.js contains the actual logic for detecting AI agents, parsing settings via bin/lib/settings.js, and writing configuration files to the appropriate system directories.

How do I completely remove caveman from my system?

Run the installer with the --uninstall flag. This triggers the uninstallation routine in bin/install.js that removes all caveman artifacts, including plugins, hooks, MCP proxy configurations, and per-repo rule files, restoring your AI agents to their pre-caveman state.

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