caveman

Applies a multi-intensity rule engine (Lite/Full/Ultra modes) that surgically removes linguistic filler—articles, hedging phrases, pleasantries—while preserving code blocks, technical terminology, and safety-critical information. Uses a single-source-of-truth SKILL.md configuration file that defines transformation rules across all host environments (Claude Code, Codex, Gemini CLI), achieving ~75% token reduction without sacrificing technical accuracy through a 'Smart Caveman' principle that protects machine-critical data.

Distributes caveman as a portable 'Skill' artifact across heterogeneous AI agent platforms (Claude Code plugin marketplace, Codex CLI, Gemini CLI) using a unified SKILL.md configuration format. Provides platform-specific installation hooks (shell scripts for macOS/Linux/WSL, PowerShell for Windows) that auto-merge configuration into host environment settings (~/.claude/settings.json, Codex config, etc.), enabling single-source-of-truth behavior across all platforms without duplicating rule definitions.

Exposes three discrete compression intensity levels (Lite, Full, Ultra) that users can toggle per session, each applying progressively aggressive linguistic transformation rules. Lite mode removes only obvious filler (articles, some hedging); Full mode aggressively compresses prose while preserving code and technical terms; Ultra mode maximizes compression by removing even more linguistic scaffolding. Implementation uses a rule registry in SKILL.md that maps intensity levels to specific transformation patterns, allowing users to trade off readability vs. token savings without code changes.

Implements a whitelist-based protection mechanism that exempts code blocks (markdown fences), technical terminology (e.g., useMemo, shallow comparison), and safety-critical operations (e.g., rm -rf) from compression rules. Uses pattern matching and AST-aware detection to identify protected regions, ensuring that compression never degrades technical accuracy or introduces ambiguity in destructive commands. This 'Smart Caveman' principle is enforced via explicit rules in SKILL.md that define protected patterns and categories.

Provides a Python-based benchmarking suite (benchmarks/run.py) that measures caveman's token savings, compression ratios, generation speed, and technical accuracy across multiple intensity levels and test prompts. Generates quantitative metrics (e.g., ~75% token savings, ~46% input compression, ~3x speed increase) and supports custom benchmark prompts. Results are published to GitHub Pages documentation, enabling transparent performance tracking and user-facing proof of efficiency gains.

Automatically generates and publishes comprehensive documentation to GitHub Pages via CI/CD pipeline, including installation guides, intensity level explanations, linguistic rules, trigger/command reference, plugin architecture details, and benchmark results. Documentation is derived from SKILL.md and repository metadata, ensuring single-source-of-truth consistency. Provides both human-readable guides and technical deep-dives for developers integrating caveman into custom workflows.

Provides explicit command-based activation mechanism (e.g., /caveman, /caveman lite, /caveman full, /caveman ultra) that users invoke to enable compression for a specific session. Activation is session-scoped (not persistent across Claude Code instances) and can be toggled on/off mid-conversation. Implementation uses Claude Code's command/trigger system to intercept user input and apply caveman rules to model output, without requiring permanent configuration changes.

Implements a declarative rule registry in SKILL.md that defines linguistic transformation patterns (e.g., 'The reason is' → 'Reason:', delete articles 'a'/'an'/'the', remove hedging phrases). Rules are organized by category (grammar, articles, filler, safety-critical) and intensity level (Lite/Full/Ultra), enabling pattern-based text transformation without hardcoded logic. Uses regex or string-matching patterns to identify and replace linguistic elements, with explicit exceptions for code blocks and technical terms.

Implements a GitHub Actions CI/CD workflow that synchronizes SKILL.md configuration changes across all supported platforms (Claude Code, Codex, Gemini CLI) by automatically regenerating platform-specific configuration files and triggering plugin updates. Uses a single-source-of-truth SKILL.md that is parsed and transformed into platform-native formats (plugin.json for Claude Code, config files for Codex/Gemini), ensuring behavior consistency without manual per-platform updates.