@xynogen/pix-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xynogen
+
+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,36 @@
+# pix-core
+
+Pi coding agent extension — core UI/UX bundle.
+
+## What's included
+
+| Extension | Type | Description |
+|---|---|---|
+| `welcome` | lifecycle | ASCII π banner + startup health checks (version, auth, models, gitignore) |
+| `footer` | UI | Status bar: mode / git branch / model / cost / tps |
+| `models` | command | `/models` — enhanced model picker with BenchLM rank, context, cost |
+| `update` | command | `/update` — self-update Pi + refresh extensions from dotfiles |
+| `lg` | command | `/lg` — summarize unstaged git changes with per-file +/- counts |
+| `yeet` | command | `/yeet` — stage all, commit, and push current changes |
+| `copy-all` | command | `/copy-all` — copy the whole conversation to the clipboard |
+| `diff` | command | `/diff` — list/open files changed during the last agent run |
+| `todo` | tool | durable execution checklist (survives compaction) |
+| `toolbox` | tool | `search` (fuzzy-find every tool / MCP tool / skill / command), `enable` / `disable` (turn a gated tool on/off by name) |
+| `nudges` | hooks | model-steering reminders (tools / skill / capability) |
+
+## Install
+
+```bash
+pi install git:github.com/xynogen/pix-core
+```
+
+> **Requires** [pix-data](https://github.com/xynogen/pix-data) for shared models.dev + BenchLM cache.
+> Install both:
+> ```bash
+> pi install git:github.com/xynogen/pix-data
+> pi install git:github.com/xynogen/pix-core
+> ```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@xynogen/pix-core",
+  "version": "0.1.0",
+  "description": "Pi extension — core UI/UX bundle (welcome banner, footer, model picker, self-update)",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "test": "bun test"
+  },
+  "files": [
+    "src",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": ["src/index.ts"],
+    "skills": ["./skills"]
+  },
+  "keywords": ["pi", "pi-package", "pi-extension", "pix"],
+  "author": "xynogen",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xynogen/pix-mono.git",
+    "directory": "packages/pix-core"
+  },
+  "homepage": "https://github.com/xynogen/pix-mono/tree/main/packages/pix-core#readme",
+  "bugs": {
+    "url": "https://github.com/xynogen/pix-mono/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "typebox": "^1.1.38"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  }
+}

package/skills/ask-user/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: ask-user
+description: "MUST use before high-stakes/irreversible decisions or when requirements are ambiguous. Gather context, present 2-5 options via ask_user, get explicit choice, then proceed."
+metadata:
+  short-description: Decision gate for ambiguity and high-stakes choices
+---
+
+# ask_user decision gate
+
+Decision control, not chit-chat.
+
+## Gate (call ask_user before proceeding if ANY true)
+- changes architecture/schema/API/deploy/security
+- costly to undo (big refactor, migration, destructive edit, prod behavior)
+- requirements unclear/conflicting/missing
+- multiple valid options, trade-off is preference-dependent
+- about to assume something that changes implementation
+
+Skip only if user already gave an explicit decision for THIS exact trade-off.
+
+## Handshake
+1. classify step: high_stakes | ambiguous | both | clear. clear → no gate.
+2. gather evidence first (read/bash/web/ref). don't ask blind.
+3. synthesize: 3-7 bullets — state, constraints, trade-offs, recommendation.
+4. ask ONE focused question: `question`, `context`(summary), `options`(2-5),
+   `allowMultiple:false` unless truly independent, `allowFreeform:true`.
+   `inline` displayMode when the preceding summary must stay visible.
+5. commit: restate decision, say next step, proceed.
+6. re-ask only on materially new ambiguity. no confirm loops.
+
+## Budget (anti-overasking)
+- max 1 call per boundary normally; max 2 if first is unclear/cancelled.
+- never re-ask same trade-off without new evidence.
+- attempt 2 = narrower question: [Proceed w/ recommended] [Choose other (freeform)] [Stop].
+- after attempt 2: high_stakes/both → STOP, mark blocked.
+  ambiguous-only + user says "your call" → take most reversible default, state assumptions.
+
+## Quality
+- question: concrete decision boundary, one decision only.
+- options: short, outcome-oriented, explicit trade-offs; add description when non-obvious.
+
+## Anti-patterns
+asking without context · trivial formatting choices · forcing options when freeform fits ·
+repeat questions w/o new info · proceeding high-stakes after unclear/cancelled answer.
+
+## On cancel / unclear
+Pause, explain what's blocked. At most one narrower follow-up.
+Then: high-stakes → stay blocked until explicit decision; ambiguity-only → proceed only if user delegated.

