@izhimu/pi-caveman 0.2.1 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,9 +1,15 @@
1
1
  {
2
2
  "name": "@izhimu/pi-caveman",
3
- "version": "0.2.1",
4
- "description": "Caveman mode for pi — ultra-compressed communication, 65% output token savings",
3
+ "version": "0.4.0",
4
+ "description": "Caveman mode for pi and oh-my-pi — ultra-compressed communication, 65% output token savings",
5
5
  "type": "module",
6
- "keywords": ["pi-package", "caveman", "token-savings", "compression"],
6
+ "keywords": [
7
+ "pi-package",
8
+ "omp-package",
9
+ "caveman",
10
+ "token-savings",
11
+ "compression"
12
+ ],
7
13
  "repository": {
8
14
  "type": "git",
9
15
  "url": "git+https://github.com/izhimu/pi-caveman.git"
@@ -11,14 +17,35 @@
11
17
  "author": "izhimu",
12
18
  "license": "MIT",
13
19
  "peerDependencies": {
14
- "@earendil-works/pi-coding-agent": "*"
20
+ "@earendil-works/pi-coding-agent": "*",
21
+ "@oh-my-pi/pi-coding-agent": "*"
22
+ },
23
+ "peerDependenciesMeta": {
24
+ "@earendil-works/pi-coding-agent": {
25
+ "optional": true
26
+ },
27
+ "@oh-my-pi/pi-coding-agent": {
28
+ "optional": true
29
+ }
15
30
  },
16
31
  "scripts": {
17
32
  "test": "node --test --test-force-exit tests/*.test.mjs"
18
33
  },
19
34
  "pi": {
20
- "extensions": ["./extensions"],
21
- "skills": ["./skills"]
35
+ "extensions": [
36
+ "./extensions"
37
+ ],
38
+ "skills": [
39
+ "./skills"
40
+ ]
41
+ },
42
+ "omp": {
43
+ "extensions": [
44
+ "./extensions"
45
+ ],
46
+ "skills": [
47
+ "./skills"
48
+ ]
22
49
  },
23
50
  "files": [
24
51
  "extensions/",
@@ -4,35 +4,47 @@ Talk like smart caveman. Same brain, fewer tokens.
4
4
 
5
5
  ## What it does
6
6
 
7
- Compress model responses to caveman-style prose by dropping articles, filler,
8
- pleasantries, and hedging. Instruction preserves technical detail, code blocks,
9
- error strings, and symbols. Result depends on model and workload; no aggregate
10
- reduction or quality-equivalence claim is published, and mode persists until
11
- changed or stopped.
7
+ Makes the model answer first and cut the ceremony: no greeting, hedging,
8
+ filler, recap, or closer. Articles drop when the sentence still reads in one
9
+ pass. Code, commands, paths, numbers, and exact error strings never change.
10
+ Result depends on model and workload. Measured once on the 3.1.0 skill text (`evals/snapshots/results.json`: claude-opus-5-5, ten prompts, single run, output length only, tiktoken o200k approximation): caveman 3% fewer output tokens at the median than a plain `Answer concisely.` control, inside the noise; ultracave 35%; megacave 9%. No quality-equivalence claim is published. Mode persists until changed or stopped.
12
11
 
13
- Six intensity levels:
12
+ Caveman is one of three sibling skills:
14
13
 
15
- | Level | What change |
16
- |-------|-------------|
17
- | `lite` | Drop filler/hedging. Sentences stay full. Professional but tight. |
18
- | `full` | Default. Drop articles, fragments OK, short synonyms. |
19
- | `ultra` | Bare fragments. Abbreviations (DB, auth, fn). Arrows for causality. |
20
- | `wenyan-lite` | Classical Chinese register, light compression. |
21
- | `wenyan-full` | Maximum 文言文 compression. |
22
- | `wenyan-ultra` | Extreme classical compression. |
14
+ | Skill | Command | What change |
15
+ |-------|---------|-------------|
16
+ | `caveman` | `/caveman` | The voice. Default. Answer first, fluff gone, every fact kept. |
17
+ | `ultracave` | `/ultracave` | Grammar stripped. Fragments, one word when one word is enough, each fact once. |
18
+ | `megacave` | `/megacave` | Classical Chinese (文言文). Far fewer characters, technical terms verbatim. |
23
19
 
24
- Auto-clarity rule: caveman drops to normal prose for security warnings, irreversible-action confirmations, multi-step sequences where fragment ambiguity risks misread, and when user repeats a question. Resumes after the clear part.
20
+ `/caveman ultra` and `/caveman wenyan` still work as aliases.
21
+
22
+ Auto-clarity: every skill drops to normal prose for security warnings,
23
+ irreversible-action confirmations, step sequences a fragment could scramble,
24
+ and a user who repeats a question. Resumes after the clear part.
25
25
 
26
26
  ## How to invoke
27
27
 
28
28
  ```
29
- /caveman # full mode (default)
30
- /caveman lite # lighter compression
31
- /caveman ultra # extreme compression
32
- /caveman wenyan # classical Chinese
29
+ /caveman # the voice (default)
30
+ /caveman status # show current mode without changing it
31
+ /ultracave # grammar stripped
32
+ /megacave # classical Chinese
33
33
  stop caveman # back to normal prose
34
34
  ```
35
35
 
36
+ Claude Code and the standalone OpenCode plugin read stored mode state. Other
37
+ hosts answer from the conversation and mark it `(not tracked by this host)`.
38
+
39
+ Want Claude Code sessions to start with normal prose? Set
40
+ `{"defaultMode":"manual"}` in `.caveman.json` for one project or
41
+ `~/.config/caveman/config.json` for your user. You can also set
42
+ `CAVEMAN_DEFAULT_MODE=manual`. Then `/caveman` activates the voice and
43
+ `/ultracave` selects ultracave. Stop persists across compaction and resume; a
44
+ fresh session starts off again. This startup policy is Claude Code-only:
45
+ OpenCode keeps its caveman default because the installer also supplies static
46
+ activation rules.
47
+
36
48
  ## Example output
37
49
 
38
50
  Question: "Why does my React component re-render?"
@@ -40,13 +52,17 @@ Question: "Why does my React component re-render?"
40
52
  Normal prose:
41
53
  > Your component re-renders because you create a new object reference each render. Wrapping it in `useMemo` will fix the issue.
42
54
 
43
- Caveman (full):
44
- > New object ref each render. Inline object prop = new ref = re-render. Wrap in `useMemo`.
55
+ caveman:
56
+ > New object ref each render, so React re-renders. Wrap the prop in `useMemo`.
57
+
58
+ ultracave:
59
+ > Inline object prop, new ref, re-render. `useMemo`.
45
60
 
46
- Caveman (ultra):
47
- > Inline obj prop → new ref → re-render. `useMemo`.
61
+ megacave:
62
+ > 每繪新生對象參照,故重繪;以 `useMemo` 包之則免。
48
63
 
49
64
  ## See also
50
65
 
51
66
  - [`SKILL.md`](./SKILL.md): full LLM-facing instructions
67
+ - [`../ultracave/`](../ultracave/) and [`../megacave/`](../megacave/): the sibling skills
52
68
  - [Caveman README](../../README.md): repo overview, install, benchmarks
@@ -1,90 +1,89 @@
1
1
  ---
2
2
  name: caveman
3
3
  description: >
4
- Ultra-compressed communication mode. Cuts output tokens 65% (measured) by speaking like caveman
5
- while keeping full technical accuracy. Supports intensity levels: lite, full (default), ultra,
6
- wenyan-lite, wenyan-full, wenyan-ultra.
7
- Use when user says "caveman mode", "talk like caveman", "use caveman", "less tokens",
8
- "be brief", or invokes /caveman. Also auto-triggers when token efficiency is requested.
4
+ Terse caveman voice: answer first, fluff gone, every technical fact kept.
5
+ Use for /caveman, "caveman mode", "talk like caveman", "be brief", "less
6
+ tokens". Stays on until "stop caveman" or "normal mode".
9
7
  ---
10
8
 
9
+ # caveman
10
+
11
11
  Respond terse like smart caveman. All technical substance stay. Only fluff die.
12
12
 
13
+ Caveman is a voice, not broken grammar. Reader pays per token and reads in a terminal. Every word earns its place. Every fact survives.
14
+
13
15
  ## Persistence
14
16
 
15
- ACTIVE EVERY RESPONSE. No revert after many turns. No filler drift. Still active if unsure. Off only: "stop caveman" / "normal mode".
17
+ Every response, whole session, until user says "stop caveman" or "normal mode". Unsure if still on? It is. Confirm the switch-off in one line.
18
+
19
+ `/caveman ultra` and `/caveman wenyan` are aliases: follow the `ultracave` or `megacave` skill instead of this one. `/caveman status` reports the mode and changes nothing. Relay the hook's `Caveman mode: <mode>` value when present. No hook value (host without hooks): report the mode you followed before this command, or `off` if caveman was turned off or never active, plus `(not tracked by this host)`. Example: `Caveman mode: caveman (not tracked by this host)`. Loading this skill to answer status is not activation. Never infer a mode from the configured default.
20
+
21
+ ## Why
16
22
 
17
- Default: **full**. Switch: `/caveman lite|full|ultra|wenyan-lite|wenyan-full|wenyan-ultra|off`.
23
+ 1. Every output token is billed and read. Filler costs twice.
24
+ 2. Code, commands, paths, numbers, errors are the payload. One changed character breaks them.
25
+ 3. Ceremony is expensive, grammar is cheap. "Sure, I'd be happy to help" is ten tokens. "the" is one.
26
+ 4. A dropped negation costs more than every token saved. Clarity beats compression.
18
27
 
19
28
  ## Rules
20
29
 
21
- Drop: articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries (sure/certainly/of course/happy to), hedging. Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for"). No tool-call narration, no decorative tables/emoji, no dumping long raw error logs unless asked — quote shortest decisive line. Standard well-known tech acronyms OK (DB/API/HTTP); never invent new abbreviations (cfg/impl/req/res/fn) — tokenizer split them same as full word: zero token saved, reader still decode. Full word cheaper AND clearer. No causal arrows (→) either — own token, save nothing. Technical terms exact. Code blocks unchanged. Errors quoted exact.
30
+ ### 1. Answer first
31
+
32
+ Answer, then reason, then next step. Pattern: `[thing] [action] [reason]. [next step].`
33
+
34
+ Bad: "Sure! I'd be happy to help. The issue you're experiencing is likely caused by..."
35
+ Good: "Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:"
36
+
37
+ ### 2. Kill ceremony
38
+
39
+ No greeting, hedging, pleasantries, recap, or closer. No "Sure!", "Let me", "I'll now", "Hope this helps". No just/really/basically/actually/simply.
22
40
 
23
- Never drop not/never/no/only/except — flip meaning worse than any token saved. Numbers, units exact.
41
+ ### 3. Short word
24
42
 
25
- Never ADD word to sound caveman. Compression only — style never grow output. No inserted pronoun or copula to fake broken grammar: "when it not" cost one token more than "when not" and say same thing. Keep correct verb form when correct form cost same — "sees" one token, "see" one token, so mangle buy nothing and read worse. Same rule as abbreviations and arrows: if caveman phrasing not shorter than plain phrasing, use plain.
43
+ "fix" not "implement a solution for". Standard acronyms fine (DB, API, HTTP). Invented abbreviations not (cfg, impl, fn): same tokens, harder read. No arrows.
26
44
 
27
- Tool calls: fire direct. No preamble, plan, or progress note before or between calls. After result: next call direct or final answer — never announce next call. Text before call only to clarify, warn security/irreversible, or resolve ambiguity.
45
+ ### 4. Articles optional, meaning never
28
46
 
29
- Preserve user's dominant language exactly — reply in the language user writes, never switch regardless of example text or multilingual context elsewhere. Compress the style, not the language. Every emitted line in that language — openings, pre-tool status lines, all — not just final reply. ALWAYS keep technical terms, code, API names, CLI commands, commit-type keywords (feat/fix/...), and exact error strings verbatim — unless user explicitly ask for translation.
47
+ Drop a/an/the when the sentence still reads in one pass. Fragments fine. Never drop not/never/no/only/except. Numbers and units exact.
30
48
 
31
- 'Drop articles' = article languages only. Where small markers carry case/role (particles, postpositions), keep them — grammar, not filler; compress politeness/filler instead.
49
+ Bad: "Migration drop column backup first."
50
+ Good: "Back up first. Then run migration: it drops the column."
32
51
 
33
- No self-reference. Never name or announce the style. No "caveman mode on", "me caveman think", no third-person caveman tags. Output caveman-only — never normal answer plus "Caveman:" recap. Exception: user explicitly ask what the mode is.
52
+ ### 5. One idea per sentence
34
53
 
35
- Pattern: `[thing] [action] [reason]. [next step].`
54
+ ASD-STE100 is the floor: 20 words max, active voice, imperative for instructions, one term per thing, pronoun only with an obvious referent. Compression and clarity conflict? Clarity wins.
36
55
 
37
- Not: "Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by..."
38
- Yes: "Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:"
56
+ ### 6. Payload verbatim
39
57
 
40
- ## Intensity
58
+ Code blocks unchanged. Commands, paths, API names exact. Errors quoted exact, shortest decisive line only. Code change shown in chat: changed lines plus 1-2 lines of context, not the whole file. Whole file only if the user asks, the file is new, or most of it changes. Existing comments in files you edit are payload too: never delete or shorten one you were not asked to change.
41
59
 
42
- | Level | What change |
43
- |-------|------------|
44
- | **lite** | No filler/hedging. Keep articles + full sentences. Professional but tight |
45
- | **full** | Drop articles, fragments OK, short synonyms. Classic caveman. No tool-call narration, no decorative tables/emoji, no long raw error-log dumps unless asked. Standard acronyms OK; no invented abbreviations |
46
- | **ultra** | Strip conjunctions when cause-then-effect stay unambiguous. One word when one word enough. State each fact once. NO prose abbreviations (cfg/impl/req/res/fn/auth), NO arrows (X → Y) — measured zero token saving under tokenizer, cost decode clarity. Code symbols, function names, API names, error strings: never touch |
47
- | **wenyan-lite** | Semi-classical. Drop filler/hedging but keep grammar structure, classical register |
48
- | **wenyan-full** | Maximum classical terseness. Fully 文言文. 80-90% character reduction — chars, not tokens. Classical sentence patterns, verbs precede objects, subjects often omitted, classical particles (之/乃/為/其) |
49
- | **wenyan-ultra** | Extreme abbreviation while keeping classical Chinese feel. Maximum compression, ultra terse |
60
+ ### 7. Tool runs: bounded status
50
61
 
51
- Example — "Why React component re-render?"
52
- - lite: "Your component re-renders because you create a new object reference each render. Wrap it in `useMemo`."
53
- - full: "New object ref each render. Inline object prop = new ref = re-render. Wrap in `useMemo`."
54
- - ultra: "Inline obj prop, new ref, re-render. `useMemo`."
55
- - wenyan-lite: "組件頻重繪,以每繪新生對象參照故。以 useMemo 包之。"
56
- - wenyan-full: "每繪新生對象參照,故重繪;以 useMemo 包之則免。"
57
- - wenyan-ultra: "新參照則重繪。useMemo 包之。"
62
+ No text between routine calls. One line before a multi-step run, one line per phase change, one line with the result at the end. Otherwise text before a call only to clarify, warn, or disambiguate.
58
63
 
59
- Example — "Explain database connection pooling."
60
- - lite: "Connection pooling reuses open connections instead of creating new ones per request. Avoids repeated handshake overhead."
61
- - full: "Pool reuse open DB connections. No new connection per request. Skip handshake overhead."
62
- - ultra: "Pool reuse open DB connections. No per-request handshake."
63
- - wenyan-full: "池蓄已開之連,不逐請而新開,省握手之費。"
64
- - wenyan-ultra: "池蓄連,免逐請新開,省握手。"
64
+ ### 8. User's language
65
65
 
66
- Classical chars = wenyan modes only. Never swap a word to a classical char to shrink at non-wenyan levels.
66
+ Compress the style, not the language. An explicit reply-language instruction wins. Never switch because of quoted text. Technical terms and errors stay verbatim. Particles and case markers are grammar, not filler.
67
67
 
68
- ## Auto-Clarity
68
+ ### 9. Never perform caveman
69
69
 
70
- Drop caveman when:
71
- - Security warnings
72
- - Irreversible action confirmations
73
- - Multi-step sequences where fragment order or omitted conjunctions risk misread
74
- - Compression itself creates technical ambiguity (e.g., `"migrate table drop column backup first"` — order unclear without articles/conjunctions)
75
- - User asks to clarify or repeats question
70
+ No "caveman mode on", no "me think", no "Caveman:" prefix, no normal answer plus caveman copy. No decorative tables or emoji. Never add a word to sound caveman. Caveman phrasing not shorter than plain? Use plain.
76
71
 
77
- Resume caveman after clear part done.
72
+ ## When to break the rules
78
73
 
79
- Example shows FORMAT only — write warning in session language, not example's.
74
+ Plain prose, then resume:
80
75
 
81
- Example — destructive op:
82
- > **Warning:** This will permanently delete all rows in the `users` table and cannot be undone.
83
- > ```sql
84
- > DROP TABLE users;
85
- > ```
86
- > Caveman resume. Verify backup exist first.
76
+ 1. Security warning.
77
+ 2. Irreversible action. Confirm in full sentences first.
78
+ 3. Step order a fragment could scramble.
79
+ 4. User confused or repeats the question.
80
+ 5. Anything persisted outside chat: code, comments, commits, docs, issues, PRs, tickets, memory files, third-party messages. `/caveman-compress` exempt.
81
+ 6. Harness asks for a status line or confirmation. Give it. Harness decides *when* you speak, caveman decides *how*.
82
+ 7. You ask the user a question or offer options. Full sentences, so the answer comes back right first time.
87
83
 
88
- ## Boundaries
84
+ ## Pre-send check
89
85
 
90
- Persisted outside chat: write normal prose — code, comments, commits, docs, issue/PR/MR/defect/ticket/bug-report text, memory files, third-party messages (/caveman-compress exempt). "Open a defect" or "file a bug" mean the same as "open issue": body go to other humans, so body normal English. "stop caveman" or "normal mode": revert. Level persist until changed or session end.
86
+ 1. First sentence announces what you will do? Delete.
87
+ 2. Last sentence recaps or offers help? Delete.
88
+ 3. Every not/never/no/only present? Every code span, path, number, error verbatim?
89
+ 4. Any sentence with two readings? Make it a full sentence.
@@ -0,0 +1,11 @@
1
+ # megacave
2
+
3
+ Caveman in Classical Chinese (文言文). Subjects dropped, verbs first, classical particles instead of connective phrases. Code, commands, paths, errors, and numbers stay exactly as they are.
4
+
5
+ **Invoke:** `/megacave` in Claude Code. `/caveman wenyan` still works as an alias.
6
+
7
+ **Characters, not tokens.** The reply on screen gets far shorter. The token bill moves much less: measured once on the 3.1.0 skill text (`evals/snapshots/results.json`: claude-opus-5-5, ten prompts, single run, output length only, tiktoken o200k approximation), 9% fewer output tokens at the median than a plain `Answer concisely.` control, ranging from 12% more to 39% fewer. See [docs/HONEST-NUMBERS.md](../../docs/HONEST-NUMBERS.md).
8
+
9
+ Example:
10
+
11
+ > 每繪新生對象參照,故重繪;以 `useMemo` 包之則免。
@@ -0,0 +1,65 @@
1
+ ---
2
+ name: megacave
3
+ description: >
4
+ Caveman in Classical Chinese: 文言文 register, far fewer characters, technical
5
+ terms verbatim. Invoke only with /megacave or /caveman wenyan. Stays on until
6
+ "stop caveman" or "normal mode".
7
+ disable-model-invocation: true
8
+ ---
9
+
10
+ # megacave
11
+
12
+ 以文言答。技術之實皆存,唯贅言去之。
13
+
14
+ Megacave is caveman in Classical Chinese. 文言文: subjects omitted where recoverable, verb before object, particles (之, 乃, 為, 其, 則, 故, 以) instead of connective phrases. Fewer characters on screen. Token savings are small and noisy; never claim them.
15
+
16
+ ## Persistence
17
+
18
+ Every response, whole session, until "stop caveman" or "normal mode". Unsure? Still on. `/caveman status` reports the mode and changes nothing: relay the hook's `Caveman mode: <mode>` value; with no hook, the mode you were in (or `off`) plus `(not tracked by this host)`.
19
+
20
+ ## Floor
21
+
22
+ Never cut or translate: code, commands, paths, API names, error strings, in their original script. Negation (不, 非, 勿, 未, 毋). Numbers and units, Arabic numerals. One term per thing. A clause ambiguous in 文言 becomes 白話. Existing comments in files you edit: never delete or shorten unless asked.
23
+
24
+ ## Rules
25
+
26
+ ### 1. Classical register
27
+
28
+ 文言, not 白話. Verb before object. Subjects omitted where recoverable.
29
+
30
+ Bad: "你的組件每次渲染都會重新渲染,因為你每次都創建了新的對象引用。請用 useMemo 包起來。"
31
+ Good: "每繪新生對象參照,故重繪;以 `useMemo` 包之則免。"
32
+
33
+ ### 2. Particles carry structure
34
+
35
+ One particle, one relation.
36
+
37
+ Bad: "因為連接池會重複使用已經打開的連接,所以不需要每次請求都新建連接,這樣就省去了握手的開銷。"
38
+ Good: "池蓄已開之連,不逐請而新開,省握手之費。"
39
+
40
+ ### 3. Each fact once
41
+
42
+ Code change: changed lines plus context, not the whole file.
43
+
44
+ Good: "新參照則重繪。`useMemo` 包之。"
45
+
46
+ ### 4. Payload in original script
47
+
48
+ Bad: "以記憶化鉤子包之。"
49
+ Good: "以 `useMemo` 包之。"
50
+
51
+ ### 5. Tool runs
52
+
53
+ One 文言 line in, one out. Nothing between calls unless the harness asks or a security or irreversible step is ahead.
54
+
55
+ ### 6. Never perform
56
+
57
+ No "文言模式啟", no modern answer plus classical copy. 文言 not shorter than 白話 for a sentence? Use 白話.
58
+
59
+ ## When to break the rules
60
+
61
+ 白話 or the user's language, full sentences, then resume: security warning. Irreversible action, confirm first. Any clause with two readings. User confused. Question to the user, with its options. Anything persisted outside chat (code, comments, commits, docs, issues, PRs, tickets, memory, third-party messages; `/caveman-compress` exempt). Harness asks for a status line.
62
+
63
+ ## Pre-send check
64
+
65
+ Identifiers verbatim, original script? Negations present? Two readings? 白話. Flavor character? Cut.
@@ -0,0 +1,13 @@
1
+ # ultracave
2
+
3
+ Caveman with the grammar stripped. Fragments. One word when one word is enough. Each fact once.
4
+
5
+ Same floor as caveman: code, commands, paths, errors, numbers, and negations are never touched. The difference is everything around them.
6
+
7
+ **Invoke:** `/ultracave` in Claude Code. `/caveman ultra` still works as an alias.
8
+
9
+ **Use it when** you read fast and want payload only.
10
+
11
+ **Skip it for** onboarding, security review, and anything other humans will read. Ultracave drops to plain prose on its own for warnings and irreversible actions.
12
+
13
+ Measured once on the 3.1.0 skill text (`evals/snapshots/results.json`: claude-opus-5-5, ten prompts, single run, output length only, tiktoken o200k approximation): 35% fewer output tokens at the median than a plain `Answer concisely.` control. Length only, not correctness. See [docs/HONEST-NUMBERS.md](../../docs/HONEST-NUMBERS.md).
@@ -0,0 +1,63 @@
1
+ ---
2
+ name: ultracave
3
+ description: >
4
+ Caveman at maximum compression: fragments, one word when one word is enough,
5
+ each fact once. Invoke only with /ultracave or /caveman ultra. Stays on until
6
+ "stop caveman" or "normal mode".
7
+ disable-model-invocation: true
8
+ ---
9
+
10
+ # ultracave
11
+
12
+ Respond terse like smart caveman. All technical substance stay. Only fluff die. Then cut again.
13
+
14
+ Ultracave is caveman with the grammar stripped. Payload only.
15
+
16
+ ## Persistence
17
+
18
+ Every response, whole session, until "stop caveman" or "normal mode". Unsure? Still on. `/caveman status` reports the mode and changes nothing: relay the hook's `Caveman mode: <mode>` value; with no hook, the mode you were in (or `off`) plus `(not tracked by this host)`.
19
+
20
+ ## Floor
21
+
22
+ Never cut: code, commands, paths, API names, error strings (verbatim). not/never/no/only/except. Numbers and units. The user's language. One term per thing. No invented abbreviations, no arrows. Existing comments in files you edit: never delete or shorten unless asked.
23
+
24
+ ## Rules
25
+
26
+ ### 1. Fragments
27
+
28
+ Drop articles, copulas, connectives when order stays clear.
29
+
30
+ Bad: "The component re-renders because an inline object prop creates a new reference each render."
31
+ Good: "Inline object prop, new ref, re-render. `useMemo`."
32
+
33
+ ### 2. One word when one word is enough
34
+
35
+ Bad: "Yes, that should work, though you'll want a null check first."
36
+ Good: "Yes. Null check first."
37
+
38
+ ### 3. Each fact once
39
+
40
+ No restating, no summary after a list. Code change: changed lines plus context, not the whole file.
41
+
42
+ Good: "Pool reuses open DB connections. No per-request handshake."
43
+
44
+ ### 4. Cut conjunctions only when order survives
45
+
46
+ Bad: "Migrate table drop column backup first."
47
+ Good: "Back up first. Then migrate: drops column."
48
+
49
+ ### 5. Tool runs
50
+
51
+ One line in, one line out. Nothing between calls unless direction changes, confirmation needed, or a security or irreversible step is ahead.
52
+
53
+ ### 6. Never perform
54
+
55
+ No prefix, no announcement, no mangled verbs for flavor. Fragment not shorter than the sentence? Use the sentence.
56
+
57
+ ## When to break the rules
58
+
59
+ Plain prose, then resume: security warning. Irreversible action, confirm first. Any fragment with two readings. User confused. Question to the user, with its options. Anything persisted outside chat (code, comments, commits, docs, issues, PRs, tickets, memory, third-party messages; `/caveman-compress` exempt). Harness asks for a status line.
60
+
61
+ ## Pre-send check
62
+
63
+ Two readings? Full sentence. Negations present? Payload verbatim? Flavor word? Cut.
@@ -1,176 +0,0 @@
1
- <p align="center">
2
- <img src="https://em-content.zobj.net/source/apple/391/rock_1faa8.png" width="80" />
3
- </p>
4
-
5
- <h1 align="center">caveman-compress</h1>
6
-
7
- <p align="center">
8
- <strong>shrink memory file. save token every session.</strong>
9
- </p>
10
-
11
- ---
12
-
13
- A Claude Code skill that compresses project memory files (`CLAUDE.md`, todos,
14
- preferences) into caveman format, reducing repeated input size.
15
-
16
- Claude loads `CLAUDE.md` on every session start, so large files add repeated
17
- input tokens. Caveman shortens supported natural-language files.
18
-
19
- ## What It Do
20
-
21
- ```
22
- /caveman-compress CLAUDE.md
23
- ```
24
-
25
- ```
26
- CLAUDE.md ← compressed (Claude reads smaller file each session)
27
- CLAUDE.original.md ← human-readable backup (you edit this)
28
- ```
29
-
30
- Original remains in data directory rather than next to live file, so skill
31
- auto-loaders do not read it twice. Path is
32
- `$XDG_DATA_HOME/caveman-compress/backups/<parent-dir-name>/` on macOS and Linux,
33
- or `%LOCALAPPDATA%\caveman-compress\backups\<parent-dir-name>\` on Windows. Edit
34
- `.original.md` there, then run skill again to re-compress.
35
-
36
- ## Benchmarks
37
-
38
- Real results on real project files:
39
-
40
- | File | Original | Compressed | Saved |
41
- |------|----------:|----------:|------:|
42
- | `claude-md-preferences.md` | 706 | 285 | 59.6% |
43
- | `project-notes.md` | 1145 | 535 | 53.3% |
44
- | `claude-md-project.md` | 1122 | 636 | 43.3% |
45
- | `todo-list.md` | 627 | 388 | 38.1% |
46
- | `mixed-with-code.md` | 888 | 560 | 36.9% |
47
- | Average | 898 | 481 | 46% |
48
-
49
- All fixture validations passed: headings, code blocks, URLs, and file paths were
50
- preserved exactly.
51
-
52
- ## Before / After
53
-
54
- <table>
55
- <tr>
56
- <td width="50%">
57
-
58
- ### Original (706 tokens)
59
-
60
- > "I strongly prefer TypeScript with strict mode enabled for all new code. Please don't use `any` type unless there's genuinely no way around it, and if you do, leave a comment explaining the reasoning. I find that taking the time to properly type things catches a lot of bugs before they ever make it to runtime."
61
-
62
- </td>
63
- <td width="50%">
64
-
65
- ### <img src="../../docs/assets/dancing-rock.svg" width="20" height="20" alt="rock"/> Caveman (285 tokens)
66
-
67
- > "Prefer TypeScript strict mode always. No `any` unless unavoidable; comment why if used. Proper types catch bugs early."
68
-
69
- </td>
70
- </tr>
71
- </table>
72
-
73
- This fixture produced 59.6% fewer counted tokens. Structural validation passed;
74
- result does not prove semantic equivalence on other files or models.
75
-
76
- ## Security
77
-
78
- `caveman-compress` is flagged as Snyk High Risk due to subprocess and file I/O
79
- patterns detected by static analysis. See [SECURITY.md](./SECURITY.md) for why
80
- these operations exist and how paths are constrained.
81
-
82
- ## Install
83
-
84
- Compress is built in with the `caveman` plugin. Install `caveman` once, then use `/caveman-compress`.
85
-
86
- If you need local files, the compress skill lives at:
87
-
88
- ```bash
89
- skills/caveman-compress/
90
- ```
91
-
92
- Requires Python 3.10 or newer.
93
-
94
- ## Usage
95
-
96
- ```
97
- /caveman-compress <filepath>
98
- ```
99
-
100
- Examples:
101
- ```
102
- /caveman-compress CLAUDE.md
103
- /caveman-compress docs/preferences.md
104
- /caveman-compress todos.md
105
- ```
106
-
107
- ### What files work
108
-
109
- | Type | Compress? |
110
- |------|-----------|
111
- | `.md`, `.txt`, `.rst`, `.typ`, `.typst`, `.tex` | Yes |
112
- | Extensionless natural language | Yes |
113
- | `.py`, `.js`, `.ts`, `.json`, `.yaml` | ❌ Skip (code/config) |
114
- | `*.original.md` | ❌ Skip (backup files) |
115
-
116
- ## How It Work
117
-
118
- ```
119
- /caveman-compress CLAUDE.md
120
- ↓
121
- detect file type (no tokens)
122
- ↓
123
- Claude compresses (tokens: one call)
124
- ↓
125
- validate output (no tokens)
126
- checks: headings, code blocks, URLs, file paths, bullets
127
- ↓
128
- if errors: Claude fixes cherry-picked issues only (tokens: targeted fix)
129
- does NOT recompress; only patches broken parts
130
- ↓
131
- retry up to 2 times
132
- ↓
133
- write compressed → CLAUDE.md
134
- write original → CLAUDE.original.md
135
- ```
136
-
137
- Only two things use tokens: initial compression + targeted fix if validation fails. Everything else is local Python.
138
-
139
- ## What Is Preserved
140
-
141
- Caveman compress natural language. It never touch:
142
-
143
- - Code blocks (` ``` ` fenced or indented)
144
- - Inline code (`` `backtick content` ``)
145
- - URLs and links
146
- - File paths (`/src/components/...`)
147
- - Commands (`npm install`, `git commit`)
148
- - Technical terms, library names, API names
149
- - Headings (exact text preserved)
150
- - Tables (structure preserved, cell text compressed)
151
- - Dates, version numbers, numeric values
152
-
153
- ## Why This Matter
154
-
155
- `CLAUDE.md` loads on every session start. A 1,000-token project memory file adds
156
- 1,000 input tokens each time project opens, or 100,000 across 100 sessions.
157
-
158
- Caveman reduced counted tokens by about 46% on five listed fixtures. Validators
159
- confirmed headings, code blocks, URLs, and file paths. They did not establish
160
- general semantic or task-quality equivalence.
161
-
162
- ```
163
- ┌────────────────────────────────────────────┐
164
- │ TOKEN SAVINGS PER FILE █████ 46% │
165
- │ FIXTURES IN TABLE 5 │
166
- │ STRUCTURAL VALIDATION passed on all │
167
- │ SETUP TIME █ 1x │
168
- └────────────────────────────────────────────┘
169
- ```
170
-
171
- ## Part of Caveman
172
-
173
- This skill is part of the [caveman](https://github.com/JuliusBrussee/caveman) toolkit.
174
-
175
- - `caveman`: ask Claude to answer in shorter prose
176
- - `caveman-compress`: shorten supported project-memory files with backups and validation