How to Set Up a Development Environment for Caveman: Complete Guide

To set up a development environment for Caveman, clone the JuliusBrussee/caveman repository, install Node.js dependencies with npm install, verify the installer detects your AI agents using --dry-run, and execute the installer to deploy hooks and rule files.

Caveman is a Node-based installer that detects AI coding agents on your machine and injects a compression skill into each of them. Setting up a development environment for Caveman requires the Node runtime, npm, and optionally Python 3 if you plan to run the token-saving benchmarks. This guide walks through cloning the source, installing dependencies, and validating your local setup using the actual installer scripts.

Prerequisites

Before you begin, ensure your system meets these requirements as defined in package.json and the benchmark harness:

• Node.js >=18 — Runs the installer, test suite, and per-repo initialization scripts
• npm — Bundled with Node; manages dependencies and executes npm test
• Python 3.10+ — Required only for running the benchmark suite (benchmarks/run.py)
• Git — For cloning the repository
• Anthropic API Key — Optional; store in .env.local only if running benchmarks that hit the Claude API

Step-by-Step Setup

Clone the Repository

Fetch the source code from GitHub and navigate into the project directory:

git clone https://github.com/JuliusBrussee/caveman.git
cd caveman

The repository root contains the cross-platform install scripts (install.sh and install.ps1), the Node source tree, and the test harness.

Install Node Dependencies

Install the required packages using npm:

npm install

The package.json file declares Node >=18 as the only runtime dependency, ensuring compatibility with the installer logic in bin/install.js.

Verify the Installer with Dry-Run

Test the installer without making system changes to confirm agent detection works on your machine:

node bin/install.js --dry-run --all

You should see a table listing detected agents such as claude, cursor, windsurf, or codenet. This validates that the PROVIDERS array in bin/install.js correctly identifies your installed AI tools.

Install the Skill

Once the dry-run output looks correct, perform the actual installation:

node bin/install.js --all

This command writes global hook files to ~/.claude/ (or the path specified by CLAUDE_CONFIG_DIR), creates per-repo rule files, and registers the caveman-shrink MCP proxy when requested.

Add Per-Repo Rule Files (Optional)

For development work within specific repositories, run the initialization script to drop activation rules into hidden directories:

node src/tools/caveman-init.js .

Running caveman-init.js inside a project directory ensures agents remain in "caveman mode" automatically without requiring the /caveman command, reading from src/rules/caveman-activate.md to generate the appropriate rule files for Cursor, Windsurf, Cline, Copilot, and Opencode.

Run the Test Suite

Validate your setup by executing the Node-based tests:

npm test

This runs the installer unit and e2e tests located in tests/installer/*.test.mjs. If you have Python configured, also run the safety tests:

python3 -m unittest tests.test_compress_safety

Configure Benchmark Environment (Optional)

To run token-saving benchmarks against the real Claude API, create a .env.local file:

echo "ANTHROPIC_API_KEY=your-key-here" > .env.local

Then execute the benchmark harness:

uv run python benchmarks/run.py

Results are stored under benchmarks/results/ and validate the compression statistics documented in the README.

Development Workflow

Use these commands when modifying the Caveman source:

Action	Command	Description
Edit rules	code src/rules/caveman-activate.md	Modify the canonical prompt that agents use for compression
Add agent support	Edit bin/install.js → PROVIDERS array	Extend detection logic, then verify with node bin/install.js --list
Update hooks	code src/hooks/caveman-activate.js	Modify session-start logic that writes flag files
Test init script	node src/tools/caveman-init.js --dry-run	Preview which rule files would be created without writing them
Full validation	npm test && python3 -m unittest tests.test_compress_safety	Catch regressions before submitting PRs
Publish	npm version patch && git push && npm publish	Uses the files field in package.json to ship minimal assets

Common Development Tasks

Installing for a Single Agent

Target a specific agent during development rather than installing globally:

node bin/install.js --only claude

Checking Installation Status

Verify that hooks are correctly registered by inspecting the flag file:

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

Expected output: full (or whatever compression level is active).

Uninstalling

Remove all Caveman artifacts during testing:

node bin/install.js --uninstall

Initializing a Specific Project Directory

Drop rule files into a specific repository without changing your working directory:

node src/tools/caveman-init.js --only cursor /path/to/project

Key Source Files

Understanding these paths is essential for development:

• bin/install.js — Core installer containing the PROVIDERS array, detection logic, and command dispatch
• src/tools/caveman-init.js — Idempotent CLI that writes always-on rule files into repositories
• src/rules/caveman-activate.md — The canonical caveman prompt consumed by all agents
• src/hooks/caveman-activate.js — Hook implementation that activates the skill on session start
• install.sh / install.ps1 — Cross-platform entry points that forward arguments to the Node installer
• package.json — Declares Node engine requirements and published file manifest

Summary

• Clone the JuliusBrussee/caveman repository and run npm install to fetch Node dependencies
• Verify agent detection using node bin/install.js --dry-run --all before making system changes
• Install globally with node bin/install.js --all to deploy hooks and rule files
• Initialize per-repo rules using node src/tools/caveman-init.js . for automatic activation
• Test changes using npm test and python3 -m unittest tests.test_compress_safety
• Benchmark token savings using uv run python benchmarks/run.py with a valid Anthropic API key

Frequently Asked Questions

What Node version is required to develop Caveman?

Caveman requires Node.js 18 or higher, as declared in the engines field of package.json. This version requirement ensures compatibility with the modern JavaScript features used in bin/install.js and the hook scripts.

How do I test the installer without modifying my system?

Use the --dry-run flag when executing the installer: node bin/install.js --dry-run --all. This simulates the detection and installation process, displaying which agents would be configured and which files would be written, without actually touching your ~/.claude/ directory or other config paths.

Why does the development environment need Python?

Python 3.10+ is only required if you want to run the benchmarks/run.py harness, which measures actual token savings against the Anthropic API. The core Caveman installer and all Node-based functionality work without Python installed.

Where does the installer write its configuration files?

According to bin/install.js, the installer writes global hook files to ~/.claude/ by default, or to the path specified by the CLAUDE_CONFIG_DIR environment variable. Per-repo rules are written to agent-specific hidden directories (like .cursor/rules/) when you run src/tools/caveman-init.js.

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