pi-file-change-reminder 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Gorbatchev
+
+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,84 @@
+# pi-file-change-reminder
+
+[pi](https://pi.dev) extension that injects reminder messages when matching files are modified via `write`, `edit`, or `multi_tool_use.parallel` tool calls.
+
+## Install
+
+```bash
+pi install npm:pi-file-change-reminder
+```
+
+## Quick start
+
+Create a rules file at your project root:
+
+`.pi/reminders.json`
+
+```json
+[
+  {
+    "glob": "README.md",
+    "reminder": "Run docs checks after editing README.md"
+  },
+  {
+    "glob": "src/**/*.ts",
+    "reminder": "Run the TypeScript test suite before finishing"
+  }
+]
+```
+
+## Slash command
+
+Use the built-in extension command:
+
+```text
+/pi-file-change-reminder
+```
+
+This injects a user message that asks Pi to help update the reminder config file with the required JSON shape, safety constraints, and picomatch glob guidance.
+
+You can also include a specific change request:
+
+```text
+/pi-file-change-reminder add a rule for docs/**/*.md reminding me to run vale
+```
+
+## Rules file resolution
+
+Default rules path is `.pi/reminders.json` resolved from the **nearest ancestor directory** containing either:
+
+- `.git`, or
+- `.pi`
+
+If no ancestor contains either marker, resolution falls back to Pi's current working directory.
+
+You can override with `PI_REMINDERS_FILE`:
+
+```bash
+export PI_REMINDERS_FILE=/absolute/path/to/reminders.json
+```
+
+If `PI_REMINDERS_FILE` is relative, it is resolved from the detected project directory (same logic as above).
+
+## Glob behavior
+
+- Matching engine: `picomatch`
+- Relative rule globs match against paths relative to the project marker directory (nearest ancestor with `.git` or `.pi`).
+- Absolute rule globs match against normalized absolute file paths.
+
+## Runtime behavior
+
+- When a rule matches a modified file, the extension injects the reminder as a user message.
+- In interactive mode, it also shows an info notification with the matched path and rule.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm run verify:pi-load
+```
+
+## Current limitation
+
+Reminder deduplication is currently keyed by reminder text. If two different rules use the same `reminder` string, only one will be injected per session branch.

package/fileChangeReminderExtension.ts

@@ -0,0 +1,412 @@
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import picomatch from "picomatch";
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+interface IReminderRule {
+	glob: string;
+	reminder: string;
+}
+
+interface IToolInputWithPath {
+	path: string;
+}
+
+const EXTENSION_ID = "file-change-reminder";
+const DEFAULT_RULES_FILE = ".pi/reminders.json";
+const COMMAND_NAME = "pi-file-change-reminder";
+const INJECTED_ENTRY_TYPE = `${EXTENSION_ID}.injected`;
+
+export default function fileChangeReminderExtension(pi: ExtensionAPI): void {
+	let rulesCache: IReminderRule[] = [];
+	let rulesMtimeMs = -1;
+	let hasLoadedRules = false;
+	let lastLoadError = "";
+	let injectedReminderKeys = new Set<string>();
+	const globMatcherCache = new Map<string, (candidatePath: string) => boolean>();
+	const projectDirectoryCache = new Map<string, string>();
+
+	const rebuildInjectedReminderKeys = (ctx: ExtensionContext): void => {
+		injectedReminderKeys = new Set<string>();
+
+		for (const entry of ctx.sessionManager.getBranch()) {
+			if (entry.type !== "custom" || entry.customType !== INJECTED_ENTRY_TYPE) {
+				continue;
+			}
+
+			if (!isRecord(entry.data)) {
+				continue;
+			}
+
+			const reminderKey = readNonEmptyString(entry.data.reminderKey);
+			if (reminderKey !== null) {
+				injectedReminderKeys.add(reminderKey);
+			}
+		}
+	};
+
+	const resolveProjectDirectory = async (cwd: string): Promise<string> => {
+		const resolvedCwd = path.resolve(cwd);
+		const cachedDirectory = projectDirectoryCache.get(resolvedCwd);
+		if (cachedDirectory !== undefined) {
+			return cachedDirectory;
+		}
+
+		let currentDirectory = resolvedCwd;
+		for (;;) {
+			const hasGitMarker = await pathExists(path.join(currentDirectory, ".git"));
+			const hasPiMarker = await pathExists(path.join(currentDirectory, ".pi"));
+			if (hasGitMarker || hasPiMarker) {
+				projectDirectoryCache.set(resolvedCwd, currentDirectory);
+				return currentDirectory;
+			}
+
+			const parentDirectory = path.dirname(currentDirectory);
+			if (parentDirectory === currentDirectory) {
+				projectDirectoryCache.set(resolvedCwd, resolvedCwd);
+				return resolvedCwd;
+			}
+
+			currentDirectory = parentDirectory;
+		}
+	};
+
+	const resolveRulesFilePathFromProjectDirectory = (projectDirectory: string): string => {
+		const envValue = process.env.PI_REMINDERS_FILE;
+		const configuredPath = readNonEmptyString(envValue) ?? DEFAULT_RULES_FILE;
+		if (path.isAbsolute(configuredPath)) {
+			return configuredPath;
+		}
+
+		return path.resolve(projectDirectory, configuredPath);
+	};
+
+	const resolveRulesFilePath = async (cwd: string): Promise<string> => {
+		const projectDirectory = await resolveProjectDirectory(cwd);
+		return resolveRulesFilePathFromProjectDirectory(projectDirectory);
+	};
+
+	const loadRules = async (ctx: ExtensionContext, force: boolean): Promise<IReminderRule[]> => {
+		const rulesFilePath = await resolveRulesFilePath(ctx.cwd);
+
+		let mtimeMs = -1;
+		try {
+			const stats = await stat(rulesFilePath);
+			mtimeMs = stats.mtimeMs;
+		} catch (error) {
+			rulesCache = [];
+			rulesMtimeMs = -1;
+			hasLoadedRules = true;
+
+			if (isRecord(error) && error.code === "ENOENT") {
+				lastLoadError = "";
+				return rulesCache;
+			}
+
+			const errorMessage = getErrorMessage(error);
+			if (errorMessage !== lastLoadError && ctx.hasUI) {
+				ctx.ui.notify(`Failed to stat reminder rules file: ${errorMessage}`, "warning");
+			}
+			lastLoadError = errorMessage;
+			return rulesCache;
+		}
+
+		if (!force && hasLoadedRules && mtimeMs === rulesMtimeMs) {
+			return rulesCache;
+		}
+
+		try {
+			const raw = await readFile(rulesFilePath, "utf8");
+			const parsed: unknown = JSON.parse(raw);
+			rulesCache = parseRules(parsed);
+			rulesMtimeMs = mtimeMs;
+			hasLoadedRules = true;
+			lastLoadError = "";
+			globMatcherCache.clear();
+			return rulesCache;
+		} catch (error) {
+			rulesCache = [];
+			rulesMtimeMs = mtimeMs;
+			hasLoadedRules = true;
+			const errorMessage = getErrorMessage(error);
+			if (errorMessage !== lastLoadError && ctx.hasUI) {
+				ctx.ui.notify(`Failed to parse reminder rules file: ${errorMessage}`, "warning");
+			}
+			lastLoadError = errorMessage;
+			return rulesCache;
+		}
+	};
+
+	const maybeInjectReminder = (
+		ctx: ExtensionContext,
+		rule: IReminderRule,
+		matchedPath: string,
+	): void => {
+		const reminderKey = buildReminderKey(rule.reminder);
+		if (injectedReminderKeys.has(reminderKey)) {
+			return;
+		}
+
+		injectedReminderKeys.add(reminderKey);
+		pi.appendEntry(INJECTED_ENTRY_TYPE, {
+			reminderKey,
+			glob: rule.glob,
+			reminder: rule.reminder,
+			matchedPath,
+			injectedAt: new Date().toISOString(),
+		});
+
+		if (ctx.isIdle()) {
+			pi.sendUserMessage(rule.reminder);
+		} else {
+			pi.sendUserMessage(rule.reminder, { deliverAs: "steer" });
+		}
+
+		if (ctx.hasUI) {
+			ctx.ui.notify(`Auto reminder injected for ${matchedPath} (rule: ${rule.glob})`, "info");
+		}
+	};
+
+	const onSessionChanged = async (_ctxEvent: unknown, ctx: ExtensionContext): Promise<void> => {
+		rebuildInjectedReminderKeys(ctx);
+		await loadRules(ctx, true);
+	};
+
+	pi.on("session_start", onSessionChanged);
+	pi.on("session_switch", onSessionChanged);
+	pi.on("session_fork", onSessionChanged);
+	pi.on("session_tree", onSessionChanged);
+
+	pi.registerCommand(COMMAND_NAME, {
+		description: "Inject a prompt that explains how to update reminder rules",
+		handler: async (args, ctx) => {
+			const projectDirectory = await resolveProjectDirectory(ctx.cwd);
+			const rulesFilePath = resolveRulesFilePathFromProjectDirectory(projectDirectory);
+			const normalizedRulesFilePath = normalizePath(rulesFilePath);
+			const normalizedProjectDirectory = normalizePath(projectDirectory);
+			const prompt = buildReminderEditPrompt(normalizedRulesFilePath, normalizedProjectDirectory, args);
+
+			if (ctx.isIdle()) {
+				pi.sendUserMessage(prompt);
+				return;
+			}
+
+			pi.sendUserMessage(prompt, { deliverAs: "followUp" });
+			if (ctx.hasUI) {
+				ctx.ui.notify(`Queued /${COMMAND_NAME} prompt as a follow-up message.`, "info");
+			}
+		},
+	});
+
+	pi.on("tool_result", async (event, ctx) => {
+		if (event.isError) {
+			return;
+		}
+
+		const changedPaths = getChangedPaths(event.toolName, event.input);
+		if (changedPaths.length === 0) {
+			return;
+		}
+
+		const rules = await loadRules(ctx, false);
+		if (rules.length === 0) {
+			return;
+		}
+
+		const projectDirectory = await resolveProjectDirectory(ctx.cwd);
+		for (const changedPath of changedPaths) {
+			const absolutePath = path.isAbsolute(changedPath)
+				? path.normalize(changedPath)
+				: path.resolve(ctx.cwd, changedPath);
+			const normalizedAbsolutePath = normalizePath(absolutePath);
+			const normalizedRelativePath = normalizePath(path.relative(projectDirectory, absolutePath));
+
+			for (const rule of rules) {
+				if (
+					matchesRule(
+						rule.glob,
+						normalizedRelativePath,
+						normalizedAbsolutePath,
+						globMatcherCache,
+					)
+				) {
+					maybeInjectReminder(ctx, rule, normalizedRelativePath);
+				}
+			}
+		}
+	});
+}
+
+function parseRules(parsed: unknown): IReminderRule[] {
+	if (!Array.isArray(parsed)) {
+		return [];
+	}
+
+	const rules: IReminderRule[] = [];
+	for (const item of parsed) {
+		if (!isRecord(item)) {
+			continue;
+		}
+
+		const glob = readNonEmptyString(item.glob);
+		const reminder = readNonEmptyString(item.reminder);
+		if (glob === null || reminder === null) {
+			continue;
+		}
+
+		rules.push({
+			glob: normalizePath(glob),
+			reminder,
+		});
+	}
+
+	return rules;
+}
+
+function getChangedPaths(toolName: string, input: unknown): string[] {
+	if ((toolName === "write" || toolName === "edit") && isToolInputWithPath(input)) {
+		return [input.path];
+	}
+
+	if (toolName !== "multi_tool_use.parallel") {
+		return [];
+	}
+
+	if (!isRecord(input) || !Array.isArray(input.tool_uses)) {
+		return [];
+	}
+
+	const changedPaths: string[] = [];
+	for (const toolUse of input.tool_uses) {
+		if (!isRecord(toolUse)) {
+			continue;
+		}
+
+		const recipientName = readNonEmptyString(toolUse.recipient_name);
+		if (recipientName === null) {
+			continue;
+		}
+
+		const isWriteCall = recipientName.endsWith(".write");
+		const isEditCall = recipientName.endsWith(".edit");
+		if (!isWriteCall && !isEditCall) {
+			continue;
+		}
+
+		if (isToolInputWithPath(toolUse.parameters)) {
+			changedPaths.push(toolUse.parameters.path);
+		}
+	}
+
+	return changedPaths;
+}
+
+function isToolInputWithPath(input: unknown): input is IToolInputWithPath {
+	return isRecord(input) && typeof input.path === "string" && input.path.length > 0;
+}
+
+function matchesRule(
+	ruleGlob: string,
+	relativePath: string,
+	absolutePath: string,
+	globMatcherCache: Map<string, (candidatePath: string) => boolean>,
+): boolean {
+	const normalizedGlob = normalizePath(ruleGlob);
+	if (path.isAbsolute(normalizedGlob)) {
+		return matchesGlob(normalizedGlob, absolutePath, globMatcherCache);
+	}
+
+	return matchesGlob(normalizedGlob, relativePath, globMatcherCache);
+}
+
+function matchesGlob(
+	globPattern: string,
+	candidatePath: string,
+	globMatcherCache: Map<string, (candidatePath: string) => boolean>,
+): boolean {
+	let matcher = globMatcherCache.get(globPattern);
+	if (matcher === undefined) {
+		const picomatchMatcher = picomatch(globPattern, { dot: true });
+		matcher = (value: string): boolean => picomatchMatcher(value);
+		globMatcherCache.set(globPattern, matcher);
+	}
+
+	return matcher(candidatePath);
+}
+
+function buildReminderEditPrompt(rulesFilePath: string, projectDirectory: string, args: string): string {
+	const requestedChange = readNonEmptyString(args);
+	const changeInstructions = requestedChange === null
+		? "Explain what changes you recommend, then ask me what to add, edit, or remove."
+		: `Apply this requested change: ${requestedChange}`;
+
+	return [
+		"Help me update this project reminder configuration file:",
+		`- ${rulesFilePath}`,
+		"",
+		"Purpose of this file:",
+		"- It defines reminders that are auto-injected when matching files are changed.",
+		"- Each rule maps a file pattern (glob) to a reminder message sent to the agent.",
+		"",
+		"Glob usage:",
+		"- 'glob' uses picomatch syntax (for example *, **, ?, braces like {ts,tsx}, and extglobs).",
+		`- Relative globs are matched from the project marker directory: ${projectDirectory}`,
+		"- Example relative glob: src/**/*.ts",
+		"- The project marker directory is the nearest ancestor containing .git or .pi.",
+		"- Absolute globs are matched against normalized absolute file paths.",
+		"- Use specific patterns to avoid noisy reminders.",
+		"",
+		"Requirements:",
+		"- Keep valid JSON with a top-level array.",
+		"- Each rule must have non-empty string fields: glob, reminder.",
+		"- Preserve existing rules unless my request says otherwise.",
+		"- Use 2-space indentation.",
+		"",
+		changeInstructions,
+	].join("\n");
+}
+
+async function pathExists(filePath: string): Promise<boolean> {
+	try {
+		await stat(filePath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function normalizePath(filePath: string): string {
+	const forwardSlashPath = filePath.replaceAll("\\", "/");
+	if (forwardSlashPath.startsWith("./")) {
+		return forwardSlashPath.slice(2);
+	}
+	return forwardSlashPath;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function readNonEmptyString(value: unknown): string | null {
+	if (typeof value !== "string") {
+		return null;
+	}
+
+	const trimmed = value.trim();
+	if (trimmed.length === 0) {
+		return null;
+	}
+
+	return trimmed;
+}
+
+function buildReminderKey(reminder: string): string {
+	return reminder.trim();
+}
+
+function getErrorMessage(error: unknown): string {
+	if (error instanceof Error && error.message.length > 0) {
+		return error.message;
+	}
+	return String(error);
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "pi-file-change-reminder",
+  "version": "1.0.0",
+  "description": "Pi extension that injects reminder messages when specific files are modified.",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "reminder"
+  ],
+  "files": [
+    "fileChangeReminderExtension.ts",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./fileChangeReminderExtension.ts"
+    ]
+  },
+  "dependencies": {
+    "picomatch": "^4.0.3"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@mariozechner/pi-coding-agent": "^0.61.1",
+    "@types/picomatch": "^4.0.2",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "verify:pi-load": "PI_OFFLINE=1 pi --no-extensions -e ./fileChangeReminderExtension.ts --list-models > /dev/null"
+  }
+}