pi-custom-system-prompt 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-06-21
+
+### Added
+
+- Initial release.
+- Load a custom system prompt from `~/.pi/agent/system-prompts/<file>.md` and inject it on every agent turn via the `before_agent_start` event.
+- Commands: `/system-prompt-info`, `/system-prompt-toggle`, `/system-prompt-reload`, `/system-prompt-mode`, `/system-prompt-show`, `/system-prompt-select`.
+- Two modes: `append` (default; keep Pi's prompt as the base and add the custom prompt as an extra section) and `replace` (use the custom prompt as the base, with Pi's tools and user customizations appended after it).
+- Multiple `.md` files can coexist in the prompt directory; use `/system-prompt-select` to switch between them.
+- Persistent state (`enabled`, `mode`, `selectedFile`) saved to `~/.pi/agent/state/system-prompt.json` and reloaded on next start.
+- Footer status widget: `system-prompt: <file>` when enabled, `system-prompt: disabled` when not.
+- `PI_SYSTEM_PROMPT_DIR` environment variable to override the default prompt directory.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nocte
+
+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,142 @@
+# pi-custom-system-prompt
+
+A [pi](https://pi.dev) extension that loads a custom system prompt from a markdown file and injects it into every agent turn. Works with any model or provider — nothing is hardcoded.
+
+Multiple `.md` files can live in the prompt directory; pick which one is active with `/system-prompt-select`. All changes take effect on the very next message you send — no `/new` or session restart required.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `/system-prompt-info` | Show loaded path, size, mode, enabled state, available files |
+| `/system-prompt-toggle` | Enable or disable the custom prompt |
+| `/system-prompt-reload` | Re-read the selected prompt file from disk |
+| `/system-prompt-mode [replace\|append]` | Toggle or set the merge mode |
+| `/system-prompt-show` | Print the first ~800 chars of the loaded prompt |
+| `/system-prompt-select` | Pick a different prompt file from the directory |
+
+## Modes
+
+**`append`** (default) — keep Pi's default system prompt as the base, and add the custom prompt as an extra section. Safest for most models, since Pi's tool descriptions stay authoritative.
+
+**`replace`** — use the custom prompt as the base system prompt. Pi's tool descriptions, current date, working directory, and any `--append-system-prompt` you passed are appended after it.
+
+## Setup
+
+### 1. Install the extension
+
+```bash
+pi install npm:pi-custom-system-prompt
+```
+
+Or try it without installing:
+
+```bash
+pi -e npm:pi-custom-system-prompt
+```
+
+### 2. Create the prompt directory
+
+```bash
+mkdir -p ~/.pi/agent/system-prompts
+```
+
+The extension reads from this directory by default. To use a different location, set the `PI_SYSTEM_PROMPT_DIR` environment variable.
+
+### 3. Add a markdown file
+
+```bash
+# Example: a focused prompt for a specific model
+cat > ~/.pi/agent/system-prompts/claude-code.md <<'EOF'
+You are a careful, terse coding assistant.
+- Read files before editing them.
+- Prefer minimal diffs.
+- Explain non-obvious choices in one sentence.
+EOF
+
+# Another example: a personality-style prompt
+cat > ~/.pi/agent/system-prompts/pirate.md <<'EOF'
+You are a pirate captain. Speak in pirate vernacular but stay accurate
+about technical content. Never break character.
+EOF
+```
+
+The first file (alphabetical) is auto-selected on first run. Use `/system-prompt-select` to switch between them.
+
+### 4. Verify and toggle
+
+```bash
+# inside pi:
+/system-prompt-info        # confirm the file loaded
+/system-prompt-toggle off  # disable without deleting the file
+/system-prompt-toggle on   # re-enable
+```
+
+The footer shows the active state:
+
+```
+system-prompt: claude-code.md    # enabled, showing the file
+system-prompt: enabled           # enabled, no file selected
+system-prompt: disabled          # disabled
+```
+
+## How it works
+
+- The extension subscribes to `before_agent_start`, which fires on every user message. It reads the selected `.md` file from the prompt directory, then either appends it to or replaces Pi's resolved system prompt before sending to the model.
+- State (`enabled`, `mode`, `selectedFile`) persists to `~/.pi/agent/state/system-prompt.json` and is reloaded on the next start.
+- All commands are non-destructive: they mutate in-memory state, save to the state file, and take effect on the next message.
+- If the prompt directory is missing, has no `.md` files, or the selected file is empty/unreadable, the extension logs the reason to `/system-prompt-info` and falls back to Pi's default prompt with no error.
+
+## Removing the extension
+
+```bash
+pi remove npm:pi-custom-system-prompt
+```
+
+This unloads the extension but does not delete your prompt files in `~/.pi/agent/system-prompts/` or your saved state in `~/.pi/agent/state/system-prompt.json`. Delete those manually if you want a clean uninstall:
+
+```bash
+rm -rf ~/.pi/agent/system-prompts
+rm -f  ~/.pi/agent/state/system-prompt.json
+```
+
+## Environment variables
+
+| Variable | Default | Effect |
+|---|---|---|
+| `PI_SYSTEM_PROMPT_DIR` | `~/.pi/agent/system-prompts` | Override the directory the extension scans for `.md` prompt files |
+
+## Development
+
+The extension lives in [`extensions/system-prompt.ts`](extensions/system-prompt.ts). To load it from a local checkout during development:
+
+```bash
+pi -e /absolute/path/to/pi-custom-system-prompt/extensions/system-prompt.ts
+```
+
+For a hot-reload loop, symlink it into the global extensions directory:
+
+```bash
+ln -s "$(pwd)/extensions/system-prompt.ts" ~/.pi/agent/extensions/system-prompt.ts
+```
+
+Then `/reload` inside pi after each edit.
+
+### Layout
+
+```
+pi-custom-system-prompt/
+├── extensions/
+│   └── system-prompt.ts
+├── package.json
+├── tsconfig.json
+├── README.md
+├── CHANGELOG.md
+└── LICENSE
+```
+
+The `extensions/` directory is a pi convention: any `.ts` file inside it is auto-discovered. The `pi-package` keyword in `package.json` makes the package appear in the [pi package gallery](https://pi.dev/packages).
+
+## License
+
+[MIT](LICENSE)

package/extensions/system-prompt.ts

@@ -0,0 +1,416 @@
+/**
+ * Custom System Prompt Extension for Pi
+ *
+ * Loads a custom system prompt from ~/.pi/agent/system-prompts/ and injects
+ * it into every agent turn. Works with any model or agent — nothing is
+ * hardcoded.
+ *
+ * Multiple .md files can coexist in the prompt directory. Use
+ * /system-prompt-select to pick which one is active.
+ *
+ * Commands
+ * --------
+ *   /system-prompt-info     Show loaded path, size, mode, enabled state
+ *   /system-prompt-toggle   Enable or disable the custom prompt
+ *   /system-prompt-reload   Re-read the selected prompt file from disk
+ *   /system-prompt-mode     Toggle between "replace" and "append" mode
+ *   /system-prompt-show     Print the first ~800 chars of the loaded prompt
+ *   /system-prompt-select   Pick a different prompt file from the directory
+ *
+ * How changes take effect
+ * -----------------------
+ *   The custom prompt is injected via the before_agent_start event, which
+ *   fires on every user message. This means all changes (toggle, reload,
+ *   mode, select) take effect on the very next message you send — no /new
+ *   or session restart required.
+ *
+ * Modes
+ * -----
+ *   append  (default) — Keep Pi's default system prompt as the base and add
+ *                        the custom prompt as an extra section. Safest for
+ *                        most models since Pi's tool descriptions stay
+ *                        authoritative.
+ *   replace           — Use the custom prompt as the base system prompt.
+ *                        Pi's tool descriptions, date, cwd, and user
+ *                        customizations are appended after it.
+ *
+ * State persistence
+ * -----------------
+ *   enabled, mode, and selectedFile are persisted to:
+ *     ~/.pi/agent/state/system-prompt.json
+ *   and survive Pi restarts.
+ *
+ * Footer indicator
+ * ----------------
+ *   system-prompt: disabled              (when disabled)
+ *   system-prompt: claude-code.md        (when enabled, showing filename)
+ *
+ * Environment variables
+ * ---------------------
+ *   PI_SYSTEM_PROMPT_DIR   Override the default prompt directory
+ *                          (default: ~/.pi/agent/system-prompts)
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const DEFAULT_PROMPT_DIR = path.join(
+	os.homedir(),
+	".pi",
+	"agent",
+	"system-prompts",
+);
+
+const STATE_PATH = path.join(
+	os.homedir(),
+	".pi",
+	"agent",
+	"state",
+	"system-prompt.json",
+);
+
+type Mode = "replace" | "append";
+
+interface PersistedState {
+	enabled: boolean;
+	mode: Mode;
+	selectedFile: string;
+}
+
+export default function systemPromptExtension(pi: ExtensionAPI) {
+	const promptDir: string =
+		process.env.PI_SYSTEM_PROMPT_DIR?.trim() || DEFAULT_PROMPT_DIR;
+
+	let enabled: boolean;
+	let mode: Mode;
+	let selectedFile: string;
+	let promptContent: string | null = null;
+	let loadError: string | null = null;
+	let lastLoaded: number | null = null;
+
+	// --- State persistence ---------------------------------------------------
+
+	function loadState(): PersistedState {
+		try {
+			if (!fs.existsSync(STATE_PATH)) {
+				return { enabled: true, mode: "append", selectedFile: "" };
+			}
+			const raw = fs.readFileSync(STATE_PATH, "utf-8");
+			const parsed = JSON.parse(raw) as Partial<PersistedState>;
+			return {
+				enabled: parsed.enabled === false ? false : true,
+				mode: parsed.mode === "replace" ? "replace" : "append",
+				selectedFile:
+					typeof parsed.selectedFile === "string"
+						? parsed.selectedFile
+						: "",
+			};
+		} catch {
+			return { enabled: true, mode: "append", selectedFile: "" };
+		}
+	}
+
+	function saveState(): void {
+		try {
+			fs.mkdirSync(path.dirname(STATE_PATH), { recursive: true });
+			fs.writeFileSync(
+				STATE_PATH,
+				JSON.stringify(
+					{ enabled, mode, selectedFile } satisfies PersistedState,
+					null,
+					2,
+				),
+			);
+		} catch {
+			// best-effort — state persistence failure should not break anything
+		}
+	}
+
+	// Initialize from persisted state
+	const initial = loadState();
+	enabled = initial.enabled;
+	mode = initial.mode;
+	selectedFile = initial.selectedFile;
+
+	// --- Prompt file management ----------------------------------------------
+
+	function listPromptFiles(): string[] {
+		try {
+			if (!fs.existsSync(promptDir)) return [];
+			return fs
+				.readdirSync(promptDir, { withFileTypes: true })
+				.filter((d) => d.isFile() && d.name.endsWith(".md"))
+				.map((d) => d.name)
+				.sort();
+		} catch {
+			return [];
+		}
+	}
+
+	function ensureSelectedFile(): void {
+		const files = listPromptFiles();
+		if (files.length === 0) {
+			selectedFile = "";
+			return;
+		}
+		if (!selectedFile || !files.includes(selectedFile)) {
+			selectedFile = files[0];
+			saveState();
+		}
+	}
+
+	function loadPrompt(): void {
+		ensureSelectedFile();
+
+		if (!selectedFile) {
+			promptContent = null;
+			loadError = fs.existsSync(promptDir)
+				? `no .md files in ${shortPath(promptDir)}`
+				: `directory not found: ${shortPath(promptDir)}`;
+			return;
+		}
+
+		const filePath = path.join(promptDir, selectedFile);
+		try {
+			if (!fs.existsSync(filePath)) {
+				promptContent = null;
+				loadError = `file not found: ${shortPath(filePath)}`;
+				return;
+			}
+			const content = fs.readFileSync(filePath, "utf-8");
+			if (!content.trim()) {
+				promptContent = null;
+				loadError = `file is empty: ${shortPath(filePath)}`;
+				return;
+			}
+			promptContent = content;
+			loadError = null;
+			lastLoaded = Date.now();
+		} catch (err) {
+			promptContent = null;
+			loadError = `read failed: ${err instanceof Error ? err.message : String(err)}`;
+		}
+	}
+
+	function shortPath(p: string): string {
+		const home = os.homedir();
+		return p.startsWith(home) ? `~${p.slice(home.length)}` : p;
+	}
+
+	// --- Footer status -------------------------------------------------------
+
+	function updateStatus(ctx: {
+		hasUI: boolean;
+		ui: { setStatus: (id: string, value: string | undefined) => void };
+	}): void {
+		if (!ctx.hasUI) return;
+		if (enabled && selectedFile) {
+			ctx.ui.setStatus("system-prompt", `system-prompt: ${selectedFile}`);
+		} else if (enabled) {
+			ctx.ui.setStatus("system-prompt", "system-prompt: enabled");
+		} else {
+			ctx.ui.setStatus("system-prompt", "system-prompt: disabled");
+		}
+	}
+
+	// --- Initial load --------------------------------------------------------
+	loadPrompt();
+
+	// --- Command handlers ----------------------------------------------------
+
+	pi.registerCommand("system-prompt-info", {
+		description: "Show custom system prompt info (path, size, mode, state)",
+		handler: async (_args, ctx) => {
+			const files = listPromptFiles();
+			const lines = [
+				`Directory: ${shortPath(promptDir)}`,
+				`File:      ${selectedFile || "(none)"}`,
+				`Mode:      ${mode}`,
+				`Enabled:   ${enabled}`,
+				`Status:    ${loadError ?? "loaded"}`,
+				`Size:      ${promptContent?.length ?? 0} chars`,
+				`Loaded:    ${lastLoaded ? new Date(lastLoaded).toLocaleTimeString() : "never"}`,
+				`Available: ${files.length > 0 ? files.join(", ") : "(none)"}`,
+			];
+			ctx.ui.notify(lines.join("\n"), "info");
+		},
+	});
+
+	pi.registerCommand("system-prompt-toggle", {
+		description: "Enable or disable the custom system prompt",
+		handler: async (_args, ctx) => {
+			enabled = !enabled;
+			saveState();
+			updateStatus(ctx);
+			const state = enabled ? "enabled" : "disabled";
+			ctx.ui.notify(
+				`System prompt ${state}. Takes effect on next message.`,
+				"info",
+			);
+		},
+	});
+
+	pi.registerCommand("system-prompt-reload", {
+		description: "Reload the custom system prompt from disk",
+		handler: async (_args, ctx) => {
+			loadPrompt();
+			updateStatus(ctx);
+			if (loadError) {
+				ctx.ui.notify(`Reload failed: ${loadError}`, "error");
+			} else {
+				ctx.ui.notify(
+					`Reloaded ${selectedFile} (${promptContent!.length} chars). Takes effect on next message.`,
+					"info",
+				);
+			}
+		},
+	});
+
+	pi.registerCommand("system-prompt-select", {
+		description: "Select which .md file to use as the system prompt",
+		handler: async (_args, ctx) => {
+			const files = listPromptFiles();
+			if (files.length === 0) {
+				ctx.ui.notify(
+					`No .md files found in ${shortPath(promptDir)}\nCreate prompt files there to use this extension.`,
+					"error",
+				);
+				return;
+			}
+			if (files.length === 1) {
+				if (files[0] === selectedFile) {
+					ctx.ui.notify(`Only one prompt available: ${files[0]} (already selected)`, "info");
+					return;
+				}
+				selectedFile = files[0];
+				saveState();
+				loadPrompt();
+				updateStatus(ctx);
+				ctx.ui.notify(
+					`Selected: ${selectedFile} (${promptContent?.length ?? 0} chars). Takes effect on next message.`,
+					"info",
+				);
+				return;
+			}
+
+			const choice = await ctx.ui.select(
+				"Select system prompt",
+				files.map((f) => (f === selectedFile ? `${f}  ✓` : f)),
+			);
+			if (!choice) return;
+
+			// Strip the checkmark suffix if present
+			const file = choice.replace(/\s+✓$/, "");
+			if (file === selectedFile) return;
+
+			selectedFile = file;
+			saveState();
+			loadPrompt();
+			updateStatus(ctx);
+			ctx.ui.notify(
+				`Selected: ${selectedFile} (${promptContent?.length ?? 0} chars). Takes effect on next message.`,
+				"info",
+			);
+		},
+	});
+
+	pi.registerCommand("system-prompt-mode", {
+		description: "Toggle mode (replace: use selected file | append: add along with Pi's prompt)",
+		handler: async (args, ctx) => {
+			const arg = args.trim().toLowerCase();
+			if (arg === "replace" || arg === "append") {
+				mode = arg;
+			} else if (arg === "" || arg === "toggle") {
+				mode = mode === "replace" ? "append" : "replace";
+			} else {
+				ctx.ui.notify(`Usage: /system-prompt-mode [replace|append]`, "error");
+				return;
+			}
+			saveState();
+			ctx.ui.notify(
+				`Mode: ${mode}. Takes effect on next message.`,
+				"info",
+			);
+		},
+	});
+
+	pi.registerCommand("system-prompt-show", {
+		description: "Show first ~800 chars of the loaded custom system prompt",
+		handler: async (_args, ctx) => {
+			if (!promptContent) {
+				ctx.ui.notify(`Not loaded: ${loadError ?? "unknown error"}`, "error");
+				return;
+			}
+			const preview = promptContent.slice(0, 800);
+			const tail = promptContent.length > 800 ? "\n\n[... truncated]" : "";
+			ctx.ui.notify(`${preview}${tail}`, "info");
+		},
+	});
+
+	// --- Lifecycle -----------------------------------------------------------
+
+	pi.on("session_start", async (_event, ctx) => {
+		// Re-read on every start so a hand-edited file gets picked up.
+		loadPrompt();
+		updateStatus(ctx);
+	});
+
+	pi.on("session_shutdown", (_event, ctx) => {
+		if (ctx.hasUI) ctx.ui.setStatus("system-prompt", undefined);
+	});
+
+	// --- Inject the prompt ---------------------------------------------------
+
+	pi.on("before_agent_start", async (event) => {
+		// Graceful no-op when disabled or when the prompt file is missing/unreadable.
+		if (!enabled || !promptContent) return;
+
+		const opts = event.systemPromptOptions;
+		const appendSystemPrompt: string = opts?.appendSystemPrompt ?? "";
+		const customPrompt: string = opts?.customPrompt ?? "";
+
+		// Build tool listing preserving tool names
+		const snippets = opts?.toolSnippets ?? {};
+		const toolLines = Object.entries(snippets)
+			.map(([name, desc]) => `- ${name}: ${desc}`)
+			.join("\n");
+		const toolsSection = toolLines
+			? "\n\n## Available tools\n\n" +
+				"The following tools are available in this environment. " +
+				"Use them as described below instead of the tools mentioned in the system prompt above.\n\n" +
+				toolLines
+			: "";
+
+		if (mode === "replace") {
+			// Custom prompt is the base. Stack Pi's tools + user customizations after.
+			const now = new Date();
+			const dateStr = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}-${String(now.getDate()).padStart(2, "0")}`;
+			const cwd = opts?.cwd ?? "unknown";
+			const customSection = customPrompt ? `\n\n${customPrompt}` : "";
+			const appendSection = appendSystemPrompt
+				? `\n\n${appendSystemPrompt}`
+				: "";
+			return {
+				systemPrompt:
+					promptContent +
+					toolsSection +
+					customSection +
+					appendSection +
+					`\nCurrent date: ${dateStr}` +
+					`\nCurrent working directory: ${cwd}`,
+			};
+		}
+
+		// Append mode: keep Pi's prompt, add custom prompt as an extra section.
+		// event.systemPrompt already includes appendSystemPrompt, so no need
+		// to re-add it.
+		return {
+			systemPrompt:
+				event.systemPrompt +
+				"\n\n---\n\n## Custom system prompt\n\n" +
+				promptContent,
+		};
+	});
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+	"name": "pi-custom-system-prompt",
+	"version": "0.1.0",
+	"description": "Pi extension that loads a custom system prompt from `~/.pi/agent/system-prompts/*.md` and injects it on every agent turn, with commands to select, toggle, reload, and switch between replace and append modes.",
+	"type": "module",
+	"license": "MIT",
+	"author": {
+		"name": "Nocte",
+		"email": "nocte19@gmail.com"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/nnocte/pi-custom-system-prompt.git"
+	},
+	"bugs": {
+		"url": "https://github.com/nnocte/pi-custom-system-prompt/issues"
+	},
+	"homepage": "https://github.com/nnocte/pi-custom-system-prompt#readme",
+	"keywords": [
+		"pi-package",
+		"pi-extension",
+		"pi",
+		"extension",
+		"system-prompt",
+		"custom-prompt",
+		"prompt"
+	],
+	"engines": {
+		"node": ">=18"
+	},
+	"files": [
+		"extensions",
+		"README.md",
+		"LICENSE",
+		"CHANGELOG.md"
+	],
+	"pi": {
+		"extensions": [
+			"./extensions"
+		]
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*"
+	}
+}