External/caveman
1
0
Fork 0
mirror of https://github.com/JuliusBrussee/caveman.git synced 2026-08-11 13:21:09 +02:00
Code Issues Packages Projects Releases Wiki Activity

Update README: restructure and add compress

Browse Source 
Rework README layout and copy: reorder navbar links, rename sections (Levels, 文言文), simplify intensity triggers, and tighten many examples/phrasing. Add caveman-compress docs and compression benchmarks (file-savings table), move/reinsert API benchmark table, and replace long "Why/How" prose with concise benefits and visuals. Misc fixes: Wenyan wording, CLAUDE.md compress examples, and various formatting cleanup for clarity and token-efficiency.
This commit is contained in:
Julius Brussee
2026-04-09 01:22:31 +02:00
parent 6f6772ab1b
commit fecea29b1f
1 changed files with 72 additions and 177 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+72 -177
View File
@@ -15,14 +15,12 @@
</p>
<p align="center">
<a href="#install">Install</a> •
<a href="#benchmarks">Benchmarks</a> •
<a href="#before--after">Before/After</a> •
<a href="#intensity-levels">Intensity Levels</a> •
<a href="#install">Install</a> •
<a href="#intensity-levels">Levels</a> •
<a href="#caveman-skills">Skills</a> •
<a href="#caveman-compress">Compress</a> •
<a href="#evals">Evals</a> •
<a href="#why">Why</a>
<a href="#benchmarks">Benchmarks</a> •
<a href="#evals">Evals</a>
</p>
---
@@ -70,7 +68,7 @@ Based on the viral observation that caveman-speak dramatically reduces LLM token
**Same fix. 75% less word. Brain still big.**
**Sometimes too much caveman. Sometimes not enough:**
**Pick your level of grunt:**
<table>
<tr>
@@ -97,9 +95,9 @@ Based on the viral observation that caveman-speak dramatically reduces LLM token
</td>
<td width="25%">
#### 📜 Wenyan-Full
#### 📜 文言文
> "物出新參照，致重繪。useMemo .Wrap之。"
> "物出新參照，致重繪。useMemo Wrap之。"
</td>
</tr>
@@ -107,34 +105,20 @@ Based on the viral observation that caveman-speak dramatically reduces LLM token
**Same answer. You pick how many word.**
## Benchmarks
```
┌─────────────────────────────────────┐
│ TOKENS SAVED ████████ 75% │
│ TECHNICAL ACCURACY ████████ 100%│
│ SPEED INCREASE ████████ ~3x │
│ VIBES ████████ OOG │
└─────────────────────────────────────┘
```
Real token counts from the Claude API ([reproduce it yourself](benchmarks/)):
<!-- BENCHMARK-TABLE-START -->
| Task | Normal (tokens) | Caveman (tokens) | Saved |
|------|---------------:|----------------:|------:|
| Explain React re-render bug | 1180 | 159 | 87% |
| Fix auth middleware token expiry | 704 | 121 | 83% |
| Set up PostgreSQL connection pool | 2347 | 380 | 84% |
| Explain git rebase vs merge | 702 | 292 | 58% |
| Refactor callback to async/await | 387 | 301 | 22% |
| Architecture: microservices vs monolith | 446 | 310 | 30% |
| Review PR for security issues | 678 | 398 | 41% |
| Docker multi-stage build | 1042 | 290 | 72% |
| Debug PostgreSQL race condition | 1200 | 232 | 81% |
| Implement React error boundary | 3454 | 456 | 87% |
| **Average** | **1214** | **294** | **65%** |
*Range: 22%–87% savings across prompts.*
<!-- BENCHMARK-TABLE-END -->
> [!IMPORTANT]
> Caveman only affects output tokens — thinking/reasoning tokens are untouched. Caveman no make brain smaller. Caveman make *mouth* smaller. Biggest win is **readability and speed**, cost savings are a bonus.
### Science back caveman up
A March 2026 paper ["Brevity Constraints Reverse Performance Hierarchies in Language Models"](https://arxiv.org/abs/2604.00025) found that constraining large models to brief responses **improved accuracy by 26 percentage points** on certain benchmarks and completely reversed performance hierarchies. Verbose not always better. Sometimes less word = more correct.
- **Faster response** — less token to generate = speed go brrr
- **Easier to read** — no wall of text, just the answer
- **Same accuracy** — all technical info kept, only fluff removed ([science say so](https://arxiv.org/abs/2604.00025))
- **Save money** — ~71% less output token = less cost
- **Fun** — every code review become comedy
## Install
@@ -184,19 +168,15 @@ Stop with: "stop caveman" or "normal mode"
### Intensity Levels
Sometimes full caveman too much. Sometimes not enough. Now you pick:
| Level | Trigger | What it do |
|-------|---------|------------|
| **Lite** | `/caveman lite` or `$caveman lite` | Drop filler, keep grammar. Professional but no fluff |
| **Full** | `/caveman full` or `$caveman full` | Default caveman. Drop articles, fragments, full grunt |
| **Ultra** | `/caveman ultra` or `$caveman ultra` | Maximum compression. Telegraphic. Abbreviate everything |
Level stick until you change it or session end.
| **Lite** | `/caveman lite` | Drop filler, keep grammar. Professional but no fluff |
| **Full** | `/caveman full` | Default caveman. Drop articles, fragments, full grunt |
| **Ultra** | `/caveman ultra` | Maximum compression. Telegraphic. Abbreviate everything |
### 文言文 (Wenyan) Mode
Caveman go ancient. Classical Chinese literary compression — same technical accuracy, but in the most token-efficient written language humans ever invented.
Classical Chinese literary compression — same technical accuracy, but in the most token-efficient written language humans ever invented.
| Level | Trigger | What it do |
|-------|---------|------------|
@@ -204,62 +184,67 @@ Caveman go ancient. Classical Chinese literary compression — same technical ac
| **Wenyan-Full** | `/caveman wenyan` | Full 文言文. Maximum classical terseness |
| **Wenyan-Ultra** | `/caveman wenyan-ultra` | Extreme. Ancient scholar on a budget |
```
English: "Your component re-renders because you create a new object reference each render."
Caveman: "New object ref each render. Wrap in useMemo."
Wenyan: "物出新參照，致重繪。useMemo Wrap之。"
```
Same answer. Different era. Fewer token.
## What Caveman Do
| Thing | Caveman Do? |
|-------|------------|
| English explanation | 🪨 Caveman smash filler words |
| Code blocks | ✍️ Write normal (caveman not stupid) |
| Technical terms | 🧠 Keep exact (polymorphism stay polymorphism) |
| Error messages | 📋 Quote exact |
| Git commits & PRs | ✍️ Write normal |
| Articles (a, an, the) | 💀 Gone |
| Pleasantries | 💀 "Sure I'd be happy to" is dead |
| Hedging | 💀 "It might be worth considering" extinct |
Level stick until you change it or session end.
## Caveman Skills
Caveman not just talk different. Caveman have **tools**:
| Skill | What it do | Trigger |
|-------|-----------|---------|
| **caveman-commit** | Terse commit messages. Conventional Commits. ≤50 char subject. Why over what. | `/caveman-commit` |
| **caveman-review** | One-line PR comments: `L42: 🔴 bug: user null. Add guard.` No throat-clearing. | `/caveman-review` |
### caveman-commit
### caveman-compress
Terse commit messages. Conventional Commits format. Subject ≤50 chars. Body only when "why" not obvious.
Caveman make Claude *speak* with fewer tokens. **Compress** make Claude *read* fewer tokens.
Your `CLAUDE.md` loads on **every session start**. Caveman Compress rewrites memory files into caveman-speak so Claude reads less — without you losing the human-readable original.
```
❌ "feat: add a new endpoint to get user profile information from the database"
✅ feat(api): add GET /users/:id/profile
/caveman:compress CLAUDE.md
```
Trigger: `/caveman-commit` or just ask for a commit message.
### caveman-review
One-line code review comments. Location, problem, fix. No throat-clearing.
```
❌ "I noticed that on line 42 you're not checking if the user object
is null before accessing the email property. This could potentially
cause a crash if the user is not found in the database."
✅ L42: 🔴 bug: user can be null after .find(). Add guard before .email.
CLAUDE.md ← compressed (Claude reads this every session — fewer tokens)
CLAUDE.original.md ← human-readable backup (you read and edit this)
```
Severity prefix tell you what matter:
- `🔴 bug:` — broken, will cause incident
- `🟡 risk:` — works but fragile
- `🔵 nit:` — style, author can ignore
- `❓ q:` — genuine question
| File | Original | Compressed | Saved |
|------|----------:|----------:|------:|
| `claude-md-preferences.md` | 706 | 285 | **59.6%** |
| `project-notes.md` | 1145 | 535 | **53.3%** |
| `claude-md-project.md` | 1122 | 687 | **38.8%** |
| `todo-list.md` | 627 | 388 | **38.1%** |
| `mixed-with-code.md` | 888 | 574 | **35.4%** |
| **Average** | **898** | **494** | **45%** |
Trigger: `/caveman-review` or ask for a code review.
Code blocks, URLs, file paths, commands, headings, dates, version numbers — anything technical passes through untouched. Only prose gets compressed. See the full [caveman-compress README](caveman-compress/README.md) for details. [Security note](./caveman-compress/SECURITY.md): Snyk flags this as High Risk due to subprocess/file patterns — it's a false positive.
## Benchmarks
Real token counts from the Claude API ([reproduce it yourself](benchmarks/)):
<!-- BENCHMARK-TABLE-START -->
| Task | Normal (tokens) | Caveman (tokens) | Saved |
|------|---------------:|----------------:|------:|
| Explain React re-render bug | 1180 | 159 | 87% |
| Fix auth middleware token expiry | 704 | 121 | 83% |
| Set up PostgreSQL connection pool | 2347 | 380 | 84% |
| Explain git rebase vs merge | 702 | 292 | 58% |
| Refactor callback to async/await | 387 | 301 | 22% |
| Architecture: microservices vs monolith | 446 | 310 | 30% |
| Review PR for security issues | 678 | 398 | 41% |
| Docker multi-stage build | 1042 | 290 | 72% |
| Debug PostgreSQL race condition | 1200 | 232 | 81% |
| Implement React error boundary | 3454 | 456 | 87% |
| **Average** | **1214** | **294** | **65%** |
*Range: 22%–87% savings across prompts.*
<!-- BENCHMARK-TABLE-END -->
> [!IMPORTANT]
> Caveman only affects output tokens — thinking/reasoning tokens are untouched. Caveman no make brain smaller. Caveman make *mouth* smaller. Biggest win is **readability and speed**, cost savings are a bonus.
A March 2026 paper ["Brevity Constraints Reverse Performance Hierarchies in Language Models"](https://arxiv.org/abs/2604.00025) found that constraining large models to brief responses **improved accuracy by 26 percentage points** on certain benchmarks. Verbose not always better. Sometimes less word = more correct.
## Evals
@@ -277,96 +262,6 @@ uv run --with tiktoken python evals/measure.py
Snapshots committed to git. CI runs free. Every number change reviewable as diff. Add a skill, add a prompt — harness pick it up automatically.
## Why
```
┌─────────────────────────────────────┐
│ TOKENS SAVED ████████ 75% │
│ TECHNICAL ACCURACY ████████ 100%│
│ SPEED INCREASE ████████ ~3x │
│ VIBES ████████ OOG │
└─────────────────────────────────────┘
```
- **Faster response** — less token to generate = speed go brrr
- **Easier to read** — no wall of text, just the answer
- **Same accuracy** — all technical info kept, only fluff removed ([science say so](https://arxiv.org/abs/2604.00025))
- **Save money** — ~71% less output token = less cost
- **Fun** — every code review become comedy
## How It Work
Caveman not dumb. Caveman **efficient**.
Normal LLM waste token on:
- "I'd be happy to help you with that" (8 wasted tokens)
- "The reason this is happening is because" (7 wasted tokens)
- "I would recommend that you consider" (7 wasted tokens)
- "Sure, let me take a look at that for you" (10 wasted tokens)
Caveman say what need saying. Then stop.
## Caveman Compress
Caveman makes Claude *speak* with fewer tokens. **Caveman Compress** makes Claude *read* fewer tokens.
Your `CLAUDE.md` loads on **every session start**. A 1000-token project memory file costs you tokens every single time you open a project. Caveman Compress rewrites those files into caveman-speak so Claude reads less — without you losing the human-readable original.
```
/caveman:compress CLAUDE.md
```
```
CLAUDE.md ← compressed (Claude reads this every session — fewer tokens)
CLAUDE.original.md ← human-readable backup (you read and edit this)
```
### How it works
A Python pipeline that shells out to `claude --print` for the actual compression, then validates the result locally — no tokens wasted on checking.
```
detect file type (local) → compress with Claude (1 call) → validate (local)
↓
if errors: targeted fix (1 call, cherry-pick only)
↓
retry up to 2×, restore original on failure
```
### What's preserved exactly
Code blocks, inline code, URLs, file paths, commands, headings, table structure, dates, version numbers — anything technical passes through untouched. Only natural language prose gets compressed.
### Compress benchmarks
| File | Original | Compressed | Saved |
|------|----------:|----------:|------:|
| `claude-md-preferences.md` | 706 | 285 | **59.6%** |
| `project-notes.md` | 1145 | 535 | **53.3%** |
| `claude-md-project.md` | 1122 | 687 | **38.8%** |
| `todo-list.md` | 627 | 388 | **38.1%** |
| `mixed-with-code.md` | 888 | 574 | **35.4%** |
| **Average** | **898** | **494** | **45%** |
### Full-circle token savings
| Tool | What it cuts | Savings |
|------|-------------|---------|
| **caveman** | Output tokens (Claude's responses) | ~65% |
| **compress (/caveman:compress)** | Input tokens (memory files loaded per session) | ~45% |
| **Both together** | The whole conversation | Output + input both shrunk |
Compress is built in with the caveman plugin — no separate install needed.
- Use `/caveman` for caveman mode
- Use `/caveman:compress <filepath>` for memory-file compression
## Security
`caveman-compress` is flagged as Snyk High Risk due to subprocess and file I/O patterns detected by static analysis. This is a false positive — see [SECURITY.md](./caveman-compress/SECURITY.md) for a full explanation of what the skill does and does not do.
See the full [caveman-compress README](caveman-compress/README.md) for install, usage, and validation details.
## Star This Repo
If caveman save you mass token, mass money — leave mass star. ⭐