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

> Set up your Caveman development environment easily. Clone the JuliusBrussee/caveman repo, install Node.js, and deploy hooks and rule files.

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

---

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

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

```

The repository root contains the cross-platform install scripts ([`install.sh`](https://github.com/JuliusBrussee/caveman/blob/main/install.sh) and `install.ps1`), the Node source tree, and the test harness.

### Install Node Dependencies

Install the required packages using npm:

```bash
npm install

```

The [`package.json`](https://github.com/JuliusBrussee/caveman/blob/main/package.json) file declares Node `>=18` as the only runtime dependency, ensuring compatibility with the installer logic in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js).

### Verify the Installer with Dry-Run

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

```bash
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`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) correctly identifies your installed AI tools.

### Install the Skill

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

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

```bash
node src/tools/caveman-init.js .

```

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

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

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

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

```

Then execute the benchmark harness:

```bash
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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/package.json) to ship minimal assets |

## Common Development Tasks

### Installing for a Single Agent

Target a specific agent during development rather than installing globally:

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

```

### Checking Installation Status

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

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

```

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

### Uninstalling

Remove all Caveman artifacts during testing:

```bash
node bin/install.js --uninstall

```

### Initializing a Specific Project Directory

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

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

```

## Key Source Files

Understanding these paths is essential for development:

- **[`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js)** — Core installer containing the `PROVIDERS` array, detection logic, and command dispatch
- **[`src/tools/caveman-init.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/tools/caveman-init.js)** — Idempotent CLI that writes always-on rule files into repositories
- **[`src/rules/caveman-activate.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md)** — The canonical caveman prompt consumed by all agents
- **[`src/hooks/caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-activate.js)** — Hook implementation that activates the skill on session start
- **[`install.sh`](https://github.com/JuliusBrussee/caveman/blob/main/install.sh) / `install.ps1`** — Cross-platform entry points that forward arguments to the Node installer
- **[`package.json`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/package.json). This version requirement ensures compatibility with the modern JavaScript features used in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/src/tools/caveman-init.js).