Caveman Project Implementation Details: Architecture, Hooks, and Runtime Behavior

The Caveman project implements a multi-layered compression skill that injects terse "caveman-speak" rules into AI coding agents through persistent rule files, runtime hooks, and platform-specific plugins.

Caveman is an open-source skill developed by Julius Brussee that compresses AI agent output while preserving technical accuracy. The implementation spans CLI tools, Claude Code hooks, and an Opencode plugin, all designed to enforce consistent brevity across supported platforms. Understanding these implementation details for the caveman project reveals how the system maintains state, injects prompts, and filters content by intensity level.

Core Architecture Layers

The codebase is organized into three distinct layers that handle installation, activation, and runtime behavior.

Installation and Rule Injection

The caveman-init.js CLI tool serves as the entry point for equipping repositories with persistent rules. Located at src/tools/caveman-init.js, this script injects the RULE_BODY—the canonical description of caveman style—into IDE-specific rule directories.

The tool creates rule files such as:

• .cursor/rules/caveman.mdc
• .windsurf/rules/caveman.md
• .clinerules/caveman.md

Each file contains the rule body plus front-matter headers that instruct the agent to apply the rules persistently. The script uses a SENTINEL string ("Respond terse like smart caveman") to detect existing installations and prevent duplicate rule injection.

Runtime Hook for Claude Code

The src/hooks/caveman-activate.js file implements the session-start hook for Claude Code. This script performs two critical functions on every session initialization:

1. Flag File Management: Writes a .caveman-active file to $CLAUDE_CONFIG_DIR/ to persist the current mode across conversation turns
2. Ruleset Injection: Streams the filtered caveman ruleset (based on selected intensity) into the session's hidden system context

The hook parses SKILL.md to extract intensity levels (lite, full, ultra, wenyan) and filters the ruleset accordingly before injection.

Opencode Plugin Integration

For Opencode platform support, src/plugins/opencode/plugin.js provides equivalent functionality through an ESM plugin architecture. The plugin tracks the mode flag via safeWriteFlag, implements the parseModeChange function to interpret slash commands (/caveman ultra) and natural language toggles ("talk like caveman"), and injects a reinforcement line into every system prompt via reinforcementLine(mode).

Key Technical Components

Understanding the caveman project requires familiarity with these specific implementation elements:

Component	Implementation Location	Purpose
RULE_BODY	src/tools/caveman-init.js	Source of truth for compression rules; copied to all agent rule files
SENTINEL	src/tools/caveman-init.js	Detection string for existing installations
Flag File	.caveman-active	Persists mode state across sessions; read by status-line indicators
Mode Parser	src/hooks/caveman-mode-tracker.js	Converts user input to mode identifiers (lite, full, ultra, wenyan, off)
Reinforcement Line	src/plugins/opencode/plugin.js	One-sentence reminder appended to system prompts when active
Intensity Filtering	src/hooks/caveman-activate.js	Selects rule subsets based on chosen compression level

Practical Implementation Examples

Installing Rule Files

To equip a repository with persistent caveman rules across all supported agents:

# From the repository root

node src/tools/caveman-init.js .

This creates agent-specific rule files containing the filtered RULE_BODY and sentinel markers for duplicate detection.

Activating Modes in Claude Code

Runtime mode switching occurs through chat commands processed by caveman-activate.js:

/caveman ultra        # Maximum compression

/caveman lite         # Minimal compression

/caveman off          # Disable compression

The hook writes the selection to $CLAUD_CONFIG_DIR/.caveman-active and injects the corresponding filtered ruleset into the hidden context.

Implementing the Opencode Plugin

Install the plugin globally:

npm install -g @juliusbrussee/caveman

The plugin automatically:

• Writes the flag file to ~/.config/opencode/.caveman-active
• Parses mode changes via parseModeChange
• Appends reinforcement lines to every system prompt

Querying Mode Programmatically

Access the current mode from the flag file using the config utility:

import { readFlag } from './src/hooks/caveman-config.js';

const flagPath = '/home/you/.config/opencode/.caveman-active';
const currentMode = readFlag(flagPath);
console.log('Caveman mode is:', currentMode);

Source File Reference Guide

These files contain the core implementation details for the caveman project:

• src/tools/caveman-init.js — CLI installer for persistent rule injection across Cursor, Windsurf, Cline, and Copilot
• src/hooks/caveman-activate.js — Claude Code session hook handling flag files and ruleset streaming
• src/hooks/caveman-config.js — Utility module exporting getDefaultMode, safeWriteFlag, and readFlag
• src/hooks/caveman-mode-tracker.js — Core parsing logic for slash commands and natural language mode toggles
• src/plugins/opencode/plugin.js — ESM plugin providing Opencode platform integration
• src/mcp-servers/caveman-shrink/index.js — MCP server wrapper for compressing tool server descriptions

Summary

• Caveman compresses AI agent output through a three-layer architecture: installation CLI (caveman-init.js), Claude Code hooks (caveman-activate.js), and Opencode plugins (plugin.js).
• The RULE_BODY and SENTINEL in src/tools/caveman-init.js provide the single source of truth for compression rules and installation detection.
• Mode persistence relies on the .caveman-active flag file, written by safeWriteFlag and read by readFlag in src/hooks/caveman-config.js.
• Intensity filtering in caveman-activate.js selects appropriate rule subsets (lite, full, ultra, wenyan) at session start.
• The reinforcement line mechanism ensures continuous application of compression rules throughout the conversation.

Frequently Asked Questions

How does Caveman detect if rules are already installed?

The caveman-init.js script searches for the SENTINEL string ("Respond terse like smart caveman") in existing rule files. If found, the script skips installation for that agent to prevent duplicate rule injection.

Where is the current mode stored during a session?

The active mode persists in a flag file (.caveman-active) written to the platform's configuration directory. For Claude Code, this is $CLAUDE_CONFIG_DIR/.caveman-active; for Opencode, ~/.config/opencode/.caveman-active. The readFlag utility in src/hooks/caveman-config.js provides programmatic access to this state.

What is the difference between the Claude Code hook and the Opencode plugin?

The Claude Code hook (caveman-activate.js) runs at session start and processes mode changes through slash commands in the chat interface. The Opencode plugin (plugin.js) provides equivalent functionality as an ESM module that integrates with the Opencode platform's plugin architecture, handling both slash commands and natural language triggers.

How does intensity filtering work?

When activating a mode, caveman-activate.js parses SKILL.md to extract the intensity table, then filters the complete ruleset to include only instructions relevant to the selected level (lite, full, ultra, or wenyan). This filtered subset is then injected into the system prompt, ensuring the agent receives only the compression rules appropriate for the desired intensity.

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