package/src/commands/clear/clear.ts

@@ -0,0 +1,32 @@
+import type {
+	ExtensionAPI,
+	ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+
+async function clearCache(pi: ExtensionAPI, ctx: ExtensionCommandContext) {
+	ctx.ui.notify("Clearing ~/.cache/pi", "info");
+	const result = await pi.exec("/bin/sh", ["-lc", 'rm -rf "$HOME/.cache/pi"'], {
+		timeout: 10_000,
+	});
+	const output = [result.stdout, result.stderr]
+		.filter(Boolean)
+		.join("\n")
+		.trim();
+	if ((result.exitCode ?? 0) !== 0) {
+		ctx.ui.notify(`Cache clear failed. ${output || "No output."}`, "error");
+		return;
+	}
+	ctx.ui.notify(
+		"~/.cache/pi cleared. Run /reload to apply changes.",
+		"warning",
+	);
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.registerCommand("clear", {
+		description: "Remove ~/.cache/pi and reload",
+		handler: async (_args, ctx) => {
+			await clearCache(pi, ctx);
+		},
+	});
+}

package/src/commands/copy-all/copy-all.ts

@@ -0,0 +1,89 @@
+/**
+ * Copy-All Extension
+ *
+ * /copy-all → copies the entire user+assistant conversation in the current
+ * branch to the system clipboard. Uses pbcopy on macOS, xclip/xsel/wl-copy
+ * on Linux, clip.exe on WSL/Windows.
+ */
+
+import { spawn } from "node:child_process";
+import { platform } from "node:os";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+function textFromContent(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	return content
+		.map((block) => {
+			if (!block || typeof block !== "object" || !("type" in block)) return "";
+			if (block.type === "text" && "text" in block && typeof block.text === "string") return block.text;
+			if (block.type === "image") return "[image]";
+			return "";
+		})
+		.filter(Boolean)
+		.join("\n");
+}
+
+function pickClipboardCmd(): { cmd: string; args: string[] } | undefined {
+	const p = platform();
+	if (p === "darwin") return { cmd: "pbcopy", args: [] };
+	if (p === "win32") return { cmd: "clip.exe", args: [] };
+	// linux / wsl
+	if (process.env.WSL_DISTRO_NAME) return { cmd: "clip.exe", args: [] };
+	if (process.env.WAYLAND_DISPLAY) return { cmd: "wl-copy", args: [] };
+	return { cmd: "xclip", args: ["-selection", "clipboard"] };
+}
+
+function copyToClipboard(text: string): Promise<void> {
+	return new Promise((resolve, reject) => {
+		const c = pickClipboardCmd();
+		if (!c) {
+			reject(new Error("No clipboard utility detected"));
+			return;
+		}
+		const child = spawn(c.cmd, c.args);
+		let stderr = "";
+		child.stderr.on("data", (chunk) => { stderr += String(chunk); });
+		child.on("error", reject);
+		child.on("close", (code) => {
+			if (code === 0) resolve();
+			else reject(new Error(stderr.trim() || `${c.cmd} exited with code ${code}`));
+		});
+		child.stdin.end(text);
+	});
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.registerCommand("copy-all", {
+		description: "Copy all user/assistant messages in this thread to the clipboard",
+		handler: async (_args, ctx) => {
+			await ctx.waitForIdle();
+
+			const messages = ctx.sessionManager
+				.getBranch()
+				.filter((entry) => entry.type === "message")
+				.map((entry) => entry.message)
+				.filter((m) => m.role === "user" || m.role === "assistant");
+
+			const text = messages
+				.map((m) => {
+					const c = textFromContent(m.content).trim();
+					return `${m.role.toUpperCase()}:\n${c}`;
+				})
+				.filter((s) => !s.endsWith(":\n"))
+				.join("\n\n---\n\n");
+
+			if (!text) {
+				ctx.ui.notify("No user or assistant messages to copy", "info");
+				return;
+			}
+
+			try {
+				await copyToClipboard(text);
+				ctx.ui.notify(`📋 Copied ${messages.length} messages to clipboard`, "info");
+			} catch (err) {
+				ctx.ui.notify(`Clipboard copy failed: ${err instanceof Error ? err.message : String(err)}`, "error");
+			}
+		},
+	});
+}

package/src/commands/diff/diff.ts

@@ -0,0 +1,138 @@
+/**
+ * Diff Extension
+ *
+ * Tracks files changed during the last agent run (git delta + tool-touched
+ * paths from edit/write), and exposes /diff to list/open them.
+ *
+ * Subcommands:
+ *   /diff         → interactive selector, opens choice in editor
+ *   /diff list    → notify with the list of changed files
+ *   /diff clear   → reset tracked set and re-baseline against git
+ *
+ * Editor: $PI_DIFF_EDITOR > $VISUAL > $EDITOR > zed > code > vim
+ */
+
+import path from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const COMMAND = "diff";
+
+function getStringPath(input: unknown): string | undefined {
+	if (!input || typeof input !== "object" || !("path" in input)) return undefined;
+	const p = (input as { path?: unknown }).path;
+	return typeof p === "string" ? p : undefined;
+}
+
+function toAbs(cwd: string, p: string): string {
+	return path.isAbsolute(p) ? path.normalize(p) : path.resolve(cwd, p);
+}
+
+function toRel(cwd: string, p: string): string {
+	const r = path.relative(cwd, p);
+	return r && !r.startsWith("..") && !path.isAbsolute(r) ? r : p;
+}
+
+function parseGitStatus(output: string, cwd: string): Set<string> {
+	const files = new Set<string>();
+	for (const line of output.split("\n")) {
+		if (line.length < 4) continue;
+		const raw = line.slice(3).trim();
+		if (!raw) continue;
+		const target = raw.includes(" -> ") ? raw.split(" -> ").at(-1) : raw;
+		if (!target) continue;
+		files.add(toAbs(cwd, target.replace(/^"|"$/g, "")));
+	}
+	return files;
+}
+
+async function getGitChanged(pi: ExtensionAPI, cwd: string): Promise<Set<string>> {
+	const r = await pi.exec("git", ["status", "--porcelain", "--untracked-files=all"], { cwd, timeout: 5000 });
+	if (r.code !== 0) return new Set();
+	return parseGitStatus(r.stdout, cwd);
+}
+
+function diff(current: Set<string>, baseline: Set<string>): Set<string> {
+	return new Set([...current].filter((f) => !baseline.has(f)));
+}
+
+function pickEditor(): { cmd: string; args: (file: string) => string[] } {
+	const env = process.env.PI_DIFF_EDITOR || process.env.VISUAL || process.env.EDITOR;
+	if (env) {
+		const parts = env.split(/\s+/);
+		const cmd = parts[0];
+		const rest = parts.slice(1);
+		return { cmd, args: (f) => [...rest, f] };
+	}
+	return { cmd: "zed", args: (f) => ["-e", f] };
+}
+
+export default function (pi: ExtensionAPI) {
+	let baseline = new Set<string>();
+	let changed = new Set<string>();
+	let touched = new Set<string>();
+
+	pi.on("agent_start", async (_event, ctx) => {
+		touched = new Set();
+		changed = new Set();
+		baseline = await getGitChanged(pi, ctx.cwd);
+	});
+
+	pi.on("tool_result", (event, ctx) => {
+		if (event.toolName !== "edit" && event.toolName !== "write") return;
+		const p = getStringPath(event.input);
+		if (!p) return;
+		touched.add(toAbs(ctx.cwd, p));
+	});
+
+	pi.on("agent_end", async (_event, ctx) => {
+		const now = await getGitChanged(pi, ctx.cwd);
+		changed = new Set([...diff(now, baseline), ...touched]);
+		if (changed.size > 0) {
+			ctx.ui.notify(`📝 ${changed.size} changed file(s). Run /${COMMAND} to view/open.`, "info");
+		}
+	});
+
+	pi.registerCommand(COMMAND, {
+		description: "Show files changed by the last agent run and open one in your editor",
+		handler: async (args, ctx) => {
+			await ctx.waitForIdle();
+			const arg = (args ?? "").trim();
+
+			if (arg === "clear") {
+				changed = new Set();
+				touched = new Set();
+				baseline = await getGitChanged(pi, ctx.cwd);
+				ctx.ui.notify("Cleared changed file list", "info");
+				return;
+			}
+
+			const files = [...changed].sort((a, b) => toRel(ctx.cwd, a).localeCompare(toRel(ctx.cwd, b)));
+			if (files.length === 0) {
+				ctx.ui.notify("No changed files tracked from the last agent run", "info");
+				return;
+			}
+
+			if (arg === "list") {
+				ctx.ui.notify(`Changed files:\n${files.map((f) => `- ${toRel(ctx.cwd, f)}`).join("\n")}`, "info");
+				return;
+			}
+
+			if (arg) {
+				ctx.ui.notify(`Unknown /${COMMAND} argument: ${arg}. Try /${COMMAND}, /${COMMAND} list, /${COMMAND} clear.`, "warning");
+				return;
+			}
+
+			const labels = files.map((f) => toRel(ctx.cwd, f));
+			const selected = await ctx.ui.select("Open changed file", labels);
+			if (!selected) return;
+
+			const file = files[labels.indexOf(selected)];
+			if (!file) return;
+
+			const ed = pickEditor();
+			const r = await pi.exec(ed.cmd, ed.args(file), { cwd: ctx.cwd, timeout: 5000 });
+			if (r.code === 0) ctx.ui.notify(`Opened ${selected} in ${ed.cmd}`, "info");
+			else ctx.ui.notify(r.stderr.trim() || `Failed to open ${selected} in ${ed.cmd}`, "error");
+		},
+	});
+}

package/src/commands/lg/lg.ts

@@ -0,0 +1,32 @@
+/**
+ * /lg — summarize unstaged git changes with per-file +/- counts.
+ *
+ * The agent runs `git status` + line counts and replies with:
+ *   1. 1–2 sentence summary of unstaged changes
+ *   2. Per-file +/- line counts
+ *   3. Total +/- line count
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const LG_PROMPT = `Run git status, inspect what has changed, then respond with only:
+
+1. A short 1-2 sentence summary of the unstaged changes.
+2. A list of changed unstaged files with their +/- line counts.
+3. A total +/- line count at the bottom.
+
+Keep it concise. Use git commands to calculate the line counts; do not include staged changes unless they also have unstaged modifications.`;
+
+export default function (pi: ExtensionAPI) {
+	pi.registerCommand("lg", {
+		description: "Summarize unstaged git changes with per-file +/- counts",
+		handler: async (_args, ctx) => {
+			if (!ctx.isIdle()) {
+				pi.sendUserMessage(LG_PROMPT, { deliverAs: "followUp" });
+				ctx.ui.notify("Queued /lg after the current turn finishes.", "info");
+				return;
+			}
+			pi.sendUserMessage(LG_PROMPT);
+		},
+	});
+}

package/src/commands/models/models.test.ts

@@ -0,0 +1,95 @@
+import { describe, it, expect } from "bun:test";
+import { fmtCtx, fmtCost, benchStars, sortModels } from "./models.ts";
+
+describe("fmtCtx", () => {
+	it("formats 0 as 0", () => expect(fmtCtx(0)).toBe("0"));
+	it("formats small numbers as-is", () => expect(fmtCtx(512)).toBe("512"));
+	it("formats thousands as Nk", () => {
+		expect(fmtCtx(128_000)).toBe("128k");
+		expect(fmtCtx(8_192)).toBe("8k");
+	});
+	it("formats millions as NM", () => {
+		expect(fmtCtx(1_000_000)).toBe("1M");
+		expect(fmtCtx(2_000_000)).toBe("2M");
+		expect(fmtCtx(1_500_000)).toBe("1.5M");
+	});
+});
+
+describe("fmtCost", () => {
+	it("returns — for undefined entry", () =>
+		expect(fmtCost(undefined)).toBe("—"));
+	it("returns — when no cost field", () => expect(fmtCost({})).toBe("—"));
+	it("returns free when both 0", () => {
+		expect(fmtCost({ cost: { input: 0, output: 0 } })).toBe("free");
+	});
+	it("formats input/output costs", () => {
+		expect(fmtCost({ cost: { input: 3, output: 15 } })).toBe("3.00/15.00");
+	});
+	it("handles missing input/output as 0", () => {
+		expect(fmtCost({ cost: {} })).toBe("free");
+	});
+});
+
+describe("benchStars", () => {
+	it("gives 5 stars for score >= 90", () => {
+		expect(benchStars(95).filled).toBe(5);
+		expect(benchStars(90).filled).toBe(5);
+	});
+	it("gives 4 stars for 80-89", () => {
+		expect(benchStars(85).filled).toBe(4);
+		expect(benchStars(80).filled).toBe(4);
+	});
+	it("gives 3 stars for 70-79", () => {
+		expect(benchStars(75).filled).toBe(3);
+	});
+	it("gives 2 stars for 50-69", () => {
+		expect(benchStars(60).filled).toBe(2);
+		expect(benchStars(50).filled).toBe(2);
+	});
+	it("gives 1 star for score < 50", () => {
+		expect(benchStars(30).filled).toBe(1);
+		expect(benchStars(0).filled).toBe(1);
+	});
+	it("gives 1 star for null/undefined", () => {
+		expect(benchStars(null).filled).toBe(1);
+		expect(benchStars(undefined).filled).toBe(1);
+	});
+	it("filled + empty always = 5", () => {
+		for (const s of [0, 50, 70, 80, 90, 100]) {
+			const { filled, empty } = benchStars(s);
+			expect(filled + empty).toBe(5);
+		}
+	});
+});
+
+describe("sortModels", () => {
+	const models = [
+		{ provider: "a", id: "m1", name: "Zebra", score: 80 },
+		{ provider: "a", id: "m2", name: "Alpha", score: 95 },
+		{ provider: "a", id: "m3", name: "Middle", score: null },
+		{ provider: "a", id: "m4", name: "Beta", score: 80 },
+	];
+
+	it("sorts by score descending", () => {
+		const sorted = sortModels(models);
+		expect(sorted[0].name).toBe("Alpha"); // score 95
+	});
+
+	it("breaks score ties alphabetically by name", () => {
+		const sorted = sortModels(models);
+		const tiedIdx = sorted.findIndex((m) => m.name === "Beta");
+		const zebraIdx = sorted.findIndex((m) => m.name === "Zebra");
+		expect(tiedIdx).toBeLessThan(zebraIdx); // Beta before Zebra, both score 80
+	});
+
+	it("puts null score models last", () => {
+		const sorted = sortModels(models);
+		expect(sorted[sorted.length - 1].name).toBe("Middle");
+	});
+
+	it("does not mutate the original array", () => {
+		const original = [...models];
+		sortModels(models);
+		expect(models).toEqual(original);
+	});
+});