# How to Run Caveman Locally: Complete Setup Guide for AI Coding Agents

> Learn how to run Caveman locally with this complete setup guide. Install this token-shrinking AI coding agent skill using a single Node.js script and auto-detect supported agents.

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

---

**Caveman is a token-shrinking skill for AI coding agents that you install locally using a single Node.js script from [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js), which auto-detects supported agents like Claude Code, Gemini CLI, and Cursor, then wires the necessary hooks or skill packages.**

Caveman, developed in the JuliusBrussee/caveman repository, is a lightweight "token-shrinking" capability designed for AI coding agents. It compresses responses to reduce token usage and can be added to any supported agent on your local machine. The unified installer handles cross-platform setup, agent detection, and configuration automatically.

## Prerequisites

Before running Caveman locally, ensure you have **Node.js version 18 or higher** installed. The installer script in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) performs an early version check via `checkNodeVersion()` and aborts immediately if Node is missing or outdated.

## Quick Installation Methods

### One-Liner Install (macOS/Linux/WSL)

Run this command to download and execute the installer directly:

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

```

### Windows PowerShell One-Liner

For Windows environments, use this equivalent command:

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

```

### Manual Installation with Node

If you prefer to run the installer directly from the repository:

```bash
node bin/install.js

```

## How the Installer Works

The installation process centers on **[`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js)**, a unified cross-platform installer that orchestrates setup across multiple AI agents.

### Core Components

The installer manages several key components:

- **[`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js)** – Parses command-line flags, detects agents via the **PROVIDERS** matrix, and executes per-agent install functions (`installClaude`, `installGemini`, `installOpencode`, etc.)
- **Hook files** – JavaScript and shell scripts ([`caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-activate.js), [`caveman-mode-tracker.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-mode-tracker.js), `caveman-statusline.*`) copied into agent config directories (e.g., `~/.claude/hooks/`)
- **Skill packages** – Markdown files ([`caveman.md`](https://github.com/JuliusBrussee/caveman/blob/main/caveman.md), [`caveman-commit.md`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-commit.md)) in the `skills/caveman` folder that define agent commands
- **Static rule files** – For agents without plugin systems, the installer drops files like `.cursor/rules/caveman.mdc` into your repository or appends rules to [`AGENTS.md`](https://github.com/JuliusBrussee/caveman/blob/main/AGENTS.md)
- **Optional MCP proxy** – `caveman-shrink` can be registered as an MCP server via `installMcpShrink()` to compress file-tree tool descriptions

### Agent Detection and Installation Flow

The installer follows this sequence:

1. **Node version validation** – Confirms Node ≥ 18 via `checkNodeVersion()`
2. **Agent detection** – The **PROVIDERS** matrix defines detection rules (e.g., `command:claude`, `vscode-ext:cursor`) checked via `hasCmd()` and `vscodeExtPresent()`
3. **Per-agent actions** – Depending on the provider, the installer:
   - Calls native install commands (`claude plugin install`, `gemini extensions install`)
   - Runs `npx skills add … -a <profile>` to push markdown skill files
   - Copies opencode plugin files to `~/.config/opencode/`
   - Appends always-on rule blocks to repo-local [`AGENTS.md`](https://github.com/JuliusBrussee/caveman/blob/main/AGENTS.md) files
4. **Hook wiring** – If plugin installation fails or you pass `--with-hooks`, `installHooks()` copies scripts to the config `hooks/` directory and merges entries into [`settings.json`](https://github.com/JuliusBrussee/caveman/blob/main/settings.json) using helpers from [`src/lib/settings.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/lib/settings.js)

## Running Caveman After Installation

Once installed, activate Caveman mode using slash commands in supported agents:

```text
/caveman          # enable default "full" mode

/caveman lite    # lighter compression

/caveman ultra   # extreme compression

stop caveman      # revert to normal prose

```

For agents relying on static rule files (like Cursor), the rules remain automatically active for the session lifetime.

## Verification Methods

To confirm Caveman is running locally:

- **Claude Code**: Check for the `[CAVEMAN]` statusline badge and the flag file `~/.claude/.caveman-active` containing the active level (e.g., `full`)
- **General**: Run `node bin/install.js --list` to see detected agents and installation status

## Advanced Installation Options

### Dry-Run Mode

Preview actions without executing them:

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

```

### Install for Specific Agent

Target only one agent (e.g., opencode):

```bash
node bin/install.js --only opencode

```

### Force Reinstall with Hooks

Rewrite all hook files and force reinstallation:

```bash
node bin/install.js --force --with-hooks

```

## Summary

- **Caveman** from JuliusBrussee/caveman is a token-shrinking skill installed via the unified [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) Node script
- The installer requires **Node.js ≥ 18** and auto-detects supported agents via the **PROVIDERS** matrix
- Installation methods include one-liner scripts for macOS/Linux/WSL and Windows PowerShell, or manual execution with `node bin/install.js`
- The installer handles **hook files**, **skill packages**, and **static rule files** depending on agent capabilities
- Activate Caveman using `/caveman` commands or rely on always-on rules for agents without plugin systems
- Verify installation using `--list` flag or by checking for the `[CAVEMAN]` statusline badge in Claude Code

## Frequently Asked Questions

### What is the minimum Node.js version required to run Caveman locally?

Caveman requires **Node.js version 18 or higher**. The installer in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) runs `checkNodeVersion()` at startup and aborts immediately if your Node version is too old or missing.

### Which AI coding agents does Caveman support?

Caveman supports **Claude Code**, **Gemini CLI**, **Cursor**, **opencode**, and **OpenClaw**, among others. The installer detects available agents via the **PROVIDERS** matrix in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js), which checks for command-line tools (`hasCmd`) and VS Code extensions (`vscodeExtPresent`), then runs appropriate installation functions like `installClaude`, `installGemini`, or `installOpencode`.

### How do I enable Caveman mode after installation?

For agents with runtime command support (Claude Code, Cursor), type `/caveman` to enable default mode, `/caveman lite` for lighter compression, or `/caveman ultra` for extreme compression. To disable, use `stop caveman`. For agents using static rule files, the rules are automatically active once installed.

### Where does Caveman install its hook files?

Hook files like [`caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-activate.js), [`caveman-mode-tracker.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-mode-tracker.js), and `caveman-statusline.*` are copied into the agent's configuration directory (e.g., `~/.claude/hooks/`). The installer then merges these entries into the agent's [`settings.json`](https://github.com/JuliusBrussee/caveman/blob/main/settings.json) using helper functions from [`src/lib/settings.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/lib/settings.js) when you use the `--with-hooks` flag or when automatic plugin installation fails.