# Caveman Skill vs Engine/Proxy: Understanding the Architecture

> Understand the Caveman skill vs Engine Proxy difference. Caveman instructs LLM terse style. Engine Proxy compresses byte payloads. Learn how they work.

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

---

**The Caveman skill is a static, model-side instruction that instructs the LLM to speak in terse "caveman" style, while the Engine/Proxy is a standalone Go service that programmatically compresses arbitrary byte payloads before they reach the model.**

The JuliusBrussee/caveman repository provides two complementary mechanisms for token optimization: a behavioral skill that alters how the model generates responses, and a compression engine that transforms external data flowing through the system. While both reduce token consumption, they operate at fundamentally different architectural layers—one inside the model's context window and one outside as a standalone service.

## Architectural Overview

Understanding the distinction begins with recognizing where each component executes relative to the large language model.

### The Caveman Skill: Model-Side Behavior Control

The Caveman skill is a **declarative markdown file** ([`skills/caveman/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/SKILL.md)) that the Caveman dispatcher injects as a system-prompt style instruction at conversation start. When activated via the `/caveman` slash command, the skill instructs the LLM to drop filler words, articles, and emojis while preserving technical accuracy. This execution happens entirely **inside the model**—the LLM itself interprets the rules and generates the final terse output.

Because the skill is pure configuration with no runtime logic, it is completely **stateless**. It influences only the model's language generation, leaving code blocks, error messages, and JSON payloads untouched. The skill remains active for the entire conversation until explicitly disabled, affecting every response the model produces.

### The Engine and Proxy: Runtime Compression Service

The Engine (`caveman-engine`) and its companion Proxy (`caveman-proxy`) constitute a **compiled Go service** that runs outside the model's execution environment. Implemented across [`engine/engine.go`](https://github.com/JuliusBrussee/caveman/blob/main/engine/engine.go) and [`proxy/protocol.go`](https://github.com/JuliusBrussee/caveman/blob/main/proxy/protocol.go), this system programmatically analyzes, compresses, and recovers arbitrary byte payloads—including prompts, tool results, and memory records—before they reach the model.

Unlike the skill, the engine is **stateful**: when performing lossy compression, it writes the original uncompressed bytes to a CCR (Compressed Content Recovery) store, typically SQLite-backed via `engine/ccr`, and returns a recovery handle. The proxy exposes these capabilities via a JSON-RPC/STDIO interface defined in [`proxy/CLAUDE.md`](https://github.com/JuliusBrussee/caveman/blob/main/proxy/CLAUDE.md), allowing any client (CLI tools, MCP agents, or external services) to invoke compression without embedding the engine library directly.

## Key Differences

**Execution Location**
The skill runs inside the model's context as a behavioral instruction, while the engine runs as an external binary that preprocesses payloads.

**Scope of Effect**
The Caveman skill affects **only linguistic output**—it rewrites sentences but never modifies structured data. The engine compresses **any byte payload**, including logs, JSON tool outputs, and non-text files.

**State Management**
The skill is stateless with no persistence mechanism. The engine maintains state through the CCR store, enabling exact reconstruction of original data via the `Retrieve` method in [`engine/engine.go`](https://github.com/JuliusBrussee/caveman/blob/main/engine/engine.go).

**Implementation Type**
The skill is a static markdown file requiring no compilation. The engine is native Go code with a registry of compressors in [`engine/compressors/registry.go`](https://github.com/JuliusBrussee/caveman/blob/main/engine/compressors/registry.go) that must be compiled into the binary.

## Implementation Details

### Skill Implementation

The skill definition resides at [`skills/caveman/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/SKILL.md), which describes intensity levels, persistence rules, and stylistic constraints. The dispatcher parses this file and inserts its contents into the system prompt. No compiled code or runtime state exists—the model simply follows the behavioral rules described in the markdown.

### Engine Implementation

The core compression logic lives in [`engine/engine.go`](https://github.com/JuliusBrussee/caveman/blob/main/engine/engine.go), which exposes four primary methods: `Compress`, `Simulate`, `Retrieve`, and `Stats`. The engine routes payloads through appropriate compressors located in `engine/compressors/*`, each targeting specific data formats like JSON or markdown. Safety checks determine whether compression is safe, and the CCR subsystem handles recovery data storage. The proxy wraps this functionality in [`proxy/protocol.go`](https://github.com/JuliusBrussee/caveman/blob/main/proxy/protocol.go), exposing it via JSON-RPC over stdio.

## Practical Usage Examples

### Activating the Caveman Skill

Use the CLI to install and activate the behavioral skill:

```bash

# Install the skill (once)

caveman tools skills install caveman

# Activate for current session

caveman wrap --caveman full

```

This injects [`skills/caveman/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/SKILL.md) into the system prompt, causing the model to respond in the terse caveman style for the duration of the conversation.

### Calling the Compression Engine from Go

Programmatically compress payloads using the Go SDK:

```go
package main

import (
    "fmt"
    "github.com/JuliusBrussee/caveman/engine"
    "github.com/JuliusBrussee/caveman/engine/ccr"
)

func main() {
    // Initialize CCR store (nil disables lossy compression)
    store, _ := ccr.Open("./recovery.db")
    eng := engine.New(store, nil)

    input := []byte("Connection pooling reuses open DB connections.")
    res, err := eng.Compress(input, engine.Options{Mode: engine.ModeFull})
    if err != nil {
        panic(err)
    }

    fmt.Printf("Saved %.1f%% (%d → %d tokens)\n", 
        res.Ratio*100, res.TokensBefore, res.TokensAfter)
}

```

The `Compress` method in [`engine/engine.go`](https://github.com/JuliusBrussee/caveman/blob/main/engine/engine.go) automatically selects the optimal compressor and returns a recovery handle if CCR is enabled.

### Using the Proxy Interface

Start the proxy and compress data via JSON-RPC:

```bash

# Launch the proxy (starts caveman-engine internally)

caveman start

# Compress via stdin

echo "Technical documentation content..." | caveman compress

```

The proxy forwards the request to the engine's `Compress` method and returns the optimized payload, making the service accessible to non-Go clients.

## When to Use Which

**Choose the Caveman skill** when you want the model itself to generate concise, direct language without filler words. This reduces the token count of the model's natural language responses but preserves all technical content exactly as generated.

**Choose the Engine/Proxy** when you need to compress incoming context, tool outputs, or memory records before they enter the model's context window. This is essential for reducing input tokens in high-volume data scenarios or when storing conversation history.

## Summary

- The **Caveman skill** is a static markdown instruction ([`skills/caveman/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/SKILL.md)) that runs inside the model and modifies linguistic output style only.
- The **Engine** is a compiled Go binary ([`engine/engine.go`](https://github.com/JuliusBrussee/caveman/blob/main/engine/engine.go)) that runs outside the model and performs algorithmic compression on arbitrary byte payloads.
- The **Proxy** exposes the engine via JSON-RPC/STDIO ([`proxy/protocol.go`](https://github.com/JuliusBrussee/caveman/blob/main/proxy/protocol.go)), enabling external services to compress data without direct library integration.
- The skill is **stateless** and behavioral; the engine is **stateful** with CCR-backed recovery capabilities.
- The skill is triggered by slash commands; the engine is invoked programmatically through its API or CLI.

## Frequently Asked Questions

### Can I use the Caveman skill and Engine together?

Yes. The skill reduces the token count of the model's generated responses, while the engine compresses the input payloads and context data fed into the model. According to the JuliusBrussee/caveman source code, they serve complementary purposes and can be activated simultaneously via the CLI's `wrap` command with appropriate flags.

### Does the Engine modify the model's behavior?

No. The Engine only transforms data payloads before they reach the model or after they are returned. It never influences how the model generates text. The Caveman skill, conversely, directly influences the model's output style by modifying the system prompt.

### What happens if the Engine fails to compress data?

The Engine is designed to be **fail-closed**. If a compressor cannot parse the input or compression would not reduce token count, the engine passes the original data through unchanged with no CCR handle. This behavior ensures that data integrity is never compromised by failed compression attempts.

### Is the Caveman skill available for custom LLM providers?

The skill is provider-agnostic because it is implemented as a markdown instruction file ([`skills/caveman/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/SKILL.md)) that any dispatcher can inject into a system prompt. As long as the LLM supports system prompts and can follow behavioral instructions, the Caveman skill will function correctly.