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

The essential files to understand the Caveman token-compression skill are README.md, src/tools/caveman-init.js, src/rules/caveman-activate.md, src/hooks/caveman-activate.js, and 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 to the session-start activation logic in 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 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 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 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:

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

For a dry-run preview without modifying files:

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

To force-overwrite existing rules for a specific agent:

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 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 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), 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:

/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 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:

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

commands/.md and commands/.toml

The commands/ directory contains human-readable command documentation (caveman.md, caveman-init.md, 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:

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 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 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 and INSTALL.md provide installation guidance and supported agent matrices.
• src/tools/caveman-init.js handles idempotent installation with dry-run and force options.
• src/rules/caveman-activate.md contains the canonical compression rules and intensity levels.
• src/hooks/caveman-activate.js manages session-start activation and rule filtering.
• src/hooks/caveman-stats.js implements token-savings telemetry.
• src/mcp-servers/caveman-shrink/ provides MCP middleware for generic agent support.
• 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 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 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 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, 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. This command reads the session log, aggregates token savings data, and displays a share-ready summary showing the percentage reduction and total tokens saved.

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