Understanding the Primary Function of the Caveman Project

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, which contains the directive:

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 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 for Windsurf

One-Line Installation

Install the rule set across all detected agents:

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:

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:

caveman-compress CLAUDE.md

This is particularly useful for files like CLAUDE.md that load into every session.

Token Usage Statistics

Monitor savings with the stats command:

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 – The core rule definition containing the transformation logic and command syntax
• src/tools/caveman-init.js – The installer script that handles agent detection and file placement
• commands/caveman.md – Documentation for the command interface and compression levels
• 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 and is installed via 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 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 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 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.

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