repository·main·Indexed 13 days ago
https://github.com/juliusbrussee/cavemanA skill and plugin for AI coding agents (such as Claude Code, Cursor, and Gemini) that compresses prose output to reduce token usage by up to 65% while maintaining 100% technical accuracy for code and commands. It includes tools for session-based compression levels (lite, full, ultra, wenyan), input token optimization via /caveman-compress, and specialized cavecrew subagents for context management.
Caveman does not use telemetry, analytics, accounts, or a backend. It does not 'phone home'.
/caveman-stats reads logs already existing on your local disk.caveman is a compression mode for LLM responses designed to reduce token usage while preserving technical accuracy. It transforms model responses into "caveman-style" prose by removing articles, filler, pleasantries, and hedging, while keeping technical details, code blocks, error strings, and symbols exact.
Measured to cut approximately 65% of output tokens, the mode persists for the entire session until explicitly stopped or changed.
Auto-clarity rule: The system automatically reverts to normal prose for critical information such as security warnings, irreversible-action confirmations, or complex multi-step sequences to prevent ambiguity. It also reverts if the user repeats a question.
Caveman mode is designed for chat interactions. It does not persist outside of the chat context. When writing the following, the system will use normal prose:
/caveman-compress is explicitly used)To revert to normal prose within a session, use stop caveman or normal mode.
Caveman reduces token usage by instructing agents to drop filler, keep substance, and use fragments, while strictly preserving code, commands, and errors.
Core Workflow & Commands:
/caveman-stats: Reads your session log to count tokens saved and displays the number in your statusline./caveman-compress: Rewrites memory files (such as CLAUDE.md) to ensure future sessions start with a smaller context, saving tokens long-term.To decide whether to enable caveman, use this heuristic:
When running /caveman-stats, the output follows this format:
Session: 47 turns
Input: 12,304 tokens
Output: 3,891 tokens (caveman)
Baseline: 11,247 tokens (estimated without caveman)
Saved: 7,356 tokens (~65%)
Est. rule overhead: 58,750 (input, ~1,250/turn over 47 turns)
Est. net: -51,394 (caveman cost more than it saved for this workload — consider turning it off)⛏ 12.4k) as a glanceable summary./caveman-stats command: Provides the net picture, accounting for the input token overhead required to run the caveman rules.To prevent technical errors or safety risks, caveman mode will automatically drop its compression and switch to normal prose (Auto-Clarity) during:
"migrate table drop column backup first").Once the critical or ambiguous part is handled, the model will resume caveman mode.
When generating commit messages via caveman-commit, adhere to these structural rules:
Format: <type>(<scope>): <imperative summary>
feat, fix, refactor, perf, docs, test, chore, build, ci, style, revert.add, fix, remove) instead of past tense (added) or present continuous (adding).Only include a body if the subject is not self-explanatory. Use a body for:
Body Formatting:
- for bullets (do not use *).Closes #42 or Refs #17.Co-authored-by instead) or AI attribution like "Generated with Claude Code" (unless specifically requested via an Assisted-by trailer).<scope> already covers them.feat(api): add GET /users/:id/profile
Mobile client needs profile data without the full user payload
to reduce LTE bandwidth on cold-launch screens.
Closes #128Caveman mode follows specific rules regarding when it is applied and when it is automatically suspended to ensure safety and clarity.
The system will automatically drop Caveman mode and revert to normal prose in the following scenarios:
Even when Caveman mode is active, certain technical outputs are exempt and will always use normal prose:
Caveman is a system-prompt skill designed to make models write shorter output. It does not compress your input, context, files, or the model's thinking tokens.
SKILL.md rules and skill-list entries into the context./caveman-compress on memory files can result in an average input reduction of ~46% for those specific files.When caveman mode is active, the following communication constraints apply to ensure technical accuracy and token efficiency:
a, an, the (except in lite mode).just, really, basically, actually, simply.sure, certainly, of course, happy to.→).fix instead of implement a solution for).not, never, no, only, or except as this flips meaning.DB, API, HTTP) are allowed. Do not invent new abbreviations (e.g., cfg, impl, req, res, fn) because they do not save tokens under most tokenizers and reduce clarity.Fire tool calls directly. Do not announce the next call. Text before a call should only be used to clarify, warn about security/irreversible actions, or resolve ambiguity.
The caveman-compress skill operates within strict boundaries to prevent corruption of functional code or configuration files.
Only natural language files are eligible for compression:
.md (Markdown).txt (Text).typ / .typst (Typst).tex (LaTeX)The following file types are strictly excluded from compression:
.py, .js, .ts (Code).json, .yaml, .yml, .toml (Data/Config).env, .lock (Environment/Lockfiles).css, .html, .xml, .sql, .sh (Web/Database/Shell)If a file contains both prose and code (e.g., a Markdown file with code blocks), the tool treats code blocks as read-only regions. It will compress only the prose sections and will not modify spacing, comments, or line order within code blocks.