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

Caveman installs via a single universal script that auto-detects your AI coding agents and wires the appropriate plugins, extensions, or rule files to each environment.

JuliusBrussee/caveman is an open-source compatibility layer that adds a "caveman mode" skill to Claude Code, Cursor, Gemini CLI, and other AI agents. The installation is idempotent, meaning you can safely rerun it multiple times without duplicate configurations.

Universal One-Liner Installation

The fastest way to install Caveman across all detected agents uses a thin shell wrapper that downloads and executes the native installer.

macOS and Linux:

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

These scripts download bin/install.js and execute it with default settings. The installer reads a hard-coded PROVIDERS matrix to detect which AI agent binaries exist on your PATH, then runs each agent's native install command automatically.

Agent-Specific Installation Methods

While the universal installer handles most cases, you can target specific agents manually when you need granular control.

Claude Code

For Claude Code, the installer adds a JSON plugin and activation hooks to your configuration directory:

claude plugin marketplace add JuliusBrussee/caveman && claude plugin install caveman@caveman

The installer also writes hook files (caveman-activate.js, caveman-mode-tracker.js) and a statusline badge script to $CLAUDE_CONFIG_DIR/plugins/. It creates a .caveman-active flag file to enable automatic activation on every session.

Cursor

Cursor receives the Caveman skill via the Vercel skills registry:

npx skills add JuliusBrussee/caveman -a cursor

Alternatively, you can drop the static rule file directly into your repository:

curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/src/rules/caveman-activate.md \
  > .cursor/rules/caveman.mdc

Static rules in src/rules/caveman-activate.md do not auto-activate; you must invoke /caveman each session unless you use the --with-init flag.

Gemini CLI, OpenCode, and OpenClaw

The installer handles these agents automatically when detected:

• Gemini CLI: Installs to ~/.gemini/extensions/ and activates immediately.
• OpenCode: Places the plugin in ~/.config/opencode/plugins/caveman/ and adds an AGENTS.md block.
• OpenClaw: Creates a skill folder in ~/.openclaw/workspace/ with a SOUL.md marker.

Advanced Installation Options

The native installer (bin/install.js) supports several flags for customized deployments.

Preview Installation Commands

Use --dry-run to see exactly what commands would execute without modifying your system:

node bin/install.js --dry-run

Install for a Single Agent

To bypass auto-detection and target only one agent:

# Via the installer directly

node bin/install.js --only claude

# Via the one-liner with arguments

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

Repo-Local Installation Without Global Hooks

For Cursor, Windsurf, Cline, or Copilot (which use static rule files rather than plugins), you can install without global configuration:

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

This drops .cursor/rules/caveman.mdc, .windsurf/rules/, .clinerules/, or .github/copilot-instructions.md into your current repository. The src/tools/caveman-init.js helper generates these per-repo init files when --with-init is supplied.

Verification and Uninstallation

Verify your installation by listing detected agents and their status:

node bin/install.js --list

For Claude Code specifically, check the activation flag:

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

You should see the active level (e.g., full) if the hooks are properly configured.

To completely remove Caveman:

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

This removes Claude Code hooks and the .caveman-active file, uninstalls all plugins/extensions managed by the installer, deletes the opencode plugin directory and AGENTS.md block, removes the OpenClaw skill folder and SOUL.md marker, and cleans up the global caveman skill folder. Note that skills installed via npx skills add remain managed by the skills CLI and require separate removal.

Summary

• Universal install: Use the curl or irm one-liner to auto-detect and configure all agents.
• Idempotent design: Re-run the installer safely; it skips already-installed components.
• Direct installer: bin/install.js contains the core logic and accepts --dry-run, --only <id>, and --with-init flags.
• Claude Code: Receives JSON plugins and activation hooks in $CLAUDE_CONFIG_DIR/plugins/.
• Cursor: Uses npx skills add or static rule files in .cursor/rules/ depending on your preference.
• Clean removal: The --uninstall flag removes all global configurations while preserving other skill registries.

Frequently Asked Questions

Does Caveman install globally or per-project?

Caveman installs globally for CLI agents like Claude Code and Gemini by placing plugins in your home directory configuration folders. For Cursor, Windsurf, and similar agents, it can install globally (via npx skills add) or per-project (via --with-init which drops rule files into .cursor/rules/ or equivalent directories). The --with-init flag is specifically designed for repo-local rule file generation without touching global settings.

Why do I need to run /caveman in Cursor but not Claude Code?

Claude Code supports hooks and plugins that can auto-activate on session start; the installer writes caveman-activate.js and a flag file (.caveman-active) to enable this. Cursor and similar editors use static Markdown rule files (src/rules/caveman-activate.md) that cannot execute code or auto-trigger; they require manual invocation. Add --with-init during installation to generate permanent rule files that persist across sessions without manual activation.

Can I install Caveman on a machine without Node.js?

The universal one-liners require either bash (macOS/Linux) or PowerShell (Windows) to download the installer, but the native installer (bin/install.js) itself requires Node.js to execute the PROVIDERS matrix logic and dispatch commands. If you cannot install Node.js, you must manually copy the static rule files from src/rules/caveman-activate.md to your agent's configuration directory.

How do I update Caveman to the latest version?

Simply re-run the universal installer. Because the installation is idempotent, it will detect your existing configuration and update the skill files in dist/caveman.skill and plugin directories without duplicating entries or breaking your existing hooks. For agents installed via npx skills add, use the skills CLI update commands instead.

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