How to Install and Set Up the Caveman Project for AI Coding Agents

Run a single command to auto-detect and configure Caveman for Claude Code, Gemini, Cursor, and other supported agents on your system.

Caveman is a lightweight skill that plugs into AI coding agents to rewrite their responses in terse "caveman-speak." The JuliusBrussee/caveman repository provides a cross-platform installer that handles detection, plugin installation, and hook configuration automatically. This guide covers the complete installation process using the official Node.js-based installer.

Prerequisites

Before running the installer, ensure your environment meets the following requirements:

• Node.js >= 18 – The checkNodeVersion() function in bin/install.js enforces this minimum version.
• AI agents on PATH – The target agents (e.g., claude, gemini, cursor, opencode) must be accessible from your shell.
• Windows PowerShell execution policy – On Windows, allow script execution with Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass before running the PowerShell one-liner.

One-Command Installation

The fastest way to install Caveman uses a single command that downloads and executes the appropriate installer for your platform.

macOS, Linux, and WSL

Run the bash one-liner to auto-detect all supported agents and configure them:

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

This command downloads install.sh, which delegates to bin/install.js to detect agents, run native install commands (e.g., claude plugin install, gemini extensions install), and copy hook files.

Windows PowerShell

For Windows environments, use the PowerShell one-liner:

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

The install.ps1 script performs the same detection logic as the Unix version but installs Windows-specific hooks like caveman-statusline.ps1.

Manual Installation for Auditing

If you prefer to review the code before execution, clone the repository and run the installer locally:

git clone https://github.com/JuliusBrussee/caveman.git
cd caveman
node bin/install.js --list    # Preview detected agents

node bin/install.js --all     # Install for all detected agents

Manual installation allows you to use flags like --dry-run to preview changes or --only <agent> to target specific agents.

How the Installer Works

The core logic in bin/install.js follows a multi-step architecture to ensure idempotent configuration across different agent ecosystems.

Agent Detection Matrix

The installer defines a PROVIDERS array that maps each agent to a detection rule. According to the source code, it checks for:

• Command existence – e.g., command:claude verifies the claude binary is on PATH.
• VS Code extensions – e.g., vscode-ext:cursor detects Cursor via VS Code extension metadata.
• Configuration directories – e.g., dir:$HOME/.openclaw/workspace locates OpenClaw installations.

The installer automatically selects all detected agents unless you specify --only <id>.

Native Plugin Installation

Depending on the detected agent, the installer invokes the appropriate native command:

• Claude Code – claude plugin install
• Gemini CLI – gemini extensions install
• Cursor, OpenClaw, Opencode – npx skills add JuliusBrussee/caveman -a <agent>

Hook Wiring for Claude Code

For Claude Code specifically, the installer copies JavaScript hook files (caveman-activate.js, caveman-mode-tracker.js) into $CLAUDE_CONFIG_DIR/hooks/ and merges them into settings.json. This ensures the "SessionStart" and "UserPromptSubmit" events trigger caveman mode. The installer backs up existing configurations (e.g., settings.json.bak) before overwriting.

Persistent Rule Files

Agents that lack a dynamic hook system (Cursor, Windsurf, Cline, Copilot) receive a static rule file. When using --with-init, the installer copies src/rules/caveman-activate.md into:

• .cursor/rules/
• .windsurf/rules/
• .clinerules/
• .github/copilot-instructions.md

These files enable caveman mode persistently without global configuration changes.

Advanced Installation Options

Preview Changes with Dry Run

To see what the installer would do without making changes:

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

This outputs the detection results and planned file operations without writing to disk.

Install for Specific Agents Only

Target a single agent to avoid modifying others:

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

Or manually:

node bin/install.js --only gemini

MCP-Shrink Proxy

Enable the optional MCP proxy for token compression in downstream tools:

curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash -s -- --with-mcp-shrink="npx @modelcontextprotocol/server-filesystem /tmp"

This registers caveman-shrink in the Opencode MCP configuration.

Verify Your Installation

Confirm the setup succeeded by checking the following:

1. List detected agents – Run node bin/install.js --list and verify checkmarks appear next to your installed agents.
2. Test the command – Open Claude Code (or your configured agent) and type /caveman. You should receive a terse response like "Got it. Caveman mode on."
3. Check Claude Code flag file – Verify the activation marker exists:

   cat "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/.caveman-active"

Uninstalling Caveman

Remove all Caveman configurations and plugins with:

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

This command cleans up hook files, rule files, and agent-specific plugin registrations.

Summary

• Single-command install – Use curl ... | bash on Unix or irm ... | iex on Windows to auto-detect and configure all agents.
• Manual control – Clone the repo and run node bin/install.js with --dry-run, --only, or --all for granular control.
• Hook vs. Rule files – Claude Code uses dynamic hooks in $CLAUDE_CONFIG_DIR/hooks/, while Cursor and others use static rule files in repository-specific directories.
• Safe and idempotent – The installer backs up existing configs and only overwrites with --force.
• Node.js 18+ required – The checkNodeVersion() function enforces this minimum before any installation steps.

Frequently Asked Questions

What is the minimum Node.js version required to install Caveman?

Caveman requires Node.js version 18 or higher. The checkNodeVersion() function in bin/install.js validates your environment before proceeding with installation and will exit with an error if your Node version is insufficient.

Can I install Caveman for only one specific AI agent?

Yes. Use the --only <agent> flag with the installer to target a single agent. For example, bash -s -- --only cursor installs only for Cursor, skipping detection and configuration for other agents like Claude Code or Gemini.

Where does Caveman store its configuration files?

For Claude Code, Caveman writes hook files to $CLAUDE_CONFIG_DIR/hooks/ (typically ~/.claude/hooks/). For agents like Cursor, Windsurf, and Cline, it drops rule files into repository-specific directories such as .cursor/rules/ or .windsurf/rules/. The installer always backs up existing files before modifying them.

How do I remove Caveman from my system?

Run the uninstall command npx -y github:JuliusBrussee/caveman -- --uninstall to remove all Caveman configurations, hook files, and plugin registrations from your detected agents. This command reverses the installation process while preserving your backed-up configuration files.

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