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

Caveman is a token-shrinking skill for AI coding agents that you install locally using a single Node.js script from 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 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:

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

Windows PowerShell One-Liner

For Windows environments, use this equivalent command:

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:

node bin/install.js

How the Installer Works

The installation process centers on 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 – 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, caveman-mode-tracker.js, caveman-statusline.*) copied into agent config directories (e.g., ~/.claude/hooks/)
• Skill packages – Markdown files (caveman.md, 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
• 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 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 using helpers from src/lib/settings.js

Running Caveman After Installation

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

/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:

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):

node bin/install.js --only opencode

Force Reinstall with Hooks

Rewrite all hook files and force reinstallation:

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

Summary

• Caveman from JuliusBrussee/caveman is a token-shrinking skill installed via the unified 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 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, 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, 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 using helper functions from src/lib/settings.js when you use the --with-hooks flag or when automatic plugin installation fails.

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