How to Update Caveman to the Latest Version

Re-run the official installer to update Caveman, as it automatically pulls the newest code from the main branch and refreshes all AI agent integrations.

Caveman is a self-installing skill that wires itself into AI coding agents such as Claude Code, Cursor, and Gemini CLI. Since the "latest version" always corresponds to the current main branch of the JuliusBrussee/caveman repository, updating requires re-executing the installer to pull new scripts, hooks, and rule files.

Why Re-Running the Installer Updates Caveman

The installer (install.sh on macOS/Linux, install.ps1 on Windows) performs three critical operations defined in bin/install.js:

1. Detects agents on the host machine (e.g., claude, gemini, cursor, opencode).
2. Installs the Caveman skill for each detected agent, including plugins, rule files, and the optional MCP shrink proxy.
3. Writes configuration hooks such as Claude Code hook files, status-line badges, and flag files that enable /caveman commands.

Because these steps reference files that change between releases, re-running the installer guarantees that bug fixes, new agent support, and configuration tweaks are applied. The installer also creates a SHA-256 manifest to verify downloaded hook files, ensuring integrity during updates.

Update Caveman Using the One-Liner (Recommended)

The fastest way to update Caveman to the latest version is using the official one-liner commands, which download the current installer from the main branch and execute it.

macOS, Linux, WSL, and 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

These commands fetch the latest install.sh or install.ps1 and run node bin/install.js with the --all flag. The process will:

• Detect any newly supported agents.
• Refresh Caveman skill files for every installed agent.
• Overwrite existing hook files only if the new version's SHA-256 hash differs, making the operation safe to repeat.

Preview Changes with Dry-Run

To see what the installer will do without modifying your system, add the --dry-run flag:

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

Update from a Local Clone

If you maintain a local copy of the repository for offline use or review purposes, update Caveman by pulling the latest changes and running the installer directly:

git pull origin main
node bin/install.js --all

Requirements: Node.js version 18 or higher (see package.json lines 18-20).

You can also target specific agents rather than updating all:

# Update only Cursor

node bin/install.js --only cursor

# Update Claude Code with static rule files

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

All installation flags are documented in INSTALL.md.

Verify the Update Completed Successfully

After updating, confirm Caveman is running the latest version using these methods:

1. List installed agents: Run node bin/install.js --list to see version numbers next to each agent.
2. Check the flag file: Verify that $CLAUDE_CONFIG_DIR/.caveman-active (or equivalent for other agents) contains the active level (full, lite, etc.).
3. Test the command: In Claude Code, type /caveman. You should receive a terse response like "Got it. Caveman mode on."

If files appear outdated, re-run the installer with --force to overwrite existing installations.

Alternative Update Flags Reference

Caveman's installer supports several flags for specific update scenarios:

• --dry-run: Preview every command without touching the filesystem.
• --minimal: Install only the plugin/extension; skip hooks and MCP-shrink.
• --only <id>: Update a specific agent (e.g., cursor, gemini, claude).
• --with-init: Drop static rule files into the current repository for agents lacking hook support.
• --with-mcp-shrink="<cmd>": Enable the optional caveman-shrink proxy for upstream MCP servers.
• --force: Overwrite existing files regardless of SHA-256 verification.
• --uninstall: Remove all Caveman artifacts from the system.

Reference INSTALL.md in the repository for complete flag documentation.

Summary

• Re-run the installer to update Caveman to the latest version from the main branch.
• Use the one-liner commands (curl for Unix, irm for Windows) for the fastest update path.
• For local clones, run git pull origin main followed by node bin/install.js --all.
• Verify updates by checking node bin/install.js --list and testing /caveman commands.
• The installer uses SHA-256 manifests to safely overwrite only changed files.

Frequently Asked Questions

Do I need to uninstall Caveman before updating to the latest version?

No, you do not need to uninstall. Re-running the installer safely overwrites existing files. The installer in bin/install.js compares SHA-256 hashes before replacing hook files, ensuring it only updates components that have actually changed between versions.

Can I update Caveman for only one specific AI agent?

Yes. Instead of using the one-liner, navigate to your local clone and run node bin/install.js --only <agent-id>. For example, node bin/install.js --only cursor updates only the Cursor integration while leaving other agents untouched. This is useful when you want to test a new version on one agent before updating others.

What Node.js version is required to update Caveman?

Caveman requires Node.js version 18 or higher. This requirement is defined in package.json (lines 18-20). If your system runs an older version, the installer will fail, and you must upgrade Node.js before attempting to update Caveman.

Is there a way to automate Caveman updates?

While there is no built-in auto-updater, you can automate the process by scheduling the one-liner command or by running git pull and node bin/install.js --all in a cron job or CI pipeline. Since the installer is idempotent—only changing files when the SHA-256 hash differs—it is safe to run frequently without risking configuration drift.

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