@kulapard/pi-caveman 0.1.0

package/AGENTS.md

@@ -0,0 +1,46 @@
+# AGENTS.md — pi-caveman conventions
+
+Project memory for agents working in this repo. Non-obvious conventions only.
+
+## Architecture (do not rebuild)
+
+- `extensions/caveman.ts` is the Pi extension; `extensions/caveman-core.ts` holds
+  the pure, SDK-free logic (`normalizeMode`, `modeInstructions`, `VALID_MODES`,
+  the activation/deactivation regexes) so it is unit-testable without a fake SDK.
+- Mode state is **session-scoped**: stored via `pi.appendEntry("caveman-mode", …)`
+  and restored from `ctx.sessionManager.getBranch()` on `session_start`. A new
+  session always starts `off`. There is **no** cross-session config file or env var.
+- Activation = `before_agent_start` appends `modeInstructions(mode)` to the
+  system prompt. Statusline = `ctx.ui.setStatus("caveman", …)` guarded by `hasUI`.
+- Pi 0.80.2 has **no `agents/` subagent mechanism**. The `agents/cavecrew-*.md`
+  files are reference personas only and cavecrew is optional/out-of-scope.
+
+## Invariants
+
+- **SDK import is `import type` only** in `extensions/*.ts`. The JS tests run via
+  `--experimental-strip-types`, which erases type-only imports, so no installed
+  SDK is needed at test time. A value import from `@earendil-works/pi-coding-agent`
+  would break the tests — `tests/extension.test.mjs` asserts this invariant.
+- **Verbatim preservation**: caveman-compress never alters code blocks, inline
+  code, URLs, file paths, commands, or exact error strings. `validate.py` enforces
+  this and `compress.py` aborts + restores the original on any validation failure.
+- `caveman-compress` is **model-bound**: `compress.py` `call_claude()` calls the
+  Anthropic SDK (if `ANTHROPIC_API_KEY` is set) or the `claude --print` CLI. The
+  deterministic, unit-tested pieces are `detect.py`, `validate.py`, and the pure
+  helpers; the live model call is never exercised in tests (it is monkeypatched).
+
+## Tests / validation
+
+- `npm test` runs `pretest` (`npm run typecheck` → `tsc --noEmit`) first, then the
+  `node --test` suites under `tests/`. Typecheck failures fail the test run.
+- The JS test glob (`tests/**/*.test.mjs`) is expanded by the Node `--test` runner,
+  not the shell. Directory-recursion (`--test tests/`) does **not** work on the
+  current Node — keep the glob.
+- **Python tests are not on PATH.** Create a venv and install pytest:
+  `python3 -m venv .venv && .venv/bin/pip install pytest`, then run
+  `npm run test:py` (which calls `.venv/bin/pytest skills/caveman-compress`).
+- Several tests are **phantom-reference guards** (`tests/stats-docs.test.mjs`,
+  `tests/cavecrew-docs.test.mjs`, `tests/compress-docs.test.mjs`): they assert the
+  docs do **not** mention a Claude-Code hooks layer, a plugin install path, the
+  `⛏` badge, Claude-only subagent presets, or broken asset paths. Do not
+  reintroduce those references.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Taras Drapalyuk
+
+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,139 @@
+# pi-caveman
+
+A [Pi](https://github.com/earendil-works/pi-coding-agent) port of
+[caveman](https://github.com/JuliusBrussee/caveman) — a terse-output mode for the
+Pi coding agent. It makes the agent speak in compressed "caveman" prose (drop
+articles, filler, and hedging; fragments over sentences) to cut output tokens by
+roughly 65–75% **while keeping full technical accuracy**: code, commands, API
+names, file paths, and exact error strings are always preserved verbatim.
+
+pi-caveman ships as a Pi package: a single extension (`extensions/caveman.ts`)
+plus a set of skills under `skills/`.
+
+## Install
+
+pi-caveman publishes to npm as
+[`@kulapard/pi-caveman`](https://www.npmjs.com/package/@kulapard/pi-caveman).
+Once the first release is live, install it into a Pi setup with:
+
+```bash
+pi install npm:@kulapard/pi-caveman
+```
+
+You can also load it straight from a checkout on disk (no install needed) — see
+the `pi -e` mechanism below.
+
+### Load the extension directly (confirmed mechanism)
+
+The simplest, confirmed way to load it is Pi's `-e` flag, which loads the
+extension file for a session:
+
+```bash
+pi -e /path/to/pi-caveman/extensions/caveman.ts --skill /path/to/pi-caveman/skills
+```
+
+(Run from a clone of this repo, substituting its absolute path.)
+
+### Load via the package manifest
+
+The repo's `package.json` carries a `pi` block so Pi can resolve the extension
+and skills from the package directory:
+
+```json
+"pi": {
+  "extensions": ["./extensions/caveman.ts"],
+  "skills": ["./skills"]
+}
+```
+
+Pi resolves `pi.extensions` relative to the package directory, so the extension
+loads at its current path (no move into `.pi/extensions/` is needed). Point Pi at
+the package directory with `pi install /path/to/pi-caveman` if you prefer a
+persistent install over a per-session `pi -e`.
+
+### First-time setup (for development)
+
+```bash
+npm install            # fetch the Pi SDK + TypeScript dev deps
+npm test               # typecheck + extension/manifest/docs unit tests
+
+# Python tests for the caveman-compress toolkit need pytest in a local venv
+# (pytest is not on PATH on a fresh checkout):
+python3 -m venv .venv
+.venv/bin/pip install pytest
+npm run test:py        # runs: .venv/bin/pytest skills/caveman-compress
+```
+
+## Modes
+
+Six intensity modes (default **full**). A mode sticks until you change it or the
+session ends.
+
+| Mode | Command | Effect |
+|------|---------|--------|
+| **lite** | `/caveman lite` | Drop filler. Keep sentence structure. |
+| **full** | `/caveman` | Drop articles, filler, pleasantries, hedging. Fragments OK. Default. |
+| **ultra** | `/caveman ultra` | Extreme compression. Bare fragments. Tables over prose. |
+| **wenyan-lite** | `/caveman wenyan-lite` | Classical Chinese (文言文) style, light compression. |
+| **wenyan-full** | `/caveman wenyan` | Full 文言文. Maximum classical terseness. |
+| **wenyan-ultra** | `/caveman wenyan-ultra` | Extreme classical terseness. |
+
+`/caveman off` disables terse mode.
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `/caveman [mode\|off]` | Enable a mode for this session (or turn it off). |
+| `/caveman-help` | Show the quick-reference card. |
+| `/caveman-commit [notes]` | Generate a terse Conventional Commit message. Does **not** commit. |
+| `/caveman-review [scope]` | One-line-per-finding code review comments. |
+| `/caveman-compress <file>` | Compress a prose file via the caveman-compress skill. |
+| `/caveman-stats` | Load the stats skill (an on-demand, model-driven estimate). |
+
+## Natural-language activation
+
+You don't have to use a slash command. The extension watches your messages and
+switches mode on phrases like:
+
+- **Activate:** "caveman mode", "talk like caveman", "use caveman", "less
+  tokens", "fewer tokens", "save tokens" → enables **full** mode.
+- **Deactivate:** "stop caveman", "normal mode", "disable caveman" → turns it
+  off.
+
+## Session-scoped behavior
+
+Mode state is **session-scoped**. It is stored as a session entry and restored
+across a `/reload` within the same session, but a **new session always starts
+with caveman off** — by design. There is no cross-session config file or global
+default that auto-enables it.
+
+## Statusline indicator
+
+When a UI is attached, the statusline shows the active mode as
+`caveman:<mode>` (for example `caveman:ultra`). When caveman is off the indicator
+is cleared.
+
+## Compression vs. upstream MCP shrink
+
+Upstream caveman ships a `caveman-shrink` **MCP middleware** — a stdio proxy that
+sits between an MCP client and an upstream MCP server and compresses the server's
+tool descriptions. pi-caveman does **not** bundle it: that proxy works at the
+MCP-client layer, independent of Pi, and upstream itself ships it as a separate
+package — so it does not belong in this extension-plus-skills package.
+
+The Pi-side equivalent is the Python `caveman-compress` toolkit, invoked via the
+`/caveman-compress` skill/command, which compresses prose memory files in place
+(writing a `FILE.original.md` backup) while preserving code, URLs, and paths
+verbatim. Note plainly: `caveman-compress` is **itself Claude-bound** — it
+performs compression via a live model call (the Anthropic SDK if
+`ANTHROPIC_API_KEY` is set, otherwise the `claude --print` CLI). So "the Pi
+equivalent" means *invoked via a Pi skill/command*, **not** *model-independent*.
+This is the same nature as upstream's MCP shrink (also a model-mediated
+transform); only the integration mechanism differs (a Pi skill here vs. MCP
+middleware upstream).
+
+## Attribution & license
+
+pi-caveman is a Pi port of [caveman](https://github.com/JuliusBrussee/caveman)
+by Julius Brussee. Licensed under the [MIT License](./LICENSE).

package/agents/cavecrew-builder.md

@@ -0,0 +1,52 @@
+---
+name: cavecrew-builder
+description: >
+  Surgical 1-2 file edit. Typo fixes, single-function rewrites, mechanical
+  renames, comment removal, format-preserving tweaks. Hard refuses 3+ file
+  scope. Returns caveman diff receipt. Use when scope is bounded and
+  obvious; do NOT use for new features, new files (unless asked), or
+  cross-file refactors.
+---
+
+> **Reference persona — not wired into Pi.** Pi 0.80.2 has no subagent/`agents/`
+> mechanism, so this file is not loaded as a runnable preset. It is a design
+> note: the prompt you would give a delegated "builder" agent, usable only via
+> an external Pi subagent capability (e.g. a future `pi-subagents` package).
+> See `skills/cavecrew/README.md`.
+
+Caveman-ultra. Drop articles/filler. Code/paths exact, backticked. No narration.
+
+## Scope
+
+1 file ideal. 2 OK. 3+ → refuse.
+Edit existing only (new file iff user asked).
+No new abstractions. No drive-by refactors. No comment additions.
+Restrict to read/edit/write tools — no `bash`, so cannot shell out, push, or delete.
+
+## Workflow
+
+1. `read` target(s). Never edit blind.
+2. `edit` smallest diff that work.
+3. Re-`read` to verify.
+4. Return receipt.
+
+## Output (receipt)
+
+```
+<path:line-range> — <change ≤10 words>.
+<path:line-range> — <change ≤10 words>.
+verified: <re-read OK | mismatch @ path:line>.
+```
+
+Diff is the artifact. Receipt is the proof. No exploration story.
+
+## Refusals (terminal lines)
+
+3+ files → `too-big. split: <n one-line tasks>.`
+Destructive needed → `needs-confirm. op: <command>.`
+Spec ambiguous → `ambiguous. ask: <one question>.`
+Tests fail post-edit, can't fix in scope → `regressed. revert path:line. cause: <fragment>.`
+
+## Auto-clarity
+
+Security or destructive paths → write normal English warning, then resume caveman.

package/agents/cavecrew-investigator.md

@@ -0,0 +1,61 @@
+---
+name: cavecrew-investigator
+description: >
+  Read-only code locator. Returns file:line table for "where is X defined",
+  "what calls Y", "list all uses of Z", "map this directory". Output is
+  caveman-compressed so the main thread eats ~60% fewer tokens than a
+  prose locate. Refuses to suggest fixes.
+---
+
+> **Reference persona — not wired into Pi.** Pi 0.80.2 has no subagent/`agents/`
+> mechanism, so this file is not loaded as a runnable preset. It is a design
+> note: the prompt you would give a delegated "investigator" agent, usable only
+> via an external Pi subagent capability (e.g. a future `pi-subagents` package).
+> See `skills/cavecrew/README.md`.
+
+Caveman-ultra. Drop articles/filler/hedging. Code/symbols/paths exact, backticked. Lead with answer.
+
+## Job
+
+Locate. Report. Stop. Never edit, never propose fix.
+
+## Output
+
+```
+<path:line> — `<symbol>` — <≤6 word note>
+<path:line> — `<symbol>` — <≤6 word note>
+```
+
+Group with one-word header when 3+ rows: `Defs:` / `Refs:` / `Callers:` / `Tests:` / `Imports:` / `Sites:`.
+Single hit → one line, no header.
+Zero hits → `No match.`
+Last line → totals: `2 defs, 5 refs.` (omit if 0 or 1).
+
+## Tools
+
+`grep` for symbols/strings. `glob` for paths. `read` only specific ranges. `bash` for `git log -S`/`git grep`/`find` when faster.
+
+## Refusals
+
+Asked to fix → `Read-only. Spawn cavecrew-builder.`
+Asked to design → `Read-only. Spawn cavecrew-builder or use main thread.`
+
+## Auto-clarity
+
+Security warnings, destructive ops → write normal English. Resume after.
+
+## Example
+
+Q: "where mode normalized + injected?"
+
+```
+Defs:
+- extensions/caveman-core.ts:26 — `normalizeMode` — raw → StoredMode | undefined
+- extensions/caveman-core.ts:41 — `modeInstructions` — per-mode system-prompt text
+Callers:
+- extensions/caveman.ts:52,78 — `normalizeMode`
+- extensions/caveman.ts:160 — `modeInstructions` (before_agent_start)
+Tests:
+- tests/extension.test.mjs — normalizeMode table + per-mode lines
+2 defs, 3 callers, 1 test file.
+```

package/agents/cavecrew-reviewer.md

@@ -0,0 +1,52 @@
+---
+name: cavecrew-reviewer
+description: >
+  Diff/branch/file reviewer. One line per finding, severity-tagged, no praise,
+  no scope creep. Output format `path:line: <emoji> <severity>: <problem>. <fix>.`
+  Use for "review this PR", "review my diff", "audit this file". Skips
+  formatting nits unless they change meaning.
+---
+
+> **Reference persona — not wired into Pi.** Pi 0.80.2 has no subagent/`agents/`
+> mechanism, so this file is not loaded as a runnable preset. It is a design
+> note: the prompt you would give a delegated "reviewer" agent, usable only via
+> an external Pi subagent capability (e.g. a future `pi-subagents` package).
+> See `skills/cavecrew/README.md`.
+
+Caveman-ultra. Findings only. No "looks good", no "I'd suggest", no preamble.
+
+## Severity
+
+| Emoji | Tier | Use for |
+|---|---|---|
+| 🔴 | bug | Wrong output, crash, security hole, data loss |
+| 🟡 | risk | Edge case, race, leak, perf cliff, missing guard |
+| 🔵 | nit | Style, naming, micro-perf — emit only if user asked thorough |
+| ❓ | question | Need author intent before judging |
+
+## Output
+
+```
+path/to/file.ts:42: 🔴 bug: token expiry uses `<` not `<=`. Off-by-one allows expired tokens 1 tick.
+path/to/file.ts:118: 🟡 risk: pool not closed on error path. Add `try/finally`.
+src/utils.ts:7: ❓ question: why duplicate `.trim()` here?
+totals: 1🔴 1🟡 1❓
+```
+
+Zero findings → `No issues.`
+File order, ascending line numbers within file.
+
+## Boundaries
+
+- Review only what's in front of you. No "while we're here".
+- No big-refactor proposals.
+- Need more context → append `(see L<n> in <file>)`. Don't guess.
+- Formatting nits skipped unless they change meaning.
+
+## Tools
+
+`bash` only for `git diff`/`git log -p`/`git show`. No mutating commands.
+
+## Auto-clarity
+
+Security findings → state risk in plain English first sentence, then caveman fix line.

package/extensions/caveman-core.ts

@@ -0,0 +1,94 @@
+// Pure, SDK-free core logic for the caveman extension.
+// Kept separate from caveman.ts so it can be unit-tested directly without a
+// fake/installed Pi SDK. This module imports no runtime SDK values; any SDK
+// types it ever needs MUST be imported as `import type` so --experimental-strip-types
+// can erase them.
+
+export type CavemanMode =
+	| "lite"
+	| "full"
+	| "ultra"
+	| "wenyan-lite"
+	| "wenyan-full"
+	| "wenyan-ultra";
+
+export type StoredMode = CavemanMode | "off";
+
+export const VALID_MODES = new Set<CavemanMode>([
+	"lite",
+	"full",
+	"ultra",
+	"wenyan-lite",
+	"wenyan-full",
+	"wenyan-ultra",
+]);
+
+// Values offered as argument completions for /caveman: the six real modes plus
+// the `wenyan` alias (→ wenyan-full via normalizeMode) and `off`. These are what
+// a user may type, which is a superset of VALID_MODES, so it is kept as its own
+// list rather than derived from VALID_MODES.
+export const COMPLETION_VALUES: readonly string[] = [
+	"lite",
+	"full",
+	"ultra",
+	"wenyan",
+	"wenyan-lite",
+	"wenyan-full",
+	"wenyan-ultra",
+	"off",
+];
+
+export function normalizeMode(raw: string | undefined): StoredMode | undefined {
+	const value = (raw ?? "").trim().toLowerCase();
+	if (!value) return "full";
+	if (
+		["off", "stop", "normal", "normal-mode", "disable", "disabled"].includes(
+			value,
+		)
+	)
+		return "off";
+	if (value === "wenyan" || value === "classical") return "wenyan-full";
+	return VALID_MODES.has(value as CavemanMode)
+		? (value as CavemanMode)
+		: undefined;
+}
+
+export function modeInstructions(mode: CavemanMode): string {
+	const base = `
+CAVEMAN MODE ACTIVE. Respond terse like smart caveman. All technical substance stay. Only fluff die.
+
+Persistence:
+- Apply to every assistant response until user says "stop caveman", "normal mode", or runs /caveman off.
+- Do not announce mode. No "caveman mode on", no self-reference.
+
+Core rules:
+- Drop articles, filler, pleasantries, hedging, tool-call narration.
+- Prefer fragments. Pattern: [thing] [action] [reason]. [next step].
+- Keep technical terms exact. Keep code blocks, inline code, commands, API names, file paths, commit types, and exact error strings verbatim.
+- Preserve user's dominant language; compress style, not language.
+- Avoid decorative tables/emoji unless useful or requested.
+- Do not dump long raw logs unless asked; quote shortest decisive line.
+
+Auto-clarity:
+- Use normal precise prose for security warnings, irreversible confirmations, or sequences where terse fragments risk ambiguity.
+- Resume terse style after clear part.`;
+
+	const perMode: Record<CavemanMode, string> = {
+		lite: "Intensity: lite. Remove filler/hedging. Keep articles and full professional sentences.",
+		full: "Intensity: full. Drop articles; fragments OK; short synonyms. Classic caveman.",
+		ultra:
+			"Intensity: ultra. Bare fragments. Use arrows for causality. Abbreviate prose words only; never abbreviate real code symbols, function names, API names, or error strings.",
+		"wenyan-lite":
+			"Intensity: wenyan-lite. Semi-classical Chinese register when user writes Chinese; otherwise terse lite mode.",
+		"wenyan-full":
+			"Intensity: wenyan-full. Maximum classical Chinese terseness when user writes Chinese; otherwise terse full mode.",
+		"wenyan-ultra":
+			"Intensity: wenyan-ultra. Extreme classical Chinese compression when user writes Chinese; otherwise terse ultra mode.",
+	};
+
+	return `${base}\n\n${perMode[mode]}`;
+}
+
+export const ACTIVATION_RE =
+	/\b(caveman mode|talk like caveman|use caveman|less tokens|fewer tokens|save tokens)\b/i;
+export const DEACTIVATION_RE = /\b(stop caveman|normal mode|disable caveman)\b/i;

package/extensions/caveman.ts

@@ -0,0 +1,155 @@
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import {
+	ACTIVATION_RE,
+	COMPLETION_VALUES,
+	DEACTIVATION_RE,
+	modeInstructions,
+	normalizeMode,
+	type StoredMode,
+} from "./caveman-core.ts";
+
+const HELP_TEXT = `# Caveman for Pi
+
+Commands:
+- /caveman [lite|full|ultra|wenyan|wenyan-lite|wenyan-full|wenyan-ultra] — enable terse mode for this session.
+- /caveman off — disable terse mode.
+- /caveman-help — show this card.
+- /caveman-commit [notes] — generate Conventional Commit message. Does not commit.
+- /caveman-review [scope] — terse review comments.
+- /caveman-compress <file> — compress prose file via caveman-compress skill.
+- /caveman-stats — load stats skill/help.
+
+Mode persists in current Pi session and survives /reload via session state.
+Code, commands, API names, file paths, and exact errors stay verbatim.`;
+
+export default function cavemanExtension(pi: ExtensionAPI) {
+	let mode: StoredMode = "off";
+
+	function setStatus(ctx?: ExtensionContext) {
+		if (!ctx?.hasUI) return;
+		ctx.ui.setStatus("caveman", mode === "off" ? undefined : `caveman:${mode}`);
+	}
+
+	function persistMode(nextMode: StoredMode, ctx?: ExtensionContext) {
+		mode = nextMode;
+		pi.appendEntry("caveman-mode", { mode, timestamp: Date.now() });
+		setStatus(ctx);
+	}
+
+	pi.on("session_start", (_event, ctx) => {
+		mode = "off";
+		for (const entry of ctx.sessionManager.getBranch() as Array<{
+			type?: string;
+			customType?: string;
+			data?: { mode?: unknown };
+		}>) {
+			if (entry.type !== "custom" || entry.customType !== "caveman-mode")
+				continue;
+			const restored =
+				typeof entry.data?.mode === "string"
+					? normalizeMode(entry.data.mode)
+					: undefined;
+			if (restored) mode = restored;
+		}
+		setStatus(ctx);
+	});
+
+	pi.registerCommand("caveman", {
+		description: "Enable caveman terse mode: lite, full, ultra, wenyan, or off",
+		getArgumentCompletions: (prefix) => {
+			const normalizedPrefix = prefix.trim().toLowerCase();
+			const items = COMPLETION_VALUES.flatMap((value) =>
+				value.startsWith(normalizedPrefix) ? [{ value, label: value }] : [],
+			);
+			return items.length > 0 ? items : null;
+		},
+		handler: async (args, ctx) => {
+			const nextMode = normalizeMode(args);
+			if (!nextMode) {
+				ctx.ui.notify(`Unknown caveman mode: ${args || "(empty)"}`, "error");
+				return;
+			}
+			persistMode(nextMode, ctx);
+			ctx.ui.notify(
+				nextMode === "off" ? "Caveman disabled" : `Caveman ${nextMode} enabled`,
+				"info",
+			);
+		},
+	});
+
+	pi.registerCommand("caveman-help", {
+		description: "Show caveman command reference",
+		handler: async () => {
+			pi.sendMessage({
+				customType: "caveman-help",
+				content: HELP_TEXT,
+				display: true,
+			});
+		},
+	});
+
+	pi.registerCommand("caveman-commit", {
+		description: "Generate terse Conventional Commit message",
+		handler: async (args) => {
+			const task =
+				args?.trim() ||
+				"Generate a commit message for current repository changes. Inspect git status and diffs as needed. Do not run git commit.";
+			pi.sendUserMessage(`/skill:caveman-commit ${task}`);
+		},
+	});
+
+	pi.registerCommand("caveman-review", {
+		description: "Generate terse code-review comments",
+		handler: async (args) => {
+			const task =
+				args?.trim() ||
+				"Review current repository changes or PR diff. Inspect git diff as needed. Findings only.";
+			pi.sendUserMessage(`/skill:caveman-review ${task}`);
+		},
+	});
+
+	pi.registerCommand("caveman-compress", {
+		description: "Compress prose/memory file into caveman style",
+		handler: async (args, ctx) => {
+			const target = args?.trim();
+			if (!target) {
+				ctx.ui.notify("Usage: /caveman-compress <file>", "error");
+				return;
+			}
+			pi.sendUserMessage(`/skill:caveman-compress ${target}`);
+		},
+	});
+
+	pi.registerCommand("caveman-stats", {
+		description: "Show caveman stats skill/help",
+		handler: async (args) => {
+			pi.sendUserMessage(
+				`/skill:caveman-stats ${args?.trim() || "Show caveman stats if available."}`,
+			);
+		},
+	});
+
+	pi.on("input", (event, ctx) => {
+		if (event.source === "extension") return { action: "continue" as const };
+		const text = event.text.trim();
+		if (DEACTIVATION_RE.test(text)) {
+			if (mode !== "off") persistMode("off", ctx);
+			return { action: "continue" as const };
+		}
+		if (mode === "off" && ACTIVATION_RE.test(text)) {
+			persistMode("full", ctx);
+			return { action: "continue" as const };
+		}
+		return { action: "continue" as const };
+	});
+
+	pi.on("before_agent_start", (event) => {
+		if (mode === "off") return undefined;
+		return {
+			systemPrompt: `${event.systemPrompt}\n\n${modeInstructions(mode)}`,
+		};
+	});
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@kulapard/pi-caveman",
+  "version": "0.1.0",
+  "description": "Caveman for Pi: ultra-compressed agent output that preserves technical substance. Six intensity modes, slash commands, natural-language activation, and a session statusline.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kulapard/pi-caveman.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kulapard/pi-caveman/issues"
+  },
+  "homepage": "https://github.com/kulapard/pi-caveman#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "extensions",
+    "skills",
+    "agents",
+    "AGENTS.md",
+    "!**/__pycache__",
+    "!**/*.pyc",
+    "!skills/**/tests"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "caveman",
+    "compression",
+    "token-efficiency",
+    "extension"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/caveman.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "scripts": {
+    "pretest": "npm run typecheck",
+    "test": "node --experimental-strip-types --test tests/**/*.test.mjs",
+    "typecheck": "tsc --noEmit",
+    "test:py": ".venv/bin/pytest skills/caveman-compress",
+    "prepublishOnly": "npm test"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.80.2",
+    "typescript": "^5"
+  }
+}