@izhimu/pi-caveman 0.5.0 → 0.6.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/CHANGELOG.md CHANGED
@@ -1,84 +1,93 @@
1
- # Changelog
2
-
3
- All notable changes to `@izhimu/pi-caveman` will be documented in this file.
4
-
5
- ## [0.5.0] - 2026-10-24
6
-
7
- ### Removed
8
- - **Standalone `/ultracave` and `/megacave` slash commands** (including their plugin-namespaced `/caveman:ultracave` / `/caveman:megacave` forms and the `input` interception branches). The modes themselves are unchanged and remain reachable via `/caveman ultracave`, `/caveman megacave` (plus legacy aliases `ultra`, `wenyan*`) and natural-language triggers.
9
-
10
- ## [0.4.1] - 2026-10-24
11
-
12
- ### Fixed
13
- - **Host API conformance for `sendMessage`**: the `/caveman status` summary is now sent as `{ customType: "caveman-status", content, display: false }`, matching pi's `SendMessageHandler` payload (which requires `customType`/`display` and has no `attribution` field). The old call passed an unsupported `attribution: "user"` and omitted `customType`, so pi persisted a session entry with `customType: undefined`. oh-my-pi accepts both shapes.
14
- - **Session boundary handling**:
15
- - Fixed a dead-code bug: `reason === "resume" || reason === "reload" || "fork"` was always truthy (the last operand is a non-empty string literal), so session stats never reset on fresh sessions.
16
- - oh-my-pi adaptation: its `session_start` carries no `reason` and fires only on initial load; mid-process switches arrive as a separate `session_switch` event with reason `new|resume|fork`. The extension now handles both events; on pi the extra registration is a no-op (its runtime accepts arbitrary event names and never dispatches it).
17
-
18
- ### Testing
19
- - Added mock-`ExtensionAPI` runtime tests: status message payload shape (including the `attribution` regression guard) and session stats continuity across `reload`/`resume`/`fork`/`session_switch` boundaries, sandboxed via `XDG_CONFIG_HOME` so they never touch `~/.pi`, `~/.omp`, or the machine caveman config.
20
-
21
- ## [0.4.0] - 2026-10-10
22
-
23
- ### Added & Changed
24
- - **Three Skills, One Mode Model (Upstream 3.2.0 Sync)**:
25
- - Replaced the 6 intensity levels with 3 dedicated standalone skills:
26
- - `caveman`: Default smart terse voice, adhering to 9 core rules.
27
- - `ultracave`: Grammar stripped, fragments only, each fact once.
28
- - `megacave`: Classical Chinese (文言文) register with character minimization.
29
- - Shipped `skills/ultracave/` and `skills/megacave/` skills directories alongside `skills/caveman/`.
30
- - Added `canonicalMode()` to seamlessly map legacy mode names (`full`, `lite`, `ultra`, `wenyan*`) to the new three-skill architecture.
31
- - **Upstream 3.2.0 Core Rules**:
32
- - Rule 6: Retain existing file comments in full unless explicitly asked to modify them.
33
- - Rule 7: Bounded tool runs — no narration between routine tool calls; single-line phase notices.
34
- - Exceptions: Always use full sentences when offering options or asking clarifying questions to the user.
35
- - Updated reinforcement thesis line extraction to synchronize with skill definitions.
36
- - **Commands & UX**:
37
- - Added dedicated `/ultracave` and `/megacave` slash commands.
38
- - Supported `/caveman status` as a first-class subcommand.
39
- - Non-permanent status bar: clears status bar on mode changes and session start while providing clean transient toast notifications (`ui.notify`).
40
- - **Testing**:
41
- - Comprehensive unit test suite covering mode canonicalization, three-skill loading, negation boundaries, and slash command parsing without logic duplication.
42
-
43
- ## [0.3.0] - 2026-09-17
44
-
45
- ### Changed & Improved
46
- - **Upstream Core Sync**: Synchronized `skills/caveman/SKILL.md` with upstream Caveman ruleset:
47
- - Added ASD-STE100 Simplified Technical English clarity register (sentences ≤20 words, imperative instructions, unambiguous terms).
48
- - Added explicit reply-language precedence (honoring user/project language directives while preserving technical terms).
49
- - Removed meta-announcements and boilerplate prefixes (`me caveman think`, `Caveman:` tags).
50
- - Shortened skill description and token-optimized punctuation.
51
- - **Host Adaptation (pi & oh-my-pi)**:
52
- - Dynamic host directory resolution (`~/.pi` vs `~/.omp`) for flags and logs.
53
- - Gated prompt reinforcement: injects full ruleset on activation or mode change; subsequent turns use lightweight one-line reminders to save tokens and avoid prompt cache misses.
54
- - Session persistence: preserves mid-session modes across compactions, reloads, and forks.
55
- - Removed unsupported `attribution: "system"` property from injected custom messages.
56
- - Added `"omp"` manifest and optional peer dependencies in `package.json`.
57
- - **Robust Mode Parsing**:
58
- - Integrated upstream gap whitelist (`ACTIVATION_GAP`) to prevent false positives on phrases like "i want to start building a caveman-themed game".
59
- - Added clause-bounded negation detection (`don't activate caveman` won't trigger; `don't use vim, activate caveman` works).
60
- - **Pruning**:
61
- - Removed `caveman-compress` skill and Python scripts to keep the package lightweight and focused purely on core caveman communication.
62
-
63
- ## [0.2.1] - 2026-08-21
64
-
65
- ### Changed & Improved
66
- - **Prompt Rules Upstream Sync**: Synchronized core compression rules with upstream Caveman v2.2.0 — added anti-expansion guards (no fake broken grammar), verb preservation on equal token cost, and clear external issue/ticket boundaries.
67
- - **Robust Mode Parser**: Added quoted-span disambiguation to prevent quoted text like `"stop caveman"` from triggering deactivation; added punctuation and quote normalization for `/caveman` arguments.
68
- - **Enhanced `caveman-compress`**: Fixed Windows `cp1252` encoding exceptions, improved CommonMark code fence parsing, and preserved original file line endings (CRLF/LF) atomically.
69
- - **Skill Slimming**: Trimmed redundant cloud-dependent and generic workflow skills to reduce initial system prompt index overhead by ~75%.
70
-
71
- ## [0.2.0] - 2026-08-16
72
-
73
- ### Added
74
- - Multi-skill integration for pi package format.
75
- - Namespaced slash commands and extended mode parsing.
76
- - Published package under `@izhimu/pi-caveman`.
77
-
78
- ## [0.1.0] - 2026-07-15
79
-
80
- ### Added
81
- - Initial release of pi-caveman extension for the Pi coding agent.
82
- - 6 compression intensity levels (`lite`, `full`, `ultra`, `wenyan-lite`, `wenyan-full`, `wenyan-ultra`).
83
- - Per-turn prompt reinforcement and auto-activation support.
84
- - Session token tracking and estimated savings display via `/caveman-status`.
1
+ # Changelog
2
+
3
+ All notable changes to `@izhimu/pi-caveman` will be documented in this file.
4
+
5
+ ## [0.6.0] - 2026-11-17
6
+
7
+ ### Added & Changed
8
+ - **Upstream hook sync (`v3.2.0..9b243662`)**: `defaultMode` now accepts UTF-8 BOM, UTF-16LE BOM, comments, and trailing commas. Mode writes preserve other JSONC settings. Repo config files without a recognized `defaultMode` no longer hide a sibling or parent config. Windows reads `%APPDATA%\caveman\config.json`, then `~/.config/caveman/config.json`. Missing skill files now fall back to the complete core ruleset instead of a one-line reminder.
9
+ - **Configurable reinforcement**: `CAVEMAN_REINFORCE` and the `reinforce` config field can disable repeated per-turn reminders. Activation and mode changes still inject the full skill ruleset. Resolution order is environment, nearest repo config naming the setting, user config, then enabled.
10
+
11
+ ### Testing
12
+ - Added sandboxed regressions for hand-edited config parsing, config precedence, Windows fallback, and reinforcement behavior. Verified all host API calls against current pi and oh-my-pi source; no host adaptation was needed.
13
+
14
+ ## [0.5.0] - 2026-10-24
15
+
16
+ ### Removed
17
+ - **Standalone `/ultracave` and `/megacave` slash commands** (including their plugin-namespaced `/caveman:ultracave` / `/caveman:megacave` forms and the `input` interception branches). The modes themselves are unchanged and remain reachable via `/caveman ultracave`, `/caveman megacave` (plus legacy aliases `ultra`, `wenyan*`) and natural-language triggers.
18
+
19
+ ## [0.4.1] - 2026-10-24
20
+
21
+ ### Fixed
22
+ - **Host API conformance for `sendMessage`**: the `/caveman status` summary is now sent as `{ customType: "caveman-status", content, display: false }`, matching pi's `SendMessageHandler` payload (which requires `customType`/`display` and has no `attribution` field). The old call passed an unsupported `attribution: "user"` and omitted `customType`, so pi persisted a session entry with `customType: undefined`. oh-my-pi accepts both shapes.
23
+ - **Session boundary handling**:
24
+ - Fixed a dead-code bug: `reason === "resume" || reason === "reload" || "fork"` was always truthy (the last operand is a non-empty string literal), so session stats never reset on fresh sessions.
25
+ - oh-my-pi adaptation: its `session_start` carries no `reason` and fires only on initial load; mid-process switches arrive as a separate `session_switch` event with reason `new|resume|fork`. The extension now handles both events; on pi the extra registration is a no-op (its runtime accepts arbitrary event names and never dispatches it).
26
+
27
+ ### Testing
28
+ - Added mock-`ExtensionAPI` runtime tests: status message payload shape (including the `attribution` regression guard) and session stats continuity across `reload`/`resume`/`fork`/`session_switch` boundaries, sandboxed via `XDG_CONFIG_HOME` so they never touch `~/.pi`, `~/.omp`, or the machine caveman config.
29
+
30
+ ## [0.4.0] - 2026-10-10
31
+
32
+ ### Added & Changed
33
+ - **Three Skills, One Mode Model (Upstream 3.2.0 Sync)**:
34
+ - Replaced the 6 intensity levels with 3 dedicated standalone skills:
35
+ - `caveman`: Default smart terse voice, adhering to 9 core rules.
36
+ - `ultracave`: Grammar stripped, fragments only, each fact once.
37
+ - `megacave`: Classical Chinese (文言文) register with character minimization.
38
+ - Shipped `skills/ultracave/` and `skills/megacave/` skills directories alongside `skills/caveman/`.
39
+ - Added `canonicalMode()` to seamlessly map legacy mode names (`full`, `lite`, `ultra`, `wenyan*`) to the new three-skill architecture.
40
+ - **Upstream 3.2.0 Core Rules**:
41
+ - Rule 6: Retain existing file comments in full unless explicitly asked to modify them.
42
+ - Rule 7: Bounded tool runs — no narration between routine tool calls; single-line phase notices.
43
+ - Exceptions: Always use full sentences when offering options or asking clarifying questions to the user.
44
+ - Updated reinforcement thesis line extraction to synchronize with skill definitions.
45
+ - **Commands & UX**:
46
+ - Added dedicated `/ultracave` and `/megacave` slash commands.
47
+ - Supported `/caveman status` as a first-class subcommand.
48
+ - Non-permanent status bar: clears status bar on mode changes and session start while providing clean transient toast notifications (`ui.notify`).
49
+ - **Testing**:
50
+ - Comprehensive unit test suite covering mode canonicalization, three-skill loading, negation boundaries, and slash command parsing without logic duplication.
51
+
52
+ ## [0.3.0] - 2026-09-17
53
+
54
+ ### Changed & Improved
55
+ - **Upstream Core Sync**: Synchronized `skills/caveman/SKILL.md` with upstream Caveman ruleset:
56
+ - Added ASD-STE100 Simplified Technical English clarity register (sentences ≤20 words, imperative instructions, unambiguous terms).
57
+ - Added explicit reply-language precedence (honoring user/project language directives while preserving technical terms).
58
+ - Removed meta-announcements and boilerplate prefixes (`me caveman think`, `Caveman:` tags).
59
+ - Shortened skill description and token-optimized punctuation.
60
+ - **Host Adaptation (pi & oh-my-pi)**:
61
+ - Dynamic host directory resolution (`~/.pi` vs `~/.omp`) for flags and logs.
62
+ - Gated prompt reinforcement: injects full ruleset on activation or mode change; subsequent turns use lightweight one-line reminders to save tokens and avoid prompt cache misses.
63
+ - Session persistence: preserves mid-session modes across compactions, reloads, and forks.
64
+ - Removed unsupported `attribution: "system"` property from injected custom messages.
65
+ - Added `"omp"` manifest and optional peer dependencies in `package.json`.
66
+ - **Robust Mode Parsing**:
67
+ - Integrated upstream gap whitelist (`ACTIVATION_GAP`) to prevent false positives on phrases like "i want to start building a caveman-themed game".
68
+ - Added clause-bounded negation detection (`don't activate caveman` won't trigger; `don't use vim, activate caveman` works).
69
+ - **Pruning**:
70
+ - Removed `caveman-compress` skill and Python scripts to keep the package lightweight and focused purely on core caveman communication.
71
+
72
+ ## [0.2.1] - 2026-08-21
73
+
74
+ ### Changed & Improved
75
+ - **Prompt Rules Upstream Sync**: Synchronized core compression rules with upstream Caveman v2.2.0 — added anti-expansion guards (no fake broken grammar), verb preservation on equal token cost, and clear external issue/ticket boundaries.
76
+ - **Robust Mode Parser**: Added quoted-span disambiguation to prevent quoted text like `"stop caveman"` from triggering deactivation; added punctuation and quote normalization for `/caveman` arguments.
77
+ - **Enhanced `caveman-compress`**: Fixed Windows `cp1252` encoding exceptions, improved CommonMark code fence parsing, and preserved original file line endings (CRLF/LF) atomically.
78
+ - **Skill Slimming**: Trimmed redundant cloud-dependent and generic workflow skills to reduce initial system prompt index overhead by ~75%.
79
+
80
+ ## [0.2.0] - 2026-08-16
81
+
82
+ ### Added
83
+ - Multi-skill integration for pi package format.
84
+ - Namespaced slash commands and extended mode parsing.
85
+ - Published package under `@izhimu/pi-caveman`.
86
+
87
+ ## [0.1.0] - 2026-07-15
88
+
89
+ ### Added
90
+ - Initial release of pi-caveman extension for the Pi coding agent.
91
+ - 6 compression intensity levels (`lite`, `full`, `ultra`, `wenyan-lite`, `wenyan-full`, `wenyan-ultra`).
92
+ - Per-turn prompt reinforcement and auto-activation support.
93
+ - Session token tracking and estimated savings display via `/caveman-status`.
package/README.md CHANGED
@@ -1,131 +1,134 @@
1
- # pi-caveman
2
-
3
- [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
4
- [![pi extension](https://img.shields.io/badge/pi-extension-green.svg)](https://github.com/earendil-works/pi)
5
- [![npm version](https://img.shields.io/npm/v/@izhimu/pi-caveman.svg)](https://www.npmjs.com/package/@izhimu/pi-caveman)
6
-
7
- Caveman mode for [pi](https://github.com/earendil-works/pi) and [oh-my-pi](https://github.com/can1357/oh-my-pi). Ultra-compressed communication — cuts **65% output tokens** (measured) while maintaining full technical accuracy.
8
-
9
- Upstream: [JuliusBrussee/caveman](https://github.com/JuliusBrussee/caveman)
10
-
11
- ## Features
12
-
13
- - **Auto-activates** on every pi / oh-my-pi session (default: `caveman` mode)
14
- - **3 dedicated skills** — `caveman` (smart concise voice), `ultracave` (payload only, fragments), and `megacave` (文言文 Classical Chinese)
15
- - **9 core upstream 3.2.0 rules** — answer first, kill ceremony, STE clarity, preserved comments, bounded tool runs
16
- - **Per-turn reinforcement** keeps the model concise without prompt bloat or cache misses
17
- - **Natural language triggers** — "talk like caveman", "be brief", "stop caveman", "normal mode" (with negation guard and gap whitelist)
18
- - **Direct persistence & aliases** — `/caveman <mode>` instantly applies and persists; legacy aliases (`full`, `lite`, `ultra`, `wenyan`) seamlessly mapped
19
- - **Token savings stats** — tracks session output tokens and estimated savings via `/caveman status` or `/caveman-status`
20
- ## Install
21
-
22
- ### npm (recommended)
23
-
24
- For pi:
25
- ```bash
26
- pi install @izhimu/pi-caveman
27
- ```
28
-
29
- For oh-my-pi (omp):
30
- ```bash
31
- omp plugin install @izhimu/pi-caveman
32
- ```
33
-
34
- ### From git
35
-
36
- ```bash
37
- # Global (pi)
38
- pi install git:github.com/izhimu/pi-caveman
39
-
40
- # Project-local (pi)
41
- pi install git:github.com/izhimu/pi-caveman -l
42
- ```
43
-
44
- ### Quick test (no install)
45
-
46
- ```bash
47
- pi -e ./extensions/caveman.ts
48
- # or
49
- omp -e ./extensions/caveman.ts
50
- ```
51
-
52
- ## Commands
53
-
54
- | Command | Effect |
55
- |---------|--------|
56
- | `/caveman` | Activate default caveman mode (persists) |
57
- | `/caveman <mode>` | Switch mode: `caveman`, `ultracave`, `megacave`, `off`, `status` (persists) |
58
- | `/caveman status` | Show current mode, session token usage, and config paths |
59
- | `/caveman-status` | Alias for `/caveman status` |
60
- | `/caveman off` | Deactivate caveman mode (persists) |
61
-
62
- All `/caveman` mode switches automatically persist to user config (`~/.config/caveman/config.json` or `%APPDATA%\caveman\config.json`). Legacy aliases (`full`, `lite`, `ultra`, `wenyan*`) are transparently mapped.
63
-
64
- Natural-language triggers also work: "talk like caveman", "be brief", "less tokens", "stop caveman", "normal mode".
65
-
66
- ## Skills & Modes
67
-
68
- | Skill / Mode | Description | Savings |
69
- |--------------|-------------|---------|
70
- | **`caveman`** | Smart caveman voice. Terse, active voice, 9 upstream 3.2.0 rules (default) | ~65% tokens |
71
- | **`ultracave`** | Maximum compression. Grammar stripped, payload only, fragments | ~75% tokens |
72
- | **`megacave`** | Classical Chinese (文言文). Drastically fewer characters on screen | ~80% tokens |
73
-
74
- ### Examples
75
-
76
- **Q: "Why does my React component re-render?"**
77
-
78
- - **caveman:** "New object ref each render. Inline object prop = new ref = re-render. Wrap in `useMemo`."
79
- - **ultracave:** "Inline obj prop, new ref, re-render. `useMemo`."
80
- - **megacave:** "每繪新生對象參照,故重繪;以 `useMemo` 包之則免。"
81
- ## Configuration
82
-
83
- Switch and persist directly with `/caveman <mode>` (e.g. `/caveman ultra`).
84
-
85
- Default mode resolution order:
86
-
87
- 1. `CAVEMAN_DEFAULT_MODE` environment variable
88
- 2. Repo-local: `.caveman/config.json` or `.caveman.json` (walks up to root)
89
- 3. User config: `~/.config/caveman/config.json` (or `%APPDATA%\caveman\config.json` on Windows)
90
- 4. `caveman` (fallback default)
91
-
92
- Manual config file format:
93
- ```json
94
- {
95
- "defaultMode": "ultracave"
96
- }
97
- ```
98
-
99
- ## How It Works
100
-
101
- pi and oh-my-pi load extensions and skills declared in `package.json` (`pi` / `omp`). This extension hooks into four lifecycle events:
102
-
103
- 1. **`session_start`** — writes mode flag, notifies user via toast, preserves mid-session modes across compactions/reloads
104
- 2. **`before_agent_start`** — injects full skill ruleset on activation/mode-switch, and lightweight reminders on subsequent turns
105
- 3. **`input`** — intercepts `/caveman` commands and natural-language triggers (with negation and clause-boundary guards)
106
- 4. **`turn_end`** — accumulates token usage and savings stats
107
-
108
- ## Project Structure
109
-
110
- ```
111
- pi-caveman/
112
- ├── extensions/
113
- │ └── caveman.ts # pi & omp ExtensionAPI integration & mode manager
114
- ├── skills/
115
- │ ├── caveman/ # Standard caveman voice (SKILL.md)
116
- │ ├── ultracave/ # Grammar-stripped fragments (SKILL.md)
117
- │ └── megacave/ # Classical Chinese 文言文 (SKILL.md)
118
- ├── CHANGELOG.md
119
- ├── package.json # pi & omp package manifest
120
- ├── tsconfig.json
121
- ├── LICENSE
122
- └── README.md
123
- ```
124
-
125
- ## Changelog
126
-
127
- See [CHANGELOG.md](./CHANGELOG.md) for release history.
128
-
129
- ## License
130
-
131
- [MIT](LICENSE) © [izhimu](https://github.com/izhimu)
1
+ # pi-caveman
2
+
3
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
4
+ [![pi extension](https://img.shields.io/badge/pi-extension-green.svg)](https://github.com/earendil-works/pi)
5
+ [![npm version](https://img.shields.io/npm/v/@izhimu/pi-caveman.svg)](https://www.npmjs.com/package/@izhimu/pi-caveman)
6
+
7
+ Caveman mode for [pi](https://github.com/earendil-works/pi) and [oh-my-pi](https://github.com/can1357/oh-my-pi). Ultra-compressed communication — cuts **65% output tokens** (measured) while maintaining full technical accuracy.
8
+
9
+ Upstream: [JuliusBrussee/caveman](https://github.com/JuliusBrussee/caveman)
10
+
11
+ ## Features
12
+
13
+ - **Auto-activates** on every pi / oh-my-pi session (default: `caveman` mode)
14
+ - **3 dedicated skills** — `caveman` (smart concise voice), `ultracave` (payload only, fragments), and `megacave` (文言文 Classical Chinese)
15
+ - **9 core upstream 3.2.0 rules** — answer first, kill ceremony, STE clarity, preserved comments, bounded tool runs
16
+ - **Per-turn reinforcement** keeps the model concise without prompt bloat or cache misses
17
+ - **Natural language triggers** — "talk like caveman", "be brief", "stop caveman", "normal mode" (with negation guard and gap whitelist)
18
+ - **Direct persistence & aliases** — `/caveman <mode>` instantly applies and persists; legacy aliases (`full`, `lite`, `ultra`, `wenyan`) seamlessly mapped
19
+ - **Token savings stats** — tracks session output tokens and estimated savings via `/caveman status` or `/caveman-status`
20
+ ## Install
21
+
22
+ ### npm (recommended)
23
+
24
+ For pi:
25
+ ```bash
26
+ pi install @izhimu/pi-caveman
27
+ ```
28
+
29
+ For oh-my-pi (omp):
30
+ ```bash
31
+ omp plugin install @izhimu/pi-caveman
32
+ ```
33
+
34
+ ### From git
35
+
36
+ ```bash
37
+ # Global (pi)
38
+ pi install git:github.com/izhimu/pi-caveman
39
+
40
+ # Project-local (pi)
41
+ pi install git:github.com/izhimu/pi-caveman -l
42
+ ```
43
+
44
+ ### Quick test (no install)
45
+
46
+ ```bash
47
+ pi -e ./extensions/caveman.ts
48
+ # or
49
+ omp -e ./extensions/caveman.ts
50
+ ```
51
+
52
+ ## Commands
53
+
54
+ | Command | Effect |
55
+ |---------|--------|
56
+ | `/caveman` | Activate default caveman mode (persists) |
57
+ | `/caveman <mode>` | Switch mode: `caveman`, `ultracave`, `megacave`, `off`, `status` (persists) |
58
+ | `/caveman status` | Show current mode, session token usage, and config paths |
59
+ | `/caveman-status` | Alias for `/caveman status` |
60
+ | `/caveman off` | Deactivate caveman mode (persists) |
61
+
62
+ All `/caveman` mode switches automatically persist to user config (`~/.config/caveman/config.json` or `%APPDATA%\caveman\config.json`). Legacy aliases (`full`, `lite`, `ultra`, `wenyan*`) are transparently mapped.
63
+
64
+ Natural-language triggers also work: "talk like caveman", "be brief", "less tokens", "stop caveman", "normal mode".
65
+
66
+ ## Skills & Modes
67
+
68
+ | Skill / Mode | Description | Savings |
69
+ |--------------|-------------|---------|
70
+ | **`caveman`** | Smart caveman voice. Terse, active voice, 9 upstream 3.2.0 rules (default) | ~65% tokens |
71
+ | **`ultracave`** | Maximum compression. Grammar stripped, payload only, fragments | ~75% tokens |
72
+ | **`megacave`** | Classical Chinese (文言文). Drastically fewer characters on screen | ~80% tokens |
73
+
74
+ ### Examples
75
+
76
+ **Q: "Why does my React component re-render?"**
77
+
78
+ - **caveman:** "New object ref each render. Inline object prop = new ref = re-render. Wrap in `useMemo`."
79
+ - **ultracave:** "Inline obj prop, new ref, re-render. `useMemo`."
80
+ - **megacave:** "每繪新生對象參照,故重繪;以 `useMemo` 包之則免。"
81
+ ## Configuration
82
+
83
+ Switch and persist directly with `/caveman <mode>` (e.g. `/caveman ultra`).
84
+
85
+ Default mode resolution order:
86
+
87
+ 1. `CAVEMAN_DEFAULT_MODE` environment variable
88
+ 2. Repo-local: nearest `.caveman/config.json` or `.caveman.json` naming `defaultMode` (walks up to root)
89
+ 3. User config: `~/.config/caveman/config.json` (or `%APPDATA%\caveman\config.json`, then `~/.config/caveman/config.json`, on Windows)
90
+ 4. `caveman` (fallback default)
91
+
92
+ Manual config file format:
93
+ ```json
94
+ {
95
+ "defaultMode": "ultracave",
96
+ "reinforce": true
97
+ }
98
+ ```
99
+
100
+ Config files accept UTF-8 BOM, UTF-16LE BOM, comments, and trailing commas. Set `reinforce` to `false` or `CAVEMAN_REINFORCE=0` to disable repeated per-turn reminders; activation and mode changes still inject the full skill ruleset. The switch resolves through `CAVEMAN_REINFORCE`, repo config, then user config.
101
+
102
+ ## How It Works
103
+
104
+ pi and oh-my-pi load extensions and skills declared in `package.json` (`pi` / `omp`). This extension hooks into four lifecycle events:
105
+
106
+ 1. **`session_start`** — writes mode flag, notifies user via toast, preserves mid-session modes across compactions/reloads
107
+ 2. **`before_agent_start`** — injects full skill ruleset on activation/mode-switch, and lightweight reminders on subsequent turns
108
+ 3. **`input`** — intercepts `/caveman` commands and natural-language triggers (with negation and clause-boundary guards)
109
+ 4. **`turn_end`** — accumulates token usage and savings stats
110
+
111
+ ## Project Structure
112
+
113
+ ```
114
+ pi-caveman/
115
+ ├── extensions/
116
+ │ └── caveman.ts # pi & omp ExtensionAPI integration & mode manager
117
+ ├── skills/
118
+ │ ├── caveman/ # Standard caveman voice (SKILL.md)
119
+ │ ├── ultracave/ # Grammar-stripped fragments (SKILL.md)
120
+ │ └── megacave/ # Classical Chinese 文言文 (SKILL.md)
121
+ ├── CHANGELOG.md
122
+ ├── package.json # pi & omp package manifest
123
+ ├── tsconfig.json
124
+ ├── LICENSE
125
+ └── README.md
126
+ ```
127
+
128
+ ## Changelog
129
+
130
+ See [CHANGELOG.md](./CHANGELOG.md) for release history.
131
+
132
+ ## License
133
+
134
+ [MIT](LICENSE) © [izhimu](https://github.com/izhimu)