@kulapard/pi-caveman 0.4.1 → 0.4.3

package/AGENTS.md

@@ -1,55 +1,25 @@
 # AGENTS.md — pi-caveman conventions
 
-Project memory for agents working in this repo. Non-obvious conventions only.
+Project memory. Non-obvious 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`.
-- The extension's `modeInstructions` injection is the **canonical** activator;
-  the `caveman` skill (`skills/caveman/SKILL.md`) is a standalone fallback for
-  hosts that load skills but not this extension. When both are active the model
-  may see both rule sets — mild, intentional redundancy. They are not
-  programmatically de-duped: skill loading is model-driven and the skill's prose
-  differs from `modeInstructions`, so there is no reliable text to match on.
-- 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.
+- `extensions/caveman.ts` = Pi extension. `extensions/caveman-core.ts` = pure SDK-free logic (`normalizeMode`, `modeInstructions`, `VALID_MODES`, regexes). Unit-testable without fake SDK.
+- Mode state **session-scoped**: `pi.appendEntry("caveman-mode", …)`, restored from `ctx.sessionManager.getBranch()` on `session_start`. New session always `off`. No cross-session config/env.
+- Activation = `before_agent_start` appends `modeInstructions(mode)`. Statusline = `ctx.ui.setStatus("caveman", …)` guarded by `hasUI`.
+- Extension `modeInstructions` = **canonical** activator. `skills/caveman/SKILL.md` = fallback for hosts loading skills but not extension. If both active, model sees both rule sets — intentional redundancy, no de-dupe.
+- Pi 0.80.2 has **no `agents/` subagent mechanism**. `agents/cavecrew-*.md` = reference personas only; cavecrew 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. The skill instructs
-  the agent to self-validate these against the original and, on any mismatch it
-  cannot fix, restore from the `.original` backup that was created during the
-  same invocation (stale backups are rejected before compression starts).
-- `caveman-compress` is **prompt-only**: the Pi agent performs the compression
-  with its own model and file tools, driven by `SKILL.md`. There is no Python and
-  no external model CLI; coverage is the doc-guard test `tests/compress-docs.test.mjs`.
+- **SDK import `import type` only** in `extensions/*.ts`. JS tests run via `--experimental-strip-types`, erases type-only imports. Value import from `@earendil-works/pi-coding-agent` breaks tests — `tests/extension.test.mjs` asserts this.
+- **Verbatim preservation**: caveman-compress never changes code blocks, inline code, URLs, paths, commands, exact error strings. Skill instructs self-validate against original. Mismatch unfixable → restore from `.original` backup created in same invocation (stale backups rejected before compression).
+- `caveman-compress` is **prompt-only**: Pi agent compresses with own model + file tools, driven by `SKILL.md`. No Python, no external model CLI. Coverage = `tests/compress-docs.test.mjs`.
 
 ## Changelog
 
-Every notable change must update `CHANGELOG.md` under `[Unreleased]`. Before
-finishing a task, run `npm run changelog:check` to confirm the changelog was
-updated for the files you changed. CI also runs this check on every pull
-request.
-
-- `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.
-- 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.
+Every notable change must update `CHANGELOG.md` under `[Unreleased]`. Before finishing task, run `npm run changelog:check` to confirm changelog updated for files changed. CI runs same check on every PR.
+
+- `npm test` runs `pretest` (`npm run typecheck` → `tsc --noEmit`), then `node --test tests/**/*.test.mjs`. Typecheck failures fail test run.
+- Node `--test` glob expanded by runner, not shell. Directory-recursion `--test tests/` does **not** work on current Node — keep glob.
+- Tests are **phantom-reference guards** (`tests/stats-docs.test.mjs`, `tests/cavecrew-docs.test.mjs`, `tests/compress-docs.test.mjs`): docs must not mention Claude-Code hooks layer, plugin install path, `⛏` badge, Claude-only subagent presets, broken asset paths. Do not reintroduce.

package/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- Caveman mode is now project-scoped: `.pi/caveman-mode.json` in the working
+  directory persists the mode across new sessions, while session entries still
+  override it for the current session. Falls back to `off` when no state exists.
+- Status bar now appends live context usage (`ctx:XX%`) when a caveman mode is
+  active and Pi exposes usage data. Updates on mode changes and at each turn end.
+
+## [0.4.2] - 2026-06-29
+
+### Changed
+
+- Compressed `AGENTS.md` with `caveman-compress` to reduce session token load.
+- Added `*.original` and `*.original.*` to `.gitignore` so caveman-compress
+  backups are not committed accidentally.
+
 ## [0.4.1] - 2026-06-29
 
 ### Changed
@@ -104,7 +120,8 @@ port of [caveman](https://github.com/JuliusBrussee/caveman).
   token, automatic provenance, a tag-equals-version guard, and a concurrency
   group).
 
-[Unreleased]: https://github.com/kulapard/pi-caveman/compare/v0.4.1...HEAD
+[Unreleased]: https://github.com/kulapard/pi-caveman/compare/v0.4.2...HEAD
+[0.4.2]: https://github.com/kulapard/pi-caveman/compare/v0.4.1...v0.4.2
 [0.4.1]: https://github.com/kulapard/pi-caveman/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/kulapard/pi-caveman/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/kulapard/pi-caveman/compare/v0.2.0...v0.3.0

package/extensions/caveman-state.ts

@@ -0,0 +1,49 @@
+// Project-scoped persistence for caveman mode.
+// This is a workaround until Pi exposes SettingsManager to extensions
+// (tracked upstream as pi-coding-agent issue #4981).
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { normalizeMode, type StoredMode } from "./caveman-core.ts";
+
+const STATE_DIR = ".pi";
+const STATE_FILE = "caveman-mode.json";
+
+function statePath(cwd: string): string {
+	return join(cwd, STATE_DIR, STATE_FILE);
+}
+
+/**
+ * Load the project-scoped caveman mode default. Returns `undefined` when no
+ * state file exists or it cannot be read, so the caller can fall back to the
+ * session-scoped default (`off`).
+ */
+export function loadProjectMode(cwd: string): StoredMode | undefined {
+	const path = statePath(cwd);
+	if (!existsSync(path)) return undefined;
+	try {
+		const raw = JSON.parse(readFileSync(path, "utf8"));
+		return normalizeMode(raw.mode);
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Persist the caveman mode for this project directory. Returns `true` on
+ * success; failures are silent so that session operation is never blocked by
+ * disk issues.
+ */
+export function saveProjectMode(cwd: string, mode: StoredMode): boolean {
+	try {
+		const dir = join(cwd, STATE_DIR);
+		if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+		writeFileSync(
+			statePath(cwd),
+			JSON.stringify({ mode, updatedAt: Date.now() }, null, 2),
+		);
+		return true;
+	} catch {
+		return false;
+	}
+}

package/extensions/caveman.ts

@@ -10,6 +10,7 @@ import {
 	normalizeMode,
 	type StoredMode,
 } from "./caveman-core.ts";
+import { loadProjectMode, saveProjectMode } from "./caveman-state.ts";
 
 const HELP_TEXT = `# Caveman for Pi
 
