# What Is the Purpose of the caveman CLI? Token Compression for LLM Coding Assistants > Discover the caveman CLI, a tool that compresses LLM output by 65% for coding assistants, preserving essential code and text - Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman) - Tags: how-to-guide - Published: 2026-07-04 --- **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`](https://github.com/JuliusBrussee/caveman/blob/main/commands/caveman.md) and [`src/plugins/opencode/commands/caveman.md`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-mode-tracker.js) – Monitors mode-switching commands during a session and updates the flag file accordingly. - [`src/hooks/caveman-stats.js`](https://github.com/JuliusBrussee/caveman/blob/main/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: ```bash curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash ``` Activate the default `full` compression mode: ```bash caveman ``` Switch to a lighter mode for approximately 30% token reduction: ```bash caveman lite ``` Generate a compressed commit message for staged changes: ```bash caveman-commit ``` ## Technical Implementation The CLI entry point lives in [`src/tools/caveman-init.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-activate.js), [`caveman-mode-tracker.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-mode-tracker.js), [`caveman-stats.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-activate.js) script creates these files on startup, while [`src/hooks/caveman-mode-tracker.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-mode-tracker.js) updates them when you switch between modes like `lite` or `ultra`.