How to Install Caveman for Claude Code, Cursor, or Other AI Agents

Caveman installs via a universal one-liner that auto-detects your AI coding agents and wires the appropriate plugin, extension, or rule file to each supported environment.

The Caveman project (JuliusBrussee/caveman) provides a cross-platform installer that eliminates manual configuration for supported AI agents. Whether you use Claude Code, Cursor, Gemini CLI, or other coding assistants, the installer handles agent detection, native command execution, and file placement through a single entry point.

Three-Layer Installation Architecture

The installation system works through three coordinated layers defined in the source code:

1. Universal one-liner – Shell scripts (install.sh or install.ps1) download and execute the native installer
2. bin/install.js – The core installer that reads a PROVIDERS matrix, detects agents on your PATH, and executes per-agent install commands
3. Agent-specific assets – Plugin files for Claude Code, extension directories for Gemini CLI, or static rule files (.cursor/rules/caveman.mdc) for agents like Cursor, Windsurf, and Cline

The installer is idempotent, meaning you can safely rerun it without duplicating components. It automatically skips already-installed agents and can be run with flags like --dry-run to preview actions or --only <id> to target specific agents.

Quick Start: Install All Detected Agents

Run the universal installer to automatically detect and configure every supported agent on your system.

macOS, Linux, WSL, or Git Bash:

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

Windows PowerShell 5.1+:

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

This script executes the following actions according to the source in bin/install.js:

• Scans your PATH for installed agents (Claude Code, Cursor, Gemini CLI, etc.)
• Runs native install commands (e.g., claude plugin install, gemini extensions install)
• Writes Claude Code hook files (caveman-activate.js, caveman-mode-tracker.js)
• Places the compiled skill (dist/caveman.skill) into appropriate plugin directories
• Optionally generates permanent rule files if you pass --with-init

Installing Specific Agents Only

To install Caveman for just one agent instead of all detected environments, use the --only flag.

Claude Code only:

node bin/install.js --only claude

Cursor only (via the Vercel skills registry):

npx skills add JuliusBrussee/caveman -a cursor

Via the one-liner with arguments:

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

The --only flag filters the PROVIDERS array in bin/install.js to execute installation logic for a single agent ID, skipping the auto-detection phase entirely.

Installation Options and Flags

The bin/install.js installer supports several flags for customized deployments:

• --dry-run – Preview all commands without executing them
• --with-init – Generate permanent rule files (e.g., .cursor/rules/caveman.mdc) in the current repository for repo-local activation
• --only <id> – Install for a specific agent only (e.g., claude, cursor, gemini)
• --all – Force installation for all supported agents regardless of detection (used when running the installer directly)

Repo-local installation without global hooks:

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

This command drops the activation rule from src/rules/caveman-activate.md into .cursor/rules/caveman.mdc without modifying global configuration directories.

Agent-Specific Installation Paths

Each agent receives Caveman through a different mechanism based on its architecture:

Claude Code

• Location: $CLAUDE_CONFIG_DIR/plugins/ (JSON plugin format)
• Auto-activate: Yes – writes .caveman-active flag file and hooks
• Command: claude plugin install caveman@caveman

Cursor, Windsurf, Cline, Copilot

• Location: Repo-local rule directories (.cursor/rules/, .windsurf/rules/, .clinerules/, .github/copilot-instructions.md)
• Auto-activate: No – requires typing /caveman each session unless you use --with-init
• Source: Static rule file from src/rules/caveman-activate.md

Gemini CLI

• Location: ~/.gemini/extensions/
• Auto-activate: Yes

opencode

• Location: ~/.config/opencode/plugins/caveman/
• Auto-activate: Yes – includes plugin and AGENTS.md block

OpenClaw

• Location: ~/.openclaw/workspace/ (skill folder with SOUL.md block)
• Auto-activate: Yes

Verification Steps

Confirm your installation succeeded by checking these specific artifacts:

List installed agents:

node bin/install.js --list

Verify Claude Code activation:

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

This should output the active level (e.g., full).

Check statusline badge: Open Claude Code – you should see [CAVEMAN] in the bottom status bar if the hook files (caveman-statusline.sh or caveman-statusline.ps1) were correctly written to the config directory.

Uninstalling Caveman

Remove all Caveman components using the built-in uninstall routine:

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

This command removes:

• Claude Code hook entries and the .caveman-active flag file
• All plugins/extensions installed by the original installer
• The opencode plugin directory and its AGENTS.md block
• The OpenClaw skill folder and SOUL.md marker
• The global caveman skill folder

Note that skills installed via npx skills add are managed by the separate skills CLI and must be removed using that tool's native commands.

Summary

• Caveman installs through a universal shell script that downloads bin/install.js and executes the PROVIDERS matrix
• Use curl | bash for macOS/Linux or irm | iex for Windows to auto-detect all agents
• Add --only <agent> to target specific agents like Claude Code or Cursor
• Include --with-init to generate permanent rule files in repo-local directories for agents that don't support auto-activation
• The installer manages different asset types: plugins for Claude Code, extensions for Gemini CLI, and static rules for Cursor/Windsurf
• Verify installation by checking the .caveman-active file or running node bin/install.js --list

Frequently Asked Questions

How do I install Caveman for Cursor specifically?

For Cursor, you have two options. Run the universal installer with the --only flag: curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash -s -- --only cursor. Alternatively, use the Vercel skills registry: npx skills add JuliusBrussee/caveman -a cursor. Unlike Claude Code, Cursor requires either typing /caveman each session or using the --with-init flag to create a permanent rule file at .cursor/rules/caveman.mdc.

Is the Caveman installer safe to run multiple times?

Yes, the installer is idempotent. According to the logic in bin/install.js, rerunning the installation safely skips components that are already present. You can use this behavior to update your installation or add new agents without worrying about duplicate files or configurations.

What is the difference between --with-init and standard installation?

Standard installation configures global agent settings (like Claude Code plugins or Gemini extensions). The --with-init flag specifically generates repo-local rule files from src/rules/caveman-activate.md into directories like .cursor/rules/ or .windsurf/rules/. This is necessary for agents like Cursor that don't support automatic activation through hooks, allowing you to commit the activation rule to your repository.

Where does Caveman store its configuration files?

Claude Code plugins live in $CLAUDE_CONFIG_DIR/plugins/, while Gemini CLI extensions reside in ~/.gemini/extensions/. The opencode plugin is stored at ~/.config/opencode/plugins/caveman/. For agents requiring static rules (Cursor, Windsurf, Cline), files are placed in repo-local directories (e.g., .cursor/rules/caveman.mdc) unless you manually copy them to global locations.

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