{
  "markdown": "<p align=\"center\">\n  <img src=\"https://em-content.zobj.net/source/apple/391/rock_1faa8.png\" width=\"120\" />\n</p>\n\n<h1 align=\"center\">caveman</h1>\n\n<p align=\"center\">\n  <strong>why use many token when few do trick</strong>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://github.com/JuliusBrussee/caveman/stargazers\"><img src=\"https://img.shields.io/github/stars/JuliusBrussee/caveman?style=flat&color=yellow\" alt=\"Stars\"></a>\n  <a href=\"https://github.com/JuliusBrussee/caveman/commits/main\"><img src=\"https://img.shields.io/github/last-commit/JuliusBrussee/caveman?style=flat\" alt=\"Last Commit\"></a>\n  <a href=\"LICENSE\"><img src=\"https://img.shields.io/github/license/JuliusBrussee/caveman?style=flat\" alt=\"License\"></a>\n</p>\n\n<p align=\"center\">\n  <a href=\"#before--after\">Before/After</a> •\n  <a href=\"#install\">Install</a> •\n  <a href=\"#what-you-get\">What You Get</a> •\n  <a href=\"#benchmarks\">Benchmarks</a> •\n  <a href=\"./INSTALL.md\">Full install guide</a>\n</p>\n\n---\n\nA [Claude Code](https://docs.anthropic.com/en/docs/claude-code) skill/plugin (also Codex, Gemini, Cursor, Windsurf, Cline, Copilot, 30+ more) that makes agent talk like caveman — cuts **~75% of output tokens**, keeps full technical accuracy. Brain still big. Mouth small.\n\n## Before / After\n\n<table>\n<tr>\n<td width=\"50%\">\n\n### 🗣️ Normal Claude (69 tokens)\n\n> \"The reason your React component is re-rendering is likely because you're creating a new object reference on each render cycle. When you pass an inline object as a prop, React's shallow comparison sees it as a different object every time, which triggers a re-render. I'd recommend using useMemo to memoize the object.\"\n\n</td>\n<td width=\"50%\">\n\n### <img src=\"docs/assets/dancing-rock.svg\" width=\"20\" height=\"20\" alt=\"rock\"/> Caveman Claude (19 tokens)\n\n> \"New object ref each render. Inline object prop = new ref = re-render. Wrap in `useMemo`.\"\n\n</td>\n</tr>\n<tr>\n<td>\n\n### 🗣️ Normal Claude\n\n> \"Sure! I'd be happy to help you with that. The issue you're experiencing is most likely caused by your authentication middleware not properly validating the token expiry. Let me take a look and suggest a fix.\"\n\n</td>\n<td>\n\n### <img src=\"docs/assets/dancing-rock.svg\" width=\"20\" height=\"20\" alt=\"rock\"/> Caveman Claude\n\n> \"Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:\"\n\n</td>\n</tr>\n</table>\n\n**Same fix. 75% less word. Brain still big.**\n\n```\n┌─────────────────────────────────────┐\n│  TOKENS SAVED          ████████ 75% │\n│  TECHNICAL ACCURACY    ████████ 100%│\n│  SPEED INCREASE        ████████ ~3x │\n│  VIBES                 ████████ OOG │\n└─────────────────────────────────────┘\n```\n\nPick your level of grunt — `lite` (drop filler), `full` (default caveman), `ultra` (telegraphic), or `wenyan` (classical Chinese, even shorter). One command switch. Cost go down forever.\n\n<table align=\"center\">\n<tr><td>\n\n### <img src=\"docs/assets/dancing-rock.svg\" width=\"22\" height=\"22\" alt=\"rock\"/> Like this trick? Now get whole agent — **caveman-code**\n\nThis skill shrink what agent **say**. **[caveman-code](https://github.com/JuliusBrussee/caveman-code)** shrink **everything** — full terminal coding agent, caveman top to bottom. **~2× fewer tokens than Codex** on identical tasks. 20+ providers · plan mode · autopilot goal loop · MIT.\n\n```bash\nnpm install -g @juliusbrussee/caveman-code\n```\n\n[**▶ Try caveman-code now →**](https://github.com/JuliusBrussee/caveman-code) — *why use many token when whole agent save*\n\n</td></tr>\n</table>\n\n## Install\n\nOne line. Find every agent. Install for each.\n\n```bash\n# macOS / Linux / WSL / Git Bash\ncurl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash\n\n# Windows (PowerShell 5.1+)\nirm https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.ps1 | iex\n```\n\n~30 seconds. Needs Node ≥18. Skip agent you no have. Safe to re-run.\n\n**Trigger:** type `/caveman` or say \"talk like caveman\". Stop with \"normal mode\".\n\nOne agent only, manual command, or any of 30+ other agents → [**INSTALL.md**](./INSTALL.md).\nInstall break? Open agent, say *\"Read CLAUDE.md and INSTALL.md, install caveman for me.\"* Agent fix own brain.\n\n## What You Get\n\n| Skill | What |\n|---|---|\n| `/caveman [lite\\|full\\|ultra\\|wenyan]` | Compress every reply. Levels stick until session end. |\n| `/caveman-commit` | Conventional Commit messages, ≤50 char subject. Why over what. |\n| `/caveman-review` | One-line PR comments: `L42: 🔴 bug: user null. Add guard.` |\n| `/caveman-stats` | Real session token usage + lifetime savings + USD. Tweetable line via `--share`. |\n| `/caveman-compress <file>` | Rewrite memory file (e.g. `CLAUDE.md`) into caveman-speak. Cuts ~46% input tokens every session. Code/URLs/paths byte-preserved. |\n| `caveman-shrink` | MCP middleware. Wraps any MCP server, compresses tool descriptions. [npm](https://www.npmjs.com/package/caveman-shrink). |\n| `cavecrew-*` | Caveman subagents (investigator/builder/reviewer). ~60% fewer tokens than vanilla, main context lasts longer. |\n\n**Statusline badge** — Claude Code shows `[CAVEMAN] ⛏ 12.4k` (lifetime tokens saved). Updates every `/caveman-stats` run. Set `CAVEMAN_STATUSLINE_SAVINGS=0` to silence.\n\nAuto-activate every session: Claude Code, Codex, Gemini (built-in). Cursor / Windsurf / Cline / Copilot get always-on rule files via `--with-init`. Other agents trigger with `/caveman` per session. Full feature matrix in [INSTALL.md](./INSTALL.md#what-you-get).\n\n## Benchmarks\n\nReal token counts from the Claude API. Average **65% output reduction** across 10 prompts (range 22-87%).\n\n<!-- BENCHMARK-TABLE-START -->\n| Task | Normal | Caveman | Saved |\n|------|-------:|--------:|------:|\n| Explain React re-render bug | 1180 | 159 | 87% |\n| Fix auth middleware token expiry | 704 | 121 | 83% |\n| Set up PostgreSQL connection pool | 2347 | 380 | 84% |\n| Explain git rebase vs merge | 702 | 292 | 58% |\n| Refactor callback to async/await | 387 | 301 | 22% |\n| Architecture: microservices vs monolith | 446 | 310 | 30% |\n| Review PR for security issues | 678 | 398 | 41% |\n| Docker multi-stage build | 1042 | 290 | 72% |\n| Debug PostgreSQL race condition | 1200 | 232 | 81% |\n| Implement React error boundary | 3454 | 456 | 87% |\n| **Average** | **1214** | **294** | **65%** |\n<!-- BENCHMARK-TABLE-END -->\n\nRaw data and reproduction script: [`benchmarks/`](./benchmarks/). Three-arm eval harness (baseline / terse / skill) lives in [`evals/`](./evals/) — caveman compared against `Answer concisely.` not against verbose default, so the delta is honest.\n\n**caveman-compress receipts** (real memory files):\n\n| File | Original | Compressed | Saved |\n|---|---:|---:|---:|\n| `claude-md-preferences.md` | 706 | 285 | **59.6%** |\n| `project-notes.md` | 1145 | 535 | **53.3%** |\n| `claude-md-project.md` | 1122 | 636 | **43.3%** |\n| `todo-list.md` | 627 | 388 | **38.1%** |\n| `mixed-with-code.md` | 888 | 560 | **36.9%** |\n| **Average** | **898** | **481** | **46%** |\n\n> [!IMPORTANT]\n> Caveman only affects output tokens — thinking/reasoning tokens untouched. Caveman no make brain smaller. Caveman make *mouth* smaller. Biggest win is **readability and speed**, cost savings a bonus.\n\nA 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 points** on certain benchmarks. Verbose not always better. Sometimes less word = more correct.\n\n## How It Work\n\n1. Install drop skill file in agent.\n2. Skill tell agent: drop filler, keep substance, use fragments.\n3. For Claude Code, hook also write tiny flag file each session — agent see flag, talk caveman from message one. No need say `/caveman`.\n4. Stats command read Claude Code session log, count tokens saved, write number to statusline.\n5. Caveman-compress sub-skill rewrite memory files (CLAUDE.md, project notes) so each session start with smaller context. Save tokens forever, not just one reply.\n\nMaintainer detail (hook architecture, file ownership, CI sync) live in [CLAUDE.md](./CLAUDE.md).\n\n## Lobster, Meet Rock 🦞 <img src=\"docs/assets/dancing-rock.svg\" width=\"22\" height=\"22\" alt=\"rock\"/>\n\n[**OpenClaw**](https://openclaw.ai) the self-host gateway. One box, many agent inside (Claude Code, Codex, Pi, OpenCode), wired to your Slack / Discord / iMessage / Telegram / whatever. Tagline: *\"The lobster way.\"* Lobster strong. Lobster smart. Lobster also talk a lot.\n\nCaveman teach lobster brevity — same canonical installer, scoped to one agent:\n\n```bash\n# macOS / Linux / WSL\ncurl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash -s -- --only openclaw\n\n# Windows (PowerShell): no Node? install Node ≥18 first, then\nnpx -y github:JuliusBrussee/caveman -- --only openclaw\n```\n\nTwo thing happen, no more:\n\n1. **Skill drop** at `~/.openclaw/workspace/skills/caveman/SKILL.md` — spec-correct frontmatter (`version`, `always: true`), discoverable by `openclaw skills list`. Skill not auto-inject (OpenClaw load skill on demand) — that why we also do step 2.\n2. **SOUL.md nudge.** Tiny marker-fenced block appended to `~/.openclaw/workspace/SOUL.md`. OpenClaw inject SOUL.md into *every* turn under \"Project Context\" (12K-per-file, 60K total — block well under). Lobster terse from message one. No `/caveman` per session. No nag.\n\n```\n~/.openclaw/workspace/\n├── skills/caveman/SKILL.md   ← full ruleset, on-demand load\n└── SOUL.md                    ← <!-- caveman-begin --> ... <!-- caveman-end -->\n                                  ↑ auto-inject every turn\n```\n\nCustom workspace path? `OPENCLAW_WORKSPACE=/your/path` before the command. Uninstall: same one-liner with `--uninstall` — skill folder gone, SOUL.md block ripped out cleanly, your other workspace content stay untouched. Idempotent re-runs (frontmatter not double-prepended, marker block not duplicated).\n\nLobster claw still sharp. Lobster mouth now small. Brain still big.\n\n## Caveman Ecosystem\n\nFive tools. One philosophy: **agent do more with less**.\n\n| Repo | What |\n|------|------|\n| [**caveman**](https://github.com/JuliusBrussee/caveman) *(you here)* | Output compression — *why use many token when few do trick* |\n| [**caveman-code**](https://github.com/JuliusBrussee/caveman-code) | Whole terminal coding agent — *why use many token when whole agent can save* |\n| [**cavemem**](https://github.com/JuliusBrussee/cavemem) | Cross-agent memory — *why agent forget when agent can remember* |\n| [**cavekit**](https://github.com/JuliusBrussee/cavekit) | Spec-driven build loop — *why agent guess when agent can know* |\n| [**cavegemma**](https://github.com/JuliusBrussee/finetune-caveman) | Gemma 4 31B fine-tuned on caveman pairs — *why prompt every turn when weight remember* |\n\nCompose: cavekit drive build, caveman compress what agent *say*, cavemem compress what agent *remember*, cavegemma bake compression into weight, caveman-code ship it all as one terminal agent. One rock. Two rock. Three rock. Four rock. Five rock. That it.\n\n## Links\n\n- [INSTALL.md](./INSTALL.md) — full install matrix, all flags, per-agent detail\n- [CONTRIBUTING.md](./CONTRIBUTING.md) — how to send patch\n- [CLAUDE.md](./CLAUDE.md) — maintainer guide (file ownership, hook architecture, CI)\n- [docs/](./docs/) — extra guides (Windows install, etc.)\n- [Issues](https://github.com/JuliusBrussee/caveman/issues) — bug, feature, weird behavior\n\n## Star This Repo\n\nCaveman save you token, save you money. Star cost zero. Fair trade. ⭐\n\n[![Star History Chart](https://api.star-history.com/svg?repos=JuliusBrussee/caveman&type=Date)](https://star-history.com/#JuliusBrussee/caveman&Date)\n\n## Also by Julius Brussee\n\n- **[Revu](https://github.com/JuliusBrussee/revu-swift)** — local-first macOS study app with FSRS spaced repetition. [revu.cards](https://revu.cards)\n\n## License\n\nMIT — free like mass mammoth on open plain.\n",
  "bytes": 11858,
  "sha": "5895a5a812b4dac97245760b6b76dbaf16909b7119536c58491c36a37d0a3c36",
  "repo_slug": "luaaccess/caveman",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_luaaccess_caveman_f237d754/readme"
}