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

> Explore JuliusBrussee/caveman implementation details, covering architecture, hooks, and runtime behavior. Discover how this project uses rule files, hooks, and plugins for AI compression.

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

---

**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`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-init.js) CLI tool serves as the entry point for equipping repositories with persistent rules. Located at [`src/tools/caveman-init.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/.windsurf/rules/caveman.md)
- [`.clinerules/caveman.md`](https://github.com/JuliusBrussee/caveman/blob/main/.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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/src/tools/caveman-init.js) | Source of truth for compression rules; copied to all agent rule files |
| **SENTINEL** | [`src/tools/caveman-init.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-mode-tracker.js) | Converts user input to mode identifiers (lite, full, ultra, wenyan, off) |
| **Reinforcement Line** | [`src/plugins/opencode/plugin.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/plugins/opencode/plugin.js) | One-sentence reminder appended to system prompts when active |
| **Intensity Filtering** | [`src/hooks/caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/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:

```bash

# 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`](https://github.com/JuliusBrussee/caveman/blob/main/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:

```bash
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:

```javascript
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`](https://github.com/JuliusBrussee/caveman/blob/main/src/tools/caveman-init.js)** — CLI installer for persistent rule injection across Cursor, Windsurf, Cline, and Copilot
- **[`src/hooks/caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-activate.js)** — Claude Code session hook handling flag files and ruleset streaming
- **[`src/hooks/caveman-config.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-config.js)** — Utility module exporting `getDefaultMode`, `safeWriteFlag`, and `readFlag`
- **[`src/hooks/caveman-mode-tracker.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-mode-tracker.js)** — Core parsing logic for slash commands and natural language mode toggles
- **[`src/plugins/opencode/plugin.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/plugins/opencode/plugin.js)** — ESM plugin providing Opencode platform integration
- **[`src/mcp-servers/caveman-shrink/index.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-init.js)), Claude Code hooks ([`caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-activate.js)), and Opencode plugins ([`plugin.js`](https://github.com/JuliusBrussee/caveman/blob/main/plugin.js)).
- The **RULE_BODY** and **SENTINEL** in [`src/tools/caveman-init.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-config.js).
- **Intensity filtering** in [`caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-activate.js)) runs at session start and processes mode changes through slash commands in the chat interface. The **Opencode plugin** ([`plugin.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-activate.js) parses [`SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/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.