# How to Update Caveman to the Latest Version

> Easily update Caveman to the latest version by re-running the official installer. It refreshes AI agent integrations with the newest code from the main branch.

- Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman)
- Tags: how-to-guide
- Published: 2026-07-04

---

**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`](https://github.com/JuliusBrussee/caveman/blob/main/install.sh) on macOS/Linux, `install.ps1` on Windows) performs three critical operations defined in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/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

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

```

### Windows PowerShell (5.1+)

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

```

These commands fetch the latest [`install.sh`](https://github.com/JuliusBrussee/caveman/blob/main/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:

```bash
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:

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

```

**Requirements:** Node.js version 18 or higher (see [`package.json`](https://github.com/JuliusBrussee/caveman/blob/main/package.json) lines 18-20).

You can also target specific agents rather than updating all:

```bash

# 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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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.