# Understanding the Primary Function of the Caveman Project

> Discover the primary function of the Caveman project. Learn how it injects a speech rule to cut AI output tokens by 65% with 100% technical accuracy, improving efficiency.

- Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman)
- Tags: getting-started
- Published: 2026-07-03

---

**The primary function of the caveman project is to inject a compact speech rule into AI-coding agents that strips filler language and reduces output tokens by approximately 65% while maintaining 100% technical accuracy.**

The **caveman** project by JuliusBrussee is a specialized skill/plugin designed to optimize how AI-coding assistants communicate. Understanding the primary function of the caveman project reveals its role as a lightweight transformer that compresses verbose agent responses into terse, high-density output without altering code snippets, commands, or technical terminology.

## What the Caveman Project Does

At its core, the caveman project functions as an **idempotent installer** that applies a language transformation rule to supported AI agents. The system operates on a simple but effective premise: remove soft language while preserving hard technical facts.

The transformation achieves approximately **65% reduction in output tokens** by:

- **Stripping filler words** – articles (a/an/the), hedging (just/really/basically), and pleasantries are eliminated
- **Preserving technical substance** – code snippets, shell commands, error messages, and URLs remain untouched
- **Maintaining exact terminology** – technical terms are kept verbatim; only surrounding prose is shortened

## The Rule Transformation Logic

The specific behavior is defined in **[`src/rules/caveman-activate.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md)**, which contains the directive:

```text
Respond terse like smart caveman. All technical substance stay. Only fluff die.

```

The rule explicitly instructs agents to:

- Use fragments and short synonyms
- Keep technical terms exact
- Leave code blocks unchanged
- Switch compression levels via `/caveman lite|full|ultra|wenyan`
- Revert to normal mode with "stop caveman"

## How the Installation Works

The **[`src/tools/caveman-init.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/tools/caveman-init.js)** script handles the primary installation logic. It detects which AI agents are present on the system and writes the rule file to the appropriate configuration directories.

For example, the installer targets:

- `.cursor/rules/caveman.mdc` for Cursor
- [`.windsurf/rules/caveman.md`](https://github.com/JuliusBrussee/caveman/blob/main/.windsurf/rules/caveman.md) for Windsurf

### One-Line Installation

Install the rule set across all detected agents:

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

```

### Dry-Run Verification

Preview which files would be modified without touching the filesystem:

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

```

This demonstrates the installer functionality without side effects, showing exactly which agent configurations would receive the rule.

## Controlling Compression Modes

Once installed, the **`/caveman`** command family provides runtime control:

- **`/caveman full`** – Activates default compression
- **`/caveman lite`** – Applies shorter, more aggressive phrasing
- **`/caveman ultra`** – Maximum compression level
- **`/caveman stop`** – Reverts to verbose mode

## Ancillary Utilities

Beyond the core speech transformation, the project includes helper tools for persistent optimization.

### Memory File Compression

The `caveman-compress` utility rewrites long-running context files to reduce their token footprint permanently:

```bash
caveman-compress CLAUDE.md

```

This is particularly useful for files like [`CLAUDE.md`](https://github.com/JuliusBrussee/caveman/blob/main/CLAUDE.md) that load into every session.

### Token Usage Statistics

Monitor savings with the stats command:

```bash
caveman-stats --share

```

Outputs a shareable summary (e.g., `🪨 CAVEMAN: 12.4k tokens saved`) suitable for status bars or documentation.

## Key Source Files and Architecture

The implementation relies on three critical components:

- **[`src/rules/caveman-activate.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md)** – The core rule definition containing the transformation logic and command syntax
- **[`src/tools/caveman-init.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/tools/caveman-init.js)** – The installer script that handles agent detection and file placement
- **[`commands/caveman.md`](https://github.com/JuliusBrussee/caveman/blob/main/commands/caveman.md)** – Documentation for the command interface and compression levels
- **[`commands/caveman-compress.md`](https://github.com/JuliusBrussee/caveman/blob/main/commands/caveman-compress.md)** – Specification for the memory file compression utility

These files work together to provide the primary function: a seamless, reversible method for reducing AI agent verbosity without sacrificing technical precision.

## Summary

- The primary function of the caveman project is to inject a **terse speech rule** into AI-coding agents, reducing output tokens by ~65%
- The rule lives in **[`src/rules/caveman-activate.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md)** and is installed via **[`src/tools/caveman-init.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/tools/caveman-init.js)**
- **Technical accuracy is preserved** – only filler language, articles, and pleasantries are removed
- Installation supports multiple agents including Cursor and Windsurf through agent-specific configuration paths
- Runtime control is available via **`/caveman`** commands with levels (lite, full, ultra, wenyan)
- Additional utilities (`caveman-compress`, `caveman-stats`) provide persistent token optimization

## Frequently Asked Questions

### What is the primary function of the caveman project?

The primary function is to act as a lightweight rule injector that compels AI-coding agents to communicate in a compressed "caveman" style. It eliminates filler words, articles, and hedging while preserving exact technical terminology, code snippets, and URLs, resulting in approximately 65% fewer output tokens.

### How does the caveman project reduce token usage?

The project reduces token usage by applying a transformation rule defined in [`src/rules/caveman-activate.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md) that strips soft language from agent responses. This rule is processed by the agent's prompt layer before returning output to the user, ensuring only dense, technical content remains while removing linguistic fluff.

### Which AI agents are supported by the caveman project?

The project supports Cursor, Windsurf, and other compatible AI-coding agents. The installer script [`src/tools/caveman-init.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/tools/caveman-init.js) automatically detects installed agents and writes the rule file to the appropriate locations, such as `.cursor/rules/caveman.mdc` for Cursor and [`.windsurf/rules/caveman.md`](https://github.com/JuliusBrussee/caveman/blob/main/.windsurf/rules/caveman.md) for Windsurf.

### How do I temporarily disable the caveman mode?

You can disable the compression by issuing the command `/caveman stop` or typing "stop caveman" or "normal mode" in your chat. This reverts the agent to its default verbose behavior without uninstalling the rule files from your repository.