What Is the Purpose of the caveman CLI? Token Compression for LLM Coding Assistants

The caveman CLI serves as the entry point for a lightweight token-compression skill that reduces LLM output by roughly 65% while preserving code, URLs, paths, and error messages verbatim.

The caveman CLI is the command-line interface for the JuliusBrussee/caveman open-source project. It provides a drop-in wrapper that integrates with popular AI coding assistants—including Claude Code, Gemini, Cursor, and Codex—to automatically compress verbose model responses into terse, technical prose without sacrificing accuracy or context.

Core Purpose: Activating Token Compression

The primary purpose of the caveman CLI is to activate a "caveman mode" that strips filler words, articles, and redundant phrasing from every model response. According to the benchmark data in the repository’s README, this yields roughly 65% fewer output tokens per reply while maintaining full technical fidelity. The compression layer specifically preserves code blocks, file paths, URLs, and error messages, ensuring that developers receive concise answers without losing actionable information.

Three Primary Functions of the caveman CLI

The CLI architecture divides functionality into three distinct areas: mode activation, utility sub-commands, and agent hook installation.

1. Session Mode Activation and Granularity Control

The CLI activates caveman mode through the /caveman command or by invoking caveman directly in the terminal. Once enabled, the mode persists for the session and supports six granularity levels—including lite, full, ultra, and wenyan—each offering different trade-offs between brevity and readability. These modes are defined in commands/caveman.md and src/plugins/opencode/commands/caveman.md, which provide the slash-command definitions parsed by supported agents.

2. Utility Sub-Commands for Developer Workflows

The CLI provides four specialized commands for common development tasks:

• caveman-commit – Generates terse conventional-commit messages (e.g., feat: add auth middleware).
• caveman-review – Creates one-line PR review comments optimized for clarity.
• `caveman-compress `` – Rewrites markdown or text files in caveman style to reduce future context-window usage.
• caveman-stats – Reports per-session and lifetime token savings, optionally formatting output as a status-line badge.

These binaries are installed to your $PATH by the repository’s installation script and reside in the bin/ directory.

3. Hook Installation for Agent Integration

The CLI installs JavaScript hook scripts that enable seamless integration with agent frameworks like Claude Code and OpenClaw. Key files include:

• src/hooks/caveman-activate.js – Writes the initial activation flag file (e.g., ~/.claude/.caveman-active) on session start.
• src/hooks/caveman-mode-tracker.js – Monitors mode-switching commands during a session and updates the flag file accordingly.
• src/hooks/caveman-stats.js – Calculates token savings by reading session logs and updates the status badge.

These hooks ensure compression applies from the very first turn of a conversation by writing persistent flag files that the agent reads before generating responses.

Installation and Quick Start

Install the CLI using the single-command installer, which works on macOS, Linux, WSL, and Git Bash:

curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash

Activate the default full compression mode:

caveman

Switch to a lighter mode for approximately 30% token reduction:

caveman lite

Generate a compressed commit message for staged changes:

caveman-commit

Technical Implementation

The CLI entry point lives in src/tools/caveman-init.js, which parses arguments and dispatches to the appropriate sub-command or hook routine. When you invoke caveman, the script checks for existing activation flags in agent-specific directories (such as ~/.claude/) and initializes the compression layer by writing the necessary state files. This architecture allows the CLI to function as a stateless wrapper that requires no background daemon or persistent server process.

Summary

• The caveman CLI is the command-line interface for a token-compression skill that reduces LLM output by approximately 65%.
• It provides six granularity levels (lite, full, ultra, wenyan, etc.) to control compression intensity.
• Four utility commands (caveman-commit, caveman-review, caveman-compress, caveman-stats) streamline common developer workflows.
• JavaScript hooks (caveman-activate.js, caveman-mode-tracker.js, caveman-stats.js) integrate with Claude Code and OpenClaw by writing persistent flag files.
• The CLI preserves code blocks, URLs, paths, and error messages verbatim while removing filler words and articles.

Frequently Asked Questions

What coding assistants support the caveman CLI?

The caveman CLI officially supports Claude Code, Gemini, Cursor, Codex, and OpenClaw. The hook scripts in src/hooks/ write activation flags to agent-specific directories (such as ~/.claude/.caveman-active), allowing the compression layer to work with any assistant that reads external state files before generating responses.

How much token reduction can I expect with caveman modes?

Benchmark data in the JuliusBrussee/caveman repository shows that the full mode reduces output tokens by roughly 65%, while the lite mode achieves approximately 30% reduction. The ultra and wenyan modes offer even more aggressive compression for users who prioritize minimal token usage.

Will caveman compression affect my code snippets or error messages?

No. The compression algorithm specifically preserves code blocks, file paths, URLs, and error messages verbatim. It targets only natural language filler words, articles, and redundant phrasing, ensuring that technical content remains unchanged and copy-pasteable.

Where does the caveman CLI store its activation state?

The CLI stores session state in flag files located in agent-specific directories (e.g., ~/.claude/.caveman-active). The src/hooks/caveman-activate.js script creates these files on startup, while src/hooks/caveman-mode-tracker.js updates them when you switch between modes like lite or ultra.

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