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

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

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

/caveman-commit

Result:

feat: add user login flow

One-Line Code Review

Defined in commands/caveman-review.md, this command produces compact, line-oriented PR comments that pinpoint issues without narrative overhead.

/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 and bin/lib/opencode-agent.js, it parses session logs to calculate efficiency metrics and displays a status-line badge.

/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 performs one-time transformations of memory files (such as CLAUDE.md or docs/HONEST-NUMBERS.md). This reduces the file's token footprint by approximately 46% permanently, benefiting all future sessions that reference the file.

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

npm i caveman-shrink

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

/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 (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 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 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
• 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 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 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 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 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.

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