pi-caveman 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# 🪨 pi-caveman
+
+**Why use many token when few do trick.**
+
+A [pi](https://github.com/mariozechner/pi) extension that cuts **~75% of output tokens** while keeping full technical accuracy. Based on [caveman](https://github.com/JuliusBrussee/caveman) by [Julius Brussee](https://github.com/JuliusBrussee).
+
+<table>
+<tr>
+<td width="50%">
+
+### 🗣️ Normal (69 tokens)
+
+> "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."
+
+</td>
+<td width="50%">
+
+### 🪨 Caveman (19 tokens)
+
+> "New object ref each render. Inline object prop = new ref = re-render. Wrap in `useMemo`."
+
+</td>
+</tr>
+</table>
+
+## Install
+
+```bash
+pi install git:github.com/jonjonrankin/pi-caveman
+```
+
+## Usage
+
+### Toggle Mode
+
+```
+/caveman              Toggle on (full) / off
+/caveman lite         Professional, no fluff
+/caveman full         Classic caveman (default)
+/caveman ultra        Maximum compression
+/caveman wenyan-lite  Semi-classical Chinese
+/caveman wenyan       Full 文言文
+/caveman wenyan-ultra Extreme 文言文
+/caveman off          Disable
+```
+
+### Settings
+
+```
+/caveman config       Open settings dialog
+```
+
+The config dialog lets you:
+
+- **Default level** — Set a level that activates automatically on every new session (e.g. `full` to always start in caveman mode)
+- **Show status bar** — Toggle the animated campfire indicator in the footer
+
+Settings are saved to `~/.pi/agent/caveman.json` and persist across all sessions.
+
+### Status Bar
+
+When active, an animated campfire flickers in the footer using colored braille characters:
+
+```
+⠠⠄ → ⠔⠂ → ⠊⠑ → ...   colored campfire embers (speed varies by level)
+```
+
+Colors cycle through red → orange → yellow → white-hot → ember using ANSI 256-color. Speed scales with intensity: 300ms for lite, 200ms for full, 100ms for ultra.
+
+## Levels
+
+| Level | Style | Example |
+|-------|-------|---------|
+| **Lite** | No filler. Full sentences. Professional but tight. | "Your component re-renders because you create a new object reference each render." |
+| **Full** | Drop articles, fragments OK. Classic caveman. | "New object ref each render. Wrap in `useMemo`." |
+| **Ultra** | Abbreviations, arrows, maximum compression. | "Inline obj prop → new ref → re-render. `useMemo`." |
+| **文言文 Lite** | Semi-classical Chinese, grammar intact. | "組件頻重繪，以每繪新生對象參照故。" |
+| **文言文** | Full classical terseness. | "物出新參照，致重繪。useMemo Wrap之。" |
+| **文言文 Ultra** | Extreme classical compression. | "新參照→重繪。useMemo Wrap。" |
+
+## How It Works
+
+The extension hooks `before_agent_start` to append caveman communication rules to the system prompt at the selected intensity. Within a session, the active level is stored as a custom session entry and restored on resume. Across sessions, persistent config (`~/.pi/agent/caveman.json`) provides the default level and status bar preference. Auto-clarity rules tell the model to drop caveman mode for security warnings or irreversible actions.
+
+## Credits
+
+Based on [caveman](https://github.com/JuliusBrussee/caveman) by [Julius Brussee](https://github.com/JuliusBrussee).
+
+## License
+
+MIT

package/extensions/caveman.ts

@@ -0,0 +1,310 @@
+/**
+ * pi-caveman — why use many token when few do trick
+ *
+ * A pi extension that cuts ~75% of output tokens while keeping full technical
+ * accuracy. Based on https://github.com/JuliusBrussee/caveman
+ *
+ * Commands:
+ *   /caveman [level]  Toggle caveman mode or set intensity
+ *   /caveman config   Open settings dialog (default level, status bar toggle)
+ */
+
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { getSettingsListTheme } from "@mariozechner/pi-coding-agent";
+import { Container, type SettingItem, SettingsList, Text } from "@mariozechner/pi-tui";
+
+// ---------------------------------------------------------------------------
+// Levels
+// ---------------------------------------------------------------------------
+
+const LEVELS = ["off", "lite", "full", "ultra", "wenyan-lite", "wenyan", "wenyan-ultra"] as const;
+type Level = (typeof LEVELS)[number];
+
+// ---------------------------------------------------------------------------
+// Persistent config (survives across sessions)
+// ---------------------------------------------------------------------------
+
+interface CavemanConfig {
+	/** Level to apply on new sessions. "off" means don't auto-enable. */
+	defaultLevel: Level;
+	/** Whether to show the animated footer status. */
+	showStatus: boolean;
+}
+
+const CONFIG_PATH = join(homedir(), ".pi", "agent", "caveman.json");
+const DEFAULT_CONFIG: CavemanConfig = { defaultLevel: "off", showStatus: true };
+
+async function loadConfig(): Promise<CavemanConfig> {
+	try {
+		const raw = await readFile(CONFIG_PATH, "utf8");
+		const parsed = JSON.parse(raw);
+		return {
+			defaultLevel: LEVELS.includes(parsed.defaultLevel) ? parsed.defaultLevel : DEFAULT_CONFIG.defaultLevel,
+			showStatus: typeof parsed.showStatus === "boolean" ? parsed.showStatus : DEFAULT_CONFIG.showStatus,
+		};
+	} catch {
+		return { ...DEFAULT_CONFIG };
+	}
+}
+
+async function saveConfig(config: CavemanConfig): Promise<void> {
+	await mkdir(join(homedir(), ".pi", "agent"), { recursive: true });
+	await writeFile(CONFIG_PATH, JSON.stringify(config, null, 2) + "\n", "utf8");
+}
+
+// ---------------------------------------------------------------------------
+// Animated status bar — campfire with 256-color fire palette
+// ---------------------------------------------------------------------------
+
+interface Animation {
+	frames: string[];
+	label: string;
+	/** ms between frames */
+	interval: number;
+}
+
+const R = "\x1b[38;5;196m"; // red
+const O = "\x1b[38;5;208m"; // orange
+const Y = "\x1b[38;5;220m"; // yellow
+const W = "\x1b[38;5;230m"; // white-hot
+const E = "\x1b[38;5;52m";  // ember (dark red)
+const X = "\x1b[0m";         // reset
+
+const FIRE_FRAMES = [
+	`${R}⠠${O}⠄${X}`,
+	`${O}⠔${Y}⠂${X}`,
+	`${Y}⠊${W}⠑${X}`,
+	`${W}⠑${Y}⠊${X}`,
+	`${Y}⠂${O}⠔${X}`,
+	`${O}⠄${R}⠠${X}`,
+	`${R}⠠${E}⠄${X}`,
+	`${E}⠔${R}⠂${X}`,
+];
+
+const ANIMATIONS: Record<Exclude<Level, "off">, Animation> = {
+	lite:          { frames: FIRE_FRAMES, label: "LITE",   interval: 300 },
+	full:          { frames: FIRE_FRAMES, label: "CAVEMAN", interval: 200 },
+	ultra:         { frames: FIRE_FRAMES, label: "ULTRA",  interval: 100 },
+	"wenyan-lite": { frames: FIRE_FRAMES, label: "文言",    interval: 300 },
+	wenyan:        { frames: FIRE_FRAMES, label: "文言文",   interval: 200 },
+	"wenyan-ultra":{ frames: FIRE_FRAMES, label: "文言文極",  interval: 100 },
+};
+
+// ---------------------------------------------------------------------------
+// System prompt fragments
+// ---------------------------------------------------------------------------
+
+const BASE = `\
+IMPORTANT: You are in CAVEMAN MODE. Respond terse like smart caveman. \
+All technical substance stay. Only fluff die.
+
+Rules:
+- Drop articles (a/an/the), filler (just/really/basically/actually/simply), \
+pleasantries, hedging
+- Fragments OK. Short synonyms preferred. Technical terms exact
+- Code blocks unchanged. Errors quoted exact
+- Pattern: [thing] [action] [reason]. [next step].
+
+Bad: "Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by..."
+Good: "Bug in auth middleware. Token expiry check use \`<\` not \`<=\`. Fix:"`;
+
+const INTENSITY: Record<Exclude<Level, "off">, string> = {
+	lite: `\
+Level: LITE — No filler/hedging. Keep articles + full sentences. Professional but tight.
+Example: "Your component re-renders because you create a new object reference each render. Wrap it in \`useMemo\`."`,
+
+	full: `\
+Level: FULL — Drop articles, fragments OK, short synonyms. Classic caveman.
+Example: "New object ref each render. Inline object prop = new ref = re-render. Wrap in \`useMemo\`."`,
+
+	ultra: `\
+Level: ULTRA — Abbreviate (DB/auth/config/req/res/fn/impl), strip conjunctions, arrows for causality (X → Y).
+Example: "Inline obj prop → new ref → re-render. \`useMemo\`."`,
+
+	"wenyan-lite": `\
+Level: 文言文 LITE — Semi-classical Chinese. Grammar intact, filler gone. Technical terms in English.
+Example: "組件頻重繪，以每繪新生對象參照故。以 useMemo 包之。"`,
+
+	wenyan: `\
+Level: 文言文 FULL — Maximum classical terseness. 80-90% character reduction. Technical terms in English.
+Example: "物出新參照，致重繪。useMemo Wrap之。"`,
+
+	"wenyan-ultra": `\
+Level: 文言文 ULTRA — Extreme classical compression. Technical terms in English.
+Example: "新參照→重繪。useMemo Wrap。"`,
+};
+
+const SAFETY = `\
+Auto-clarity: drop caveman for security warnings, irreversible action confirmations, \
+or when user is confused. Resume after.
+Boundaries: write normal code. Only compress explanations. "stop caveman" or "normal mode" reverts.`;
+
+// ---------------------------------------------------------------------------
+// Extension
+// ---------------------------------------------------------------------------
+
+export default function caveman(pi: ExtensionAPI) {
+	let level: Level = "off";
+	let config: CavemanConfig = { ...DEFAULT_CONFIG };
+	let timer: ReturnType<typeof setInterval> | null = null;
+	let frameIndex = 0;
+
+	// -- Animation helpers --
+
+	function stopAnimation() {
+		if (timer) {
+			clearInterval(timer);
+			timer = null;
+		}
+		frameIndex = 0;
+	}
+
+	function syncStatus(ctx: Pick<ExtensionContext, "ui">) {
+		stopAnimation();
+		const theme = ctx.ui.theme;
+
+		if (level === "off" || !config.showStatus) {
+			ctx.ui.setStatus("caveman", "");
+			return;
+		}
+
+		const anim = ANIMATIONS[level];
+
+		const renderFrame = () => {
+			const icon = anim.frames[frameIndex % anim.frames.length]!;
+			ctx.ui.setStatus("caveman", icon + " " + theme.fg("muted", "caveman level: ") + theme.fg("text", anim.label));
+			frameIndex++;
+		};
+
+		renderFrame();
+		timer = setInterval(renderFrame, anim.interval);
+	}
+
+	// -- Restore state on session load --
+
+	pi.on("session_start", async (_event, ctx) => {
+		config = await loadConfig();
+
+		// Check for session-level override first (resuming a session)
+		let sessionLevel: Level | null = null;
+		for (const entry of ctx.sessionManager.getEntries()) {
+			if (entry.type === "custom" && entry.customType === "caveman-level") {
+				sessionLevel = (entry.data as { level: Level })?.level ?? null;
+			}
+		}
+
+		if (sessionLevel !== null) {
+			// Resuming — use session state
+			level = sessionLevel;
+		} else if (config.defaultLevel !== "off") {
+			// New session — apply default from config
+			level = config.defaultLevel;
+			pi.appendEntry("caveman-level", { level });
+		}
+
+		syncStatus(ctx);
+	});
+
+	pi.on("session_shutdown", async () => {
+		stopAnimation();
+	});
+
+	// -- /caveman command --
+
+	pi.registerCommand("caveman", {
+		description: "Toggle caveman mode, set level, or 'config' to open settings",
+		handler: async (args, ctx) => {
+			const arg = args?.trim().toLowerCase();
+
+			// Open config dialog
+			if (arg === "config") {
+				await openConfig(ctx);
+				return;
+			}
+
+			if (!arg) {
+				level = level === "off" ? "full" : "off";
+			} else if (LEVELS.includes(arg as Level)) {
+				level = arg as Level;
+			} else {
+				ctx.ui.notify(`Unknown: "${arg}". Use: ${LEVELS.join(", ")} or config`, "error");
+				return;
+			}
+
+			pi.appendEntry("caveman-level", { level });
+			syncStatus(ctx);
+
+			ctx.ui.notify(
+				level === "off" ? "Caveman mode off." : `Caveman: ${ANIMATIONS[level].label}`,
+				"info",
+			);
+		},
+	});
+
+	// -- /caveman config: interactive SettingsList --
+
+	async function openConfig(ctx: ExtensionContext) {
+		config = await loadConfig();
+
+		await ctx.ui.custom((_tui, theme, _kb, done) => {
+			const items: SettingItem[] = [
+				{
+					id: "defaultLevel",
+					label: "Default level for new sessions",
+					currentValue: config.defaultLevel,
+					values: [...LEVELS],
+				},
+				{
+					id: "showStatus",
+					label: "Show animated status bar",
+					currentValue: config.showStatus ? "on" : "off",
+					values: ["on", "off"],
+				},
+			];
+
+			const container = new Container();
+			container.addChild(new Text(theme.fg("accent", theme.bold(" Caveman Config")), 0, 0));
+			container.addChild(new Text(theme.fg("dim", " Saved to ~/.pi/agent/caveman.json"), 0, 0));
+			container.addChild(new Text("", 0, 0));
+
+			const settingsList = new SettingsList(
+				items,
+				Math.min(items.length + 2, 10),
+				getSettingsListTheme(),
+				(id, newValue) => {
+					if (id === "defaultLevel" && LEVELS.includes(newValue as Level)) {
+						config.defaultLevel = newValue as Level;
+					} else if (id === "showStatus") {
+						config.showStatus = newValue === "on";
+					}
+					saveConfig(config);
+					syncStatus(ctx);
+				},
+				() => done(undefined),
+			);
+
+			container.addChild(settingsList);
+			container.addChild(new Text(theme.fg("dim", " ←→ change • esc close"), 0, 0));
+
+			return {
+				render: (w: number) => container.render(w),
+				invalidate: () => container.invalidate(),
+				handleInput: (data: string) => {
+					settingsList.handleInput?.(data);
+				},
+			};
+		});
+	}
+
+	// -- Inject caveman rules into system prompt --
+
+	pi.on("before_agent_start", async (event) => {
+		if (level === "off") return;
+		return {
+			systemPrompt: `${event.systemPrompt}\n\n${BASE}\n\n${INTENSITY[level]}\n\n${SAFETY}`,
+		};
+	});
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "pi-caveman",
+  "version": "1.0.0",
+  "description": "Why use many token when few do trick. Caveman mode for pi — cuts ~75% output tokens while keeping full technical accuracy.",
+  "keywords": ["pi-package", "pi-extension", "caveman", "token-saving"],
+  "license": "MIT",
+  "author": "jonjonrankin",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jonjonrankin/pi-caveman.git"
+  },
+  "homepage": "https://github.com/jonjonrankin/pi-caveman",
+  "files": [
+    "extensions",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": ["./extensions"]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*"
+  }
+}