pi-soul 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Akshay Patel
+
+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,63 @@
+# pi-soul
+
+Give your [pi](https://pi.dev) agent a **soul** — a persistent persona/profile that tailors every session's output.
+
+Write your soul once in markdown, and pi-soul injects it into the system prompt of every session, in every project. Your agent stops being generic and starts being *yours*.
+
+## Install
+
+```bash
+# from npm
+pi install npm:pi-soul
+
+# or straight from git
+pi install git:github.com/Akshay-patel7/pi-soul
+```
+
+Try it without installing:
+
+```bash
+pi -e npm:pi-soul
+```
+
+## Usage
+
+| Command      | What it does                                            |
+| ------------ | ------------------------------------------------------- |
+| `/soul`      | Show the active soul (source, path, preview) and state  |
+| `/soul edit` | Create or edit your soul in an editor                   |
+| `/soul on`   | Enable soul injection for this session (default)        |
+| `/soul off`  | Disable soul injection for this session                 |
+
+When a soul is active you'll see `soul: global` (or `soul: project`) in the footer.
+
+## Where your soul lives
+
+pi-soul resolves the soul fresh on every turn, so edits apply immediately:
+
+1. **Project soul** — `<project>/.pi/soul.md` (only in trusted projects). Wins when present. Great for team-shared personas checked into a repo.
+2. **Global soul** — `~/.pi/agent/soul.md`. Your default persona everywhere.
+
+The soul file is plain markdown — edit it with `/soul edit` or any editor.
+
+## Example soul
+
+```markdown
+# My Soul
+
+You are an elite software engineer — the greatest the world has ever seen.
+Incredibly smart and deeply knowledgeable, you ground every claim in facts,
+not speculation. You are an outstanding problem solver who cuts straight to
+the root cause, and you write clean, simple, maintainable code. You are one
+of those rare engineers that are hard to come by.
+```
+
+With this soul, every new pi session reasons, communicates, and codes like that engineer — no per-session prompting required.
+
+## How it works
+
+A single TypeScript extension listens for pi's `before_agent_start` event and appends your soul to the system prompt under a `# Your Soul` section. No build step, no runtime dependencies — pi loads the TypeScript source directly.
+
+## License
+
+MIT

package/extensions/soul.ts

@@ -0,0 +1,163 @@
+/**
+ * pi-soul — give your pi agent a soul.
+ *
+ * A "soul" is a persistent persona/profile written in markdown. When present,
+ * it is appended to the system prompt on every turn so the agent's output is
+ * tailored to it in every session.
+ *
+ * Soul resolution (checked fresh on each agent start):
+ *   1. Project soul: <cwd>/.pi/soul.md   (only when the project is trusted)
+ *   2. Global soul:  ~/.pi/agent/soul.md
+ *
+ * Commands:
+ *   /soul        show the active soul (source, path, preview) and state
+ *   /soul edit   create or edit the soul in an editor
+ *   /soul on     enable soul injection for this session (default)
+ *   /soul off    disable soul injection for this session
+ */
+
+import {
+	CONFIG_DIR_NAME,
+	getAgentDir,
+	type ExtensionAPI,
+	type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+const STARTER_SOUL = `# My Soul
+
+You are an elite software engineer — the greatest the world has ever seen.
+Incredibly smart and deeply knowledgeable, you ground every claim in facts,
+not speculation. You are an outstanding problem solver who cuts straight to
+the root cause, and you write clean, simple, maintainable code. You are one
+of those rare engineers that are hard to come by.
+
+<!-- Edit this file to shape your agent's persona. Delete anything you like. -->
+`;
+
+interface ResolvedSoul {
+	source: "project" | "global";
+	path: string;
+	content: string;
+}
+
+function globalSoulPath(): string {
+	return join(getAgentDir(), "soul.md");
+}
+
+function projectSoulPath(cwd: string): string {
+	return join(cwd, CONFIG_DIR_NAME, "soul.md");
+}
+
+function readSoulFile(path: string): string | undefined {
+	try {
+		if (!existsSync(path)) return undefined;
+		const content = readFileSync(path, "utf8").trim();
+		return content.length > 0 ? content : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Resolve the active soul: project (trusted only) wins over global. */
+function resolveSoul(ctx: ExtensionContext): ResolvedSoul | undefined {
+	if (ctx.isProjectTrusted()) {
+		const path = projectSoulPath(ctx.cwd);
+		const content = readSoulFile(path);
+		if (content) return { source: "project", path, content };
+	}
+	const path = globalSoulPath();
+	const content = readSoulFile(path);
+	if (content) return { source: "global", path, content };
+	return undefined;
+}
+
+export default function soulExtension(pi: ExtensionAPI) {
+	let enabled = true;
+
+	const updateStatus = (ctx: ExtensionContext) => {
+		if (!ctx.hasUI) return;
+		const soul = enabled ? resolveSoul(ctx) : undefined;
+		ctx.ui.setStatus("soul", soul ? `soul: ${soul.source}` : undefined);
+	};
+
+	pi.on("session_start", async (_event, ctx) => {
+		updateStatus(ctx);
+	});
+
+	// Inject the soul into the system prompt on every turn.
+	pi.on("before_agent_start", async (event, ctx) => {
+		if (!enabled) return undefined;
+		const soul = resolveSoul(ctx);
+		if (!soul) return undefined;
+		return {
+			systemPrompt: `${event.systemPrompt}
+
+# Your Soul
+
+The user has given you the following soul — a persona and profile you must
+embody. Let it shape your reasoning, tone, and output in every response,
+while still completing every task correctly and accurately.
+
+${soul.content}`,
+		};
+	});
+
+	pi.registerCommand("soul", {
+		description: "Manage your agent's soul (persona). Usage: /soul [edit|on|off]",
+		handler: async (args, ctx) => {
+			const sub = (args ?? "").trim().toLowerCase();
+
+			if (sub === "on" || sub === "off") {
+				enabled = sub === "on";
+				updateStatus(ctx);
+				ctx.ui.notify(enabled ? "Soul enabled" : "Soul disabled for this session", "info");
+				return;
+			}
+
+			if (sub === "edit") {
+				if (!ctx.hasUI) {
+					ctx.ui.notify(`No interactive UI. Edit your soul directly: ${globalSoulPath()}`, "warning");
+					return;
+				}
+				// Edit the active soul file; fall back to creating the global one.
+				const active = resolveSoul(ctx);
+				const path = active?.path ?? globalSoulPath();
+				const prefill = active?.content ?? STARTER_SOUL;
+				const result = await ctx.ui.editor(`Edit soul (${path})`, prefill);
+				if (result === undefined) {
+					ctx.ui.notify("Soul edit cancelled", "info");
+					return;
+				}
+				mkdirSync(dirname(path), { recursive: true });
+				writeFileSync(path, result, "utf8");
+				updateStatus(ctx);
+				ctx.ui.notify(
+					result.trim().length > 0 ? `Soul saved to ${path}` : `Soul cleared (${path} is empty)`,
+					"info",
+				);
+				return;
+			}
+
+			if (sub === "") {
+				const soul = resolveSoul(ctx);
+				if (!soul) {
+					ctx.ui.notify(
+						`No soul found. Run /soul edit to create one (global: ${globalSoulPath()})`,
+						"info",
+					);
+					return;
+				}
+				const preview = soul.content.split("\n").find((l) => l.trim() && !l.startsWith("#")) ?? "";
+				ctx.ui.notify(
+					`Soul: ${soul.source} (${soul.path}) — ${enabled ? "enabled" : "disabled"}\n${preview}`,
+					"info",
+				);
+				return;
+			}
+
+			ctx.ui.notify("Usage: /soul [edit|on|off]", "warning");
+		},
+	});
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "pi-soul",
+  "version": "0.1.0",
+  "description": "Give your pi agent a soul — a persistent persona that tailors every session.",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "persona",
+    "profile",
+    "soul"
+  ],
+  "license": "MIT",
+  "author": "Akshay Patel",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Akshay-patel7/pi-soul.git"
+  },
+  "files": [
+    "extensions",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "latest",
+    "typescript": "^5"
+  }
+}