# Key Files to Understand the Caveman Project: Architecture and Source Guide

> Explore key Caveman project files like README.md and caveman-init.js to quickly grasp its architecture and source code. Dive into the token-compression skill today.

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

---

**The essential files to understand the Caveman token-compression skill are [`README.md`](https://github.com/JuliusBrussee/caveman/blob/main/README.md), [`src/tools/caveman-init.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/tools/caveman-init.js), [`src/rules/caveman-activate.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md), [`src/hooks/caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-activate.js), and [`src/hooks/caveman-stats.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-stats.js), which together handle installation, rule definitions, runtime activation, and telemetry.**

The Caveman project by JuliusBrussee is a token-compression skill for AI coding agents that reduces context window usage by eliminating filler words while preserving technical accuracy. Understanding the key files to understand the Caveman project reveals how it integrates with agents like Cursor, Windsurf, Cline, and Copilot through a combination of installation scripts, markdown rule sets, and runtime hooks. This guide examines the core source files that define the architecture, from the initial setup in [`caveman-init.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-init.js) to the session-start activation logic in [`caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-activate.js).

## Core Installation and Initialization Files

The installation workflow centers on three primary files that handle setup, agent detection, and configuration deployment.

### README.md and INSTALL.md

The **[`README.md`](https://github.com/JuliusBrussee/caveman/blob/main/README.md)** file serves as the primary entry point, providing high-level overview, installation commands, token-saving statistics, and the list of supported agents. It documents the runtime commands (`/caveman`, `/caveman-commit`, etc.) that users invoke during sessions.

The **[`INSTALL.md`](https://github.com/JuliusBrussee/caveman/blob/main/INSTALL.md)** file contains the detailed per-agent installation matrix, documenting flags, dry-run behavior, and uninstall instructions for each supported platform.

### src/tools/caveman-init.js

The **[`caveman-init.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-init.js)** script is the command-line installer that drops the always-on Caveman rule files into a target repository for each supported agent. According to the source code, this script is idempotent and supports `--dry-run` and `--force` options, plus handling for OpenClaw global installation.

To install the skill registry entry and initialize the current repository:

```bash
npx skills add JuliusBrussee/caveman
node src/tools/caveman-init.js .

```

For a dry-run preview without modifying files:

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

```

To force-overwrite existing rules for a specific agent:

```bash
node src/tools/caveman-init.js . --force --only cursor

```

## Runtime Activation and Rule Engine

These files define how the caveman mode activates during agent sessions and governs the compression rules.

### src/rules/caveman-activate.md

The **[`caveman-activate.md`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-activate.md)** file contains the canonical rule set that tells an agent how to "talk like a caveman": which filler words to drop, how to keep technical content unchanged, and the level-switch syntax (`/caveman lite|full|ultra|wenyan`). This file serves as the source of truth that the initializer copies into agent configurations.

### src/hooks/caveman-activate.js

The **[`caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-activate.js)** hook implements the Claude Code *SessionStart* hook executed on every chat start. As implemented in JuliusBrussee/caveman, it writes a flag file (`.caveman-active`), loads the appropriate skill ([`SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/SKILL.md)), filters the intensity table to the selected level, and emits the full ruleset to the model. It also prompts users to configure a status-line badge if missing.

Users activate specific compression levels during sessions using:

```text
/caveman ultra

```

## Command Implementation and Telemetry

The project provides runtime commands for statistics and compression, implemented through dedicated hook files and documentation.

### src/hooks/caveman-stats.js

The **[`caveman-stats.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-stats.js)** file implements the `/caveman-stats` command. It reads the session log, aggregates token savings, and optionally prints a share-ready line showing the reduction impact. This runtime telemetry allows users to verify the token-reduction benefits.

Example output when checking statistics:

```text
/caveman-stats
[CAVEMAN] ⛏ 12.4k tokens saved (≈65% reduction)

```

### commands/*.md and commands/*.toml

The **`commands/`** directory contains human-readable command documentation ([`caveman.md`](https://github.com/JuliusBrussee/caveman/blob/main/caveman.md), [`caveman-init.md`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-init.md), [`caveman-commit.md`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-commit.md), etc.) that is shown to agents via the skill registry. The `.toml` files define the command signatures for the agent runtime, providing structured metadata for the caveman commands.

To compress a local memory file for permanent token savings:

```bash
caveman-compress CLAUDE.md

```

## Middleware and Agent Integration

Caveman extends beyond individual agent configurations through MCP middleware and sub-agent specifications.

### src/mcp-servers/caveman-shrink/*

The **`caveman-shrink`** middleware in `src/mcp-servers/caveman-shrink/` intercepts any tool description from an MCP server and compresses it using the same caveman rules. This is how the skill works for generic agents that rely on an MCP back-end.

### AGENTS.md and plugins/caveman/agents/*.md

The **[`AGENTS.md`](https://github.com/JuliusBrussee/caveman/blob/main/AGENTS.md)** file is the top-level manifest that lists all agents this skill supports and provides a short description for each, used by the Opencode skill registry to expose the Caveman commands.

The **`plugins/caveman/agents/*.md`** files contain markdown specifications for sub-agents (`cavecrew-builder`, `cavecrew-investigator`, `cavecrew-reviewer`), illustrating how the caveman style applies to specific tasks like PR review and code investigation.

## Security and Privacy Guarantees

The **[`SECURITY.md`](https://github.com/JuliusBrussee/caveman/blob/main/SECURITY.md)** file describes the privacy model (no telemetry, no network calls after install) and the threat model for the status-line badge. This documentation is essential for anyone reviewing the safety of the skill.

## Summary

Reviewing these key files to understand the Caveman project provides complete visibility into the architecture:

- **[`README.md`](https://github.com/JuliusBrussee/caveman/blob/main/README.md)** and **[`INSTALL.md`](https://github.com/JuliusBrussee/caveman/blob/main/INSTALL.md)** provide installation guidance and supported agent matrices.
- **[`src/tools/caveman-init.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/tools/caveman-init.js)** handles idempotent installation with dry-run and force options.
- **[`src/rules/caveman-activate.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md)** contains the canonical compression rules and intensity levels.
- **[`src/hooks/caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-activate.js)** manages session-start activation and rule filtering.
- **[`src/hooks/caveman-stats.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-stats.js)** implements token-savings telemetry.
- **`src/mcp-servers/caveman-shrink/`** provides MCP middleware for generic agent support.
- **[`SECURITY.md`](https://github.com/JuliusBrussee/caveman/blob/main/SECURITY.md)** documents the privacy guarantees and threat model.

## Frequently Asked Questions

### What is the purpose of the caveman-init.js script?

The **[`caveman-init.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-init.js)** script installs the Caveman skill into supported AI agents by copying rule files into their configuration directories. It is idempotent, supports `--dry-run` for previewing changes without modifying files, and includes `--force` options for overwriting existing configurations. It also handles OpenClaw global installation.

### How does the caveman-activate.js hook work?

The **[`caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-activate.js)** file is a Claude Code SessionStart hook that runs automatically when a chat session begins. It writes a `.caveman-active` flag file, loads the [`SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/SKILL.md) content, filters the intensity table based on the user's selected level (lite, full, ultra, or wenyan), and emits the complete ruleset to the model.

### Where are the compression rules defined in the Caveman project?

The canonical compression rules are defined in **[`src/rules/caveman-activate.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md)**, which specifies which filler words to remove, how to preserve technical content, and the syntax for switching between intensity levels. This file is copied into agent configurations by the installer and read by the activation hook at runtime.

### How can I check token savings when using Caveman?

Use the **`/caveman-stats`** command, which is implemented in **[`src/hooks/caveman-stats.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-stats.js)**. This command reads the session log, aggregates token savings data, and displays a share-ready summary showing the percentage reduction and total tokens saved.