how does this repo work

How caveman works

Caveman is fundamentally a prompt-engineering skill/plugin distribution system for AI coding agents (Claude Code, Codex, Gemini, Cursor, Windsurf, Cline, etc.), not a runtime application in the traditional sense. Here's the shape of it:

1. The core idea: skills as instruction files

The repo ships a set of Markdown "SKILL.md" files that instruct an AI agent how to write more tersely — using caveman-style compressed language (dropped articles, short synonyms, fragments) to cut token usage. For example, skills/caveman-review/SKILL.md shows the compression pattern for code review comments, contrasting verbose phrasing against terse equivalents like L42: 🔴 bug: user can be null after .find(). Add guard before .email. [skills/caveman-review/SKILL.md:L35-L48]. Similarly, skills/caveman-compress/SKILL.md defines the compression rules themselves — using short synonyms, dropping filler phrases like "you should" or "make sure to," while treating fenced code blocks and inline code as strictly read-only regions that must never be altered [skills/caveman-compress/SKILL.md:L66-L89].

There's also a caveman-commit skill that applies the same terse philosophy to commit messages, contrasting a verbose commit description against a properly scoped Conventional Commit message [skills/caveman-commit/SKILL.md:L36-L58].

2. One source of truth, many distribution targets

Per CONTRIBUTING.md, the repo distributes a single skill (caveman) plus sub-skills (caveman-commit, caveman-review, caveman-compress, cavecrew-*) to many different agent ecosystems through different mechanisms — Claude Code plugin, Codex plugin, Gemini extension, and rule files for Cursor/Windsurf/Cline, plus a generic path via npx skills for everything else [CONTRIBUTING.md:L15-L29]. A Node-based installer at bin/install.js detects which agents are present on a user's machine and installs the appropriate variant for each [CONTRIBUTING.md:L15-L29].

Critically, the source of truth lives at the top level of the repo (e.g. skills/caveman-compress/SKILL.md), while agent-specific copies under plugins/caveman/ (e.g. plugins/caveman/skills/caveman-compress/SKILL.md) are rebuilt by CI — direct edits there get reverted [CONTRIBUTING.md:L15-L29]. This explains why the same SKILL.md content appears duplicated in both locations in the retrieved chunks.

3. Measuring the effect: evals

The evals/snapshots/results.json file contains benchmark data comparing a baseline agent, a "terse" prompt-instructed agent, and the actual caveman skill (plus localized variants caveman-cn, caveman-es) answering the same 10 technical prompts (React re-renders, connection pooling, TCP vs UDP, memory leaks, etc.) [evals/snapshots/results.json:L1-L36]. This is how the project substantiates its token-reduction claims — by running the same prompts through different "arms" and comparing output verbosity/token counts, as referenced by the README's benchmark link.

4. Under the hood (per RepoPilot's import graph)

While the skill/prompt files are the user-facing product, the repo also has a real codebase (Go, JS/TS, Python) backing it — the most-depended-on files are engine/safety/safety.go (25 importers), engine/compressors/axtree.go (20 importers), engine/detect.go (19 importers), engine/ccr/sqlite_parent_security_posix.go (19 importers), and cacheengine/doc.go (14 importers). RepoPilot's analysis grades the architecture A (100/100) across 394 parsed files with 199 internal imports and 0 import cycles, suggesting a clean layered structure even though the retrieved chunks above focus mostly on the skill-definition layer rather than this engine code.

If you want, I can dig into what engine/safety/safety.go or engine/compressors/axtree.go actually do, since those are the architectural entry points RepoPilot flags as most central.

FOLLOW_UPS:

• What does engine/safety/safety.go act

The Go files aren't appearing in the search results. Based on what I can see, the most actionable code visible in the repo is actually the prose compression engine, which is what's publicly shipping. Let me explain what that does:

What the actual production code does

The most central code visible is the prose compression engine — a pure-Node compressor in src/mcp-servers/caveman-shrink/compress.js [src/mcp-servers/caveman-shrink/compress.js:L105-L115]. This is the runtime that actually shrinks token usage:

The compression algorithm

It works by:

1. Protected-segment parsing — identifies regions that must never be touched [src/mcp-servers/caveman-shrink/compress.js:L1-L64]:

   • Fenced code blocks (...)
   • Inline code (...)
   • URLs (https?://...)
   • Filesystem paths (anything with / or \)
   • CamelCase / snake_case / dotted.path identifiers
   • Function calls and version numbers

2. Prose compression on everything else — strips:

   • Articles: "a", "an", "the"
   • Fillers: "just", "really", "basically", "actually", "simply", "quite", "very", "essentially", "literally"
   • Pleasantries: "please", "kindly", "thank you", "sure", "certainly", "of course", "happy to"
   • Hedging: "perhaps", "maybe", "might", "could potentially", "would like to", "i think", "in my opinion", "it seems"
   • Leaders: strips "I'll", "I will", "I can", "you can", "we will", "let me", "let's" from sentence starts
   • Whitespace runs → collapsed

3. Sentinel-based nesting — uses regex-based sentinel replacement with up to 8 restore passes to handle nested protected patterns (e.g., a path rule swallows STARTER/BUSINESS, then the function-call rule swallows the resulting sanitized result) [src/mcp-servers/caveman-shrink/compress.js:L1-L64].

The output is { compressed, before, after } — tracking bytes reduced [src/mcp-servers/caveman-shrink/compress.js:L105-L115].

Where it's deployed

This compressor runs in an MCP server (src/mcp-servers/caveman-shrink/index.js) that implements the Model Context Protocol, intercepting tool descriptions and prompt responses to compress them mid-flight. The hook system in bin/install.js patches this into various agent CLIs at installation time [bin/install.js].

Why the Go engine matters (but isn't visible here)

RepoPilot flagged engine/safety/safety.go as the most-depended-on file (25 importers). While I can't retrieve its source directly from the visible chunks, the pattern suggests it's likely responsible for validating what can safely be compressed — detecting code vs. prose, checking for injection risks, ensuring security-sensitive fields aren't mangled. The engine/compressors/axtree.go (20 importers) likely parses accessibility trees from the DOM/UI to understand component structure and context, helping decide which strings are safe to shrink without breaking semantics.

In other words: the Go engine provides safety guarantees so the Node compressor doesn't accidentally break code or introduce bugs, while the Node compressor does the actual token reduction at runtime.

FOLLOW_UPS:

• What are the Intensity levels in caveman SKILL files?
• How does the install.js detector find each agent?
• What MCP protocol does caveman-shrink implement?