# Main Features of Caveman: Token-Saving Skill for AI Coding Agents

> Discover Caveman, the AI coding agent skill that cuts output tokens by 65%. Learn about its compression, developer commands, and middleware features to save AI costs.

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

---

**Caveman is a universal AI-coding agent skill that reduces output tokens by approximately 65% through configurable compression levels, specialized developer commands, and middleware integration.**

Caveman is a lightweight plugin developed by JuliusBrussee that integrates with Claude Code, Codex, Gemini, Cursor, and over 30 other AI-coding agents. The main features of Caveman focus on shrinking textual output while preserving exact code blocks, commands, and error messages. This open-source tool deploys as plain-text skill files that require no core modifications to the host agent.

## Configurable Compression Intensity

### The Caveman Intensity Switch

The `/caveman` command defined in [`commands/caveman.md`](https://github.com/JuliusBrussee/caveman/blob/main/commands/caveman.md) offers four compression levels that control how aggressively the agent trims its responses:

- **`lite`** – Removes filler words and articles only
- **`full`** – Default aggressive compression (balanced readability)
- **`ultra`** – Reduces output to bare essentials (nouns and verbs only)
- **`wenyan`** – Renders responses in classical Chinese for maximal brevity

```text
/caveman ultra

```

Activating `ultra` mode transforms verbose explanations into terse technical fragments (e.g., "New ref/render. `useMemo` it.") while preserving all functional code.

## Developer Workflow Commands

### Conventional Commit Generation

The `/caveman-commit` command implemented in [`commands/caveman-commit.md`](https://github.com/JuliusBrussee/caveman/blob/main/commands/caveman-commit.md) generates terse commit messages following the Conventional Commits specification. The output maintains a subject line of ≤50 characters using imperative mood and "why-over-what" style.

```text
/caveman-commit

```

**Result:**

```

feat: add user login flow

```

### One-Line Code Review

Defined in [`commands/caveman-review.md`](https://github.com/JuliusBrussee/caveman/blob/main/commands/caveman-review.md), this command produces compact, line-oriented PR comments that pinpoint issues without narrative overhead.

```text
/caveman-review

```

**Result:**

```

L42: 🔴 bug: user null. Add guard.

```

### Session Statistics Tracking

The `/caveman-stats` command tracks lifetime token savings and cost reductions. As implemented in [`commands/caveman-stats.md`](https://github.com/JuliusBrussee/caveman/blob/main/commands/caveman-stats.md) and [`bin/lib/opencode-agent.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/lib/opencode-agent.js), it parses session logs to calculate efficiency metrics and displays a status-line badge.

```text
/caveman-stats --share

```

**Result:**

```

[⛏ 12.4k] Saved 65% output tokens, $0.24 saved. → tweet

```

The `--share` flag exports a tweet-ready summary of your savings.

## Persistent File Optimization

### Permanent File Compression

The `/caveman-compress` CLI command in [`commands/caveman-compress.md`](https://github.com/JuliusBrussee/caveman/blob/main/commands/caveman-compress.md) performs one-time transformations of memory files (such as [`CLAUDE.md`](https://github.com/JuliusBrussee/caveman/blob/main/CLAUDE.md) or [`docs/HONEST-NUMBERS.md`](https://github.com/JuliusBrussee/caveman/blob/main/docs/HONEST-NUMBERS.md)). This reduces the file's token footprint by approximately 46% permanently, benefiting all future sessions that reference the file.

```text
/caveman-compress docs/HONEST-NUMBERS.md

```

Unlike session-based compression, this modifies the source file directly, rewriting it in caveman-speak for lasting efficiency gains.

## MCP Middleware Integration

### Universal Server Wrapping

The `caveman-shrink` npm package provides middleware that wraps any MCP-compatible server, automatically compressing tool descriptions and payload metadata without modifying the underlying server code.

```bash
npm i caveman-shrink

```

```javascript
import { cavemanShrink } from 'caveman-shrink';
const server = createMCPServer(...);
cavemanShrink(server);   // all tool descriptions are now compressed

```

This extends Caveman's token-saving logic beyond individual prompts to entire MCP server ecosystems.

## Cavecrew Sub-Agents

Located in `plugins/caveman/agents/`, the Cavecrew suite provides specialized agents that inherit the compression behavior for targeted workflows:

- **`cavecrew-investigator`** – Debugging and analysis with compressed output
- **`cavecrew-builder`** – Code generation with ~60% fewer tokens than vanilla agents
- **`cavecrew-reviewer`** – Automated review processes in caveman style

```text
/cavecrew-builder <your-prompt>

```

These sub-agents maintain the same compression intensity while offering specialized system prompts for distinct development phases.

## Cross-Agent Installation

### Automated Deployment

The [`install.sh`](https://github.com/JuliusBrussee/caveman/blob/main/install.sh) (and `install.ps1` for Windows) scripts detect all supported AI agents installed on the host system and automatically deploy the appropriate skill files to each agent's configuration directory. This enables immediate use across heterogeneous development environments without manual file copying.

## Architectural Implementation

### Skill-as-Prompt Design

The core compression logic resides in [`plugins/caveman/skills/caveman-stats/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/plugins/caveman/skills/caveman-stats/SKILL.md) and related skill files. These templates instruct the host LLM to "drop filler, keep technical terms, preserve code verbatim," effectively treating the compression strategy as a prompt engineering layer rather than a post-processing filter.

### Flag-Based Activation System

The [`src/rules/caveman-openclaw-bootstrap.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-openclaw-bootstrap.md) hook implements automatic activation by creating a hidden `CAVEMAN_FLAG` file at session initialization. This ensures compression engages from the very first reply on Claude Code, Codex, or Gemini without requiring an explicit `/caveman` command.

## Summary

- **Caveman achieves ~65% token reduction** through four compression intensity levels (`lite`, `full`, `ultra`, `wenyan`) controlled via [`commands/caveman.md`](https://github.com/JuliusBrussee/caveman/blob/main/commands/caveman.md)
- **Workflow automation** via `/caveman-commit`, `/caveman-review`, and `/caveman-stats` streamlines development tasks while minimizing verbosity
- **Persistent optimization** through `/caveman-compress` permanently reduces memory file sizes by ~46%
- **MCP middleware support** via the `caveman-shrink` npm package extends functionality to any MCP-compatible server
- **Specialized sub-agents** in `plugins/caveman/agents/` provide targeted workflows with inherited compression logic
- **Zero-configuration deployment** through [`install.sh`](https://github.com/JuliusBrussee/caveman/blob/main/install.sh) supports 30+ AI coding agents with automatic detection

## Frequently Asked Questions

### What AI agents are compatible with Caveman?

Caveman supports Claude Code, Codex, Gemini, Cursor, Windsurf, Cline, Copilot, and more than 30 other AI-coding agents. The [`install.sh`](https://github.com/JuliusBrussee/caveman/blob/main/install.sh) script automatically detects installed agents on your system and deploys the appropriate skill files to each agent's plugin directory.

### How does Caveman achieve 65% token reduction without losing code accuracy?

The tool uses a "skill-as-prompt" architecture where compression instructions in [`plugins/caveman/skills/caveman-stats/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/plugins/caveman/skills/caveman-stats/SKILL.md) tell the host LLM to eliminate filler words while strictly preserving code blocks, shell commands, and error messages. This happens at the generation layer rather than through post-processing, ensuring functional integrity.

### Can I use Caveman with MCP servers that I don't control?

Yes. The `caveman-shrink` npm package provides middleware that wraps any MCP-compatible server, automatically compressing tool descriptions and payloads. You can wrap existing servers without modifying their source code or configuration.

### Does Caveman require manual activation for every new session?

No. The [`src/rules/caveman-openclaw-bootstrap.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-openclaw-bootstrap.md) hook creates a `CAVEMAN_FLAG` file at session start that automatically activates caveman mode from the first reply. This eliminates the need to type `/caveman` at the beginning of each conversation on supported agents.