@@ -22,15 +23,22 @@ Commands:
 - /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.`;
+Mode persists across sessions in the same project via \`.pi/caveman-mode.json\`, 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}`);
+		const usage = ctx.getContextUsage?.();
+		const suffix =
+			usage?.percent != null ? ` ctx:${Math.round(usage.percent)}%` : "";
+		ctx.ui.setStatus(
+			"caveman",
+			mode === "off" ? undefined : `caveman:${mode}${suffix}`,
+		);
 	}
 
 	function persistMode(nextMode: StoredMode, ctx?: ExtensionContext) {
@@ -40,7 +48,7 @@ export default function cavemanExtension(pi: ExtensionAPI) {
 	}
 
 	pi.on("session_start", (_event, ctx) => {
-		mode = "off";
+		mode = loadProjectMode(ctx.cwd) ?? "off";
 		for (const entry of ctx.sessionManager.getBranch() as Array<{
 			type?: string;
 			customType?: string;
@@ -73,6 +81,7 @@ export default function cavemanExtension(pi: ExtensionAPI) {
 				return;
 			}
 			persistMode(nextMode, ctx);
+			saveProjectMode(ctx.cwd, nextMode);
 			ctx.ui.notify(
 				nextMode === "off" ? "Caveman disabled" : `Caveman ${nextMode} enabled`,
 				"info",
@@ -137,14 +146,22 @@ export default function cavemanExtension(pi: ExtensionAPI) {
 		if (event.source !== "extension") {
 			const text = (event.text ?? "").trim();
 			if (DEACTIVATION_RE.test(text)) {
-				if (mode !== "off") persistMode("off", ctx);
+				if (mode !== "off") {
+					persistMode("off", ctx);
+					saveProjectMode(ctx.cwd, "off");
+				}
 			} else if (mode === "off" && ACTIVATION_RE.test(text)) {
 				persistMode("full", ctx);
+				saveProjectMode(ctx.cwd, "full");
 			}
 		}
 		return { action: "continue" as const };
 	});
 
+	pi.on("turn_end", (_event, ctx) => {
+		setStatus(ctx);
+	});
+
 	pi.on("before_agent_start", (event) => {
 		if (mode === "off") return undefined;
 		return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kulapard/pi-caveman",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "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",