pi-notifi 0.1.0

package/README.md

@@ -0,0 +1,217 @@
+# pi-notifi
+
+A [pi](https://pi.dev/) package that sends desktop notifications when an
+interactive pi task finishes, unless the tmux window containing that pi agent is
+already visible in Hyprland.
+
+Notifications include a `Focus` action that jumps back to the originating pi
+agent by focusing the saved Hyprland/Ghostty/tmux target.
+
+This package is intentionally developed for an Arch + Hyprland + Ghostty +
+tmux + dunst workflow. If your setup differs, copy/fork it and adapt the small
+focus script.
+
+## Requirements
+
+- Linux with Hyprland
+- Ghostty
+- tmux
+- dunst or another notification daemon compatible with `notify-send` actions
+- `notify-send` from `libnotify`
+- `dunstctl` if using the example keybinds
+- `jq`
+
+On Arch:
+
+```bash
+sudo pacman -S libnotify dunst jq
+```
+
+Your pi shell should be running inside tmux, and that tmux client should be
+inside a Hyprland-managed Ghostty window.
+
+## Install
+
+From npm, once published:
+
+```bash
+pi install npm:pi-notifi
+```
+
+From git:
+
+```bash
+pi install git:github.com/<you>/pi-notifi
+```
+
+For a one-off test without installing:
+
+```bash
+pi -e git:github.com/<you>/pi-notifi
+```
+
+For local development from this checkout:
+
+```bash
+pi -e /absolute/path/to/pi-notifi
+```
+
+The package manifest loads:
+
+```text
+extensions/notifi.ts
+```
+
+No manual symlink is required. The extension invokes the packaged focus helper
+at:
+
+```text
+scripts/notifi-focus
+```
+
+## My dunst / Hyprland setup
+
+Hyprland binds:
+
+```ini
+bind = SUPER, X, exec, dunstctl close
+bind = SUPER, N, exec, dunstctl action 0 && dunstctl close
+```
+
+Dunst mouse behavior:
+
+```ini
+mouse_left_click = do_action, close_current
+mouse_right_click = close_current
+```
+
+Behavior:
+
+- `SUPER X` / right click: close the current notification without action.
+- `SUPER N` / left click: invoke the notification action, then close it.
+- For notifi notifications, the action jumps to the Ghostty/tmux location that
+  produced that specific notification.
+
+## Commands
+
+Inside pi:
+
+```text
+/notifi status
+/notifi test
+/notifi on|enable
+/notifi off|disable
+```
+
+`on` / `off` are persisted into the current pi session.
+
+## Configuration
+
+Configuration is read from the first valid JSON file that exists:
+
+1. `<project>/.pi/notifi.json`
+2. `~/.pi/agent/notifi.json`
+
+Example:
+
+```json
+{
+  "disabled": false,
+  "urgency": "normal",
+  "expireTime": 0,
+  "notifyOnError": true,
+  "notifyOnAbort": false
+}
+```
+
+An example file is included at:
+
+```text
+examples/notifi.json
+```
+
+Available JSON fields:
+
+| Field           | Default                                          | Description                                                         |
+| --------------- | ------------------------------------------------ | ------------------------------------------------------------------- |
+| `disabled`      | `false`                                          | Start disabled                                                      |
+| `title`         | `<tmux-session>:<window-index>` or `pi`          | Notification title                                                  |
+| `body`          | `Task Finished` / `Task Failed` / `Task Aborted` | Notification body                                                   |
+| `urgency`       | `normal` / `critical`                            | notify-send urgency                                                 |
+| `expireTime`    | `0`                                              | notify-send expire time in ms; `0` requests persist until dismissed |
+| `notifyOnError` | `true`                                           | Notify when a task fails                                            |
+| `notifyOnAbort` | `false`                                          | Notify when a task is aborted                                       |
+
+Environment variables with the old `PI_NOTIFI_*` names override JSON for quick
+one-off changes. Invalid JSON config files are ignored so a bad config does not
+break notification delivery.
+
+## Behavior
+
+Notification is suppressed only when all of these are true:
+
+1. pi is running inside tmux.
+2. notifi identifies the tmux session/window containing the pi pane.
+3. an attached tmux client is currently viewing that same tmux window.
+4. that tmux client maps through its process tree to a Hyprland window.
+5. that Hyprland window is on a workspace visible on a monitor.
+
+Pane focus does not matter for notification suppression. If the pi pane is
+anywhere in the visible tmux window, no notification is sent. Notification
+actions still try to focus the original pi pane after switching to the saved
+tmux session/window.
+
+If the tmux window is not visible, notifi sends a persistent notification with a
+`Focus` action:
+
+```text
+<title: tmux-session:window-index>
+<body: Task Finished | Task Failed>
+<action: Focus>
+```
+
+Aborted tasks do not notify by default. Headless/print-mode pi runs do not
+notify.
+
+## Action target cache
+
+Each notification gets a unique UUID target id. The extension writes that
+notification's jump target to:
+
+```text
+${XDG_CACHE_HOME:-~/.cache}/notifi/targets/<target-id>.json
+```
+
+Each notification action captures its own target id, so multiple concurrent pi
+agents and long-lived notifications do not overwrite each other.
+
+`scripts/notifi-focus <target-id>`:
+
+1. validates the target id
+2. reads the target file
+3. deletes the consumed target file
+4. prunes target files older than 24 hours
+5. switches Hyprland to the saved Ghostty workspace/window when possible
+6. switches tmux to the saved session/window
+7. focuses the original pi pane if it still exists
+
+If the original Ghostty window no longer exists but the tmux session/window
+still exists, the action opens Ghostty attached to that tmux session/window. If
+the tmux session/window no longer exists, it exits successfully and does
+nothing.
+
+Target files for notifications dismissed without action are cleaned up the next
+time a notifi action is consumed.
+
+## Edge cases
+
+- If multiple Ghostty windows are attached to the same tmux session, notifi
+  picks the first usable tmux client it can map back to Hyprland.
+- If the saved Ghostty/Hyprland window is stale, notifi falls back to opening
+  Ghostty attached to the saved tmux session/window.
+- If the saved tmux session or window no longer exists, the action exits
+  successfully and does nothing.
+- If the saved tmux pane no longer exists, the action still switches to the
+  saved tmux window and skips pane focus.
+- If the target file is missing, malformed, or older than 24 hours when pruning
+  runs, the action exits successfully and/or removes stale metadata.

package/examples/notifi.json

@@ -0,0 +1,7 @@
+{
+  "disabled": false,
+  "urgency": "normal",
+  "expireTime": 0,
+  "notifyOnError": true,
+  "notifyOnAbort": false
+}

package/extensions/notifi.ts

@@ -0,0 +1,475 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { randomUUID } from "node:crypto";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+type NotifiState = {
+	enabled: boolean;
+};
+
+type TaskStatus = "finished" | "error" | "aborted";
+
+type NotifiConfig = {
+	disabled: boolean;
+	title?: string;
+	body?: string;
+	urgency?: string;
+	expireTime?: string;
+	notifyOnError: boolean;
+	notifyOnAbort: boolean;
+};
+
+type NotifiFileConfig = Partial<{
+	disabled: boolean;
+	title: string;
+	body: string;
+	urgency: string;
+	expireTime: string | number;
+	notifyOnError: boolean;
+	notifyOnAbort: boolean;
+}>;
+
+type TmuxLocation = {
+	sessionId: string;
+	windowId: string;
+	paneId: string;
+	sessionName?: string;
+	windowIndex?: string;
+};
+
+type TmuxClient = {
+	pid: number;
+	tty?: string;
+	sessionId: string;
+	windowId: string;
+};
+
+type HyprClient = {
+	address?: string;
+	pid?: number;
+	mapped?: boolean;
+	hidden?: boolean;
+	visible?: boolean;
+	workspace?: {
+		id?: number;
+	};
+};
+
+type NotifiTarget = {
+	id: string;
+	workspaceId?: number;
+	hyprWindowAddress?: string;
+	tmuxSessionId: string;
+	tmuxWindowId: string;
+	tmuxPaneId: string;
+	tmuxClientTty?: string;
+	timestamp: number;
+};
+
+type HyprMonitor = {
+	activeWorkspace?: {
+		id?: number;
+	};
+	specialWorkspace?: {
+		id?: number;
+	};
+};
+
+const truthy = (value: string | undefined): boolean => {
+	if (!value) return false;
+	return ["1", "true", "yes", "on"].includes(value.toLowerCase());
+};
+
+const env = (name: string): string | undefined => {
+	const value = process.env[name];
+	return value && value.trim().length > 0 ? value : undefined;
+};
+
+const extensionDir = dirname(fileURLToPath(import.meta.url));
+const packageRoot = dirname(extensionDir);
+const focusScriptPath = join(packageRoot, "scripts", "notifi-focus");
+
+const fileExists = async (path: string): Promise<boolean> => {
+	try {
+		await access(path);
+		return true;
+	} catch {
+		return false;
+	}
+};
+
+const cacheHome = (): string => process.env.XDG_CACHE_HOME ?? join(process.env.HOME ?? "/tmp", ".cache");
+
+const targetFile = (targetId: string): string => join(cacheHome(), "notifi", "targets", `${targetId}.json`);
+
+const readConfigFile = async (cwd: string): Promise<NotifiFileConfig> => {
+	const paths = [join(cwd, ".pi", "notifi.json"), join(process.env.HOME ?? "", ".pi", "agent", "notifi.json")];
+
+	for (const path of paths) {
+		if (!path || !(await fileExists(path))) continue;
+
+		try {
+			const raw = await readFile(path, "utf8");
+			return JSON.parse(raw) as NotifiFileConfig;
+		} catch {
+			continue;
+		}
+	}
+
+	return {};
+};
+
+const configString = (value: unknown): string | undefined => {
+	if (typeof value === "string" && value.trim().length > 0) return value;
+	if (typeof value === "number") return String(value);
+	return undefined;
+};
+
+const configBoolean = (value: unknown): boolean | undefined => (typeof value === "boolean" ? value : undefined);
+
+const statusBody = (status: TaskStatus): string => {
+	if (status === "finished") return "Task Finished";
+	if (status === "aborted") return "Task Aborted";
+	return "Task Failed";
+};
+
+const getTmuxSessionTitle = async (pi: ExtensionAPI): Promise<string | undefined> => {
+	const pane = process.env.TMUX_PANE;
+	if (!process.env.TMUX || !pane) return undefined;
+
+	try {
+		const result = await pi.exec("tmux", ["display-message", "-p", "-t", pane, "#S:#{window_index}"], {
+			timeout: 2000,
+		});
+		const title = result.stdout.trim();
+		return title || undefined;
+	} catch {
+		return undefined;
+	}
+};
+
+const getConfig = async (pi: ExtensionAPI, ctx: ExtensionContext, status: TaskStatus): Promise<NotifiConfig> => {
+	const [tmuxTitle, fileConfig] = await Promise.all([getTmuxSessionTitle(pi), readConfigFile(ctx.cwd)]);
+
+	return {
+		disabled: truthy(process.env.PI_NOTIFI_DISABLED) || configBoolean(fileConfig.disabled) === true,
+		title: env("PI_NOTIFI_TITLE") ?? configString(fileConfig.title) ?? tmuxTitle ?? "pi",
+		body: env("PI_NOTIFI_BODY") ?? configString(fileConfig.body) ?? statusBody(status),
+		urgency: env("PI_NOTIFI_URGENCY") ?? configString(fileConfig.urgency) ?? (status === "finished" ? "normal" : "critical"),
+		expireTime: env("PI_NOTIFI_EXPIRE_TIME") ?? configString(fileConfig.expireTime) ?? "0",
+		notifyOnError: !truthy(process.env.PI_NOTIFI_NOTIFY_ON_ERROR_DISABLED) && configBoolean(fileConfig.notifyOnError) !== false,
+		notifyOnAbort: truthy(process.env.PI_NOTIFI_NOTIFY_ON_ABORT) || configBoolean(fileConfig.notifyOnAbort) === true,
+	};
+};
+
+const parseJsonArray = <T>(text: string): T[] | undefined => {
+	try {
+		const value = JSON.parse(text) as unknown;
+		return Array.isArray(value) ? (value as T[]) : undefined;
+	} catch {
+		return undefined;
+	}
+};
+
+const getTmuxLocation = async (pi: ExtensionAPI): Promise<TmuxLocation | undefined> => {
+	const pane = process.env.TMUX_PANE;
+	if (!process.env.TMUX || !pane) return undefined;
+
+	try {
+		const result = await pi.exec("tmux", ["display-message", "-p", "-t", pane, "#{session_id}\t#{window_id}\t#{pane_id}\t#S\t#{window_index}"], {
+			timeout: 2000,
+		});
+		const [sessionId, windowId, paneId, sessionName, windowIndex] = result.stdout.trim().split("\t");
+		if (!sessionId || !windowId || !paneId) return undefined;
+		return { sessionId, windowId, paneId, sessionName, windowIndex };
+	} catch {
+		return undefined;
+	}
+};
+
+const getTmuxClients = async (pi: ExtensionAPI): Promise<TmuxClient[]> => {
+	try {
+		const result = await pi.exec(
+			"tmux",
+			["list-clients", "-F", "#{client_pid}\t#{client_tty}\t#{session_id}\t#{window_id}"],
+			{ timeout: 2000 },
+		);
+
+		return result.stdout
+			.split("\n")
+			.map((line) => line.trim())
+			.filter(Boolean)
+			.map((line) => {
+				const [pidText, tty, sessionId, windowId] = line.split("\t");
+				return { pid: Number(pidText), tty, sessionId, windowId };
+			})
+			.filter((client) => Number.isInteger(client.pid) && client.pid > 0 && !!client.sessionId && !!client.windowId);
+	} catch {
+		return [];
+	}
+};
+
+const getTmuxClientsForWindow = async (pi: ExtensionAPI, location: TmuxLocation): Promise<TmuxClient[]> => {
+	const clients = await getTmuxClients(pi);
+	return clients.filter((client) => client.sessionId === location.sessionId && client.windowId === location.windowId);
+};
+
+const getTmuxClientsForSession = async (pi: ExtensionAPI, location: TmuxLocation): Promise<TmuxClient[]> => {
+	const clients = await getTmuxClients(pi);
+	return clients.filter((client) => client.sessionId === location.sessionId);
+};
+
+const getAncestorPids = async (pid: number): Promise<number[]> => {
+	const pids: number[] = [];
+	let current = pid;
+
+	for (let depth = 0; depth < 64 && current > 1; depth++) {
+		pids.push(current);
+
+		try {
+			const status = await readFile(`/proc/${current}/status`, "utf8");
+			const parent = /^PPid:\s+(\d+)$/m.exec(status)?.[1];
+			if (!parent) break;
+			current = Number(parent);
+		} catch {
+			break;
+		}
+	}
+
+	return pids;
+};
+
+const getVisibleHyprWorkspaceIds = (monitors: HyprMonitor[]): Set<number> => {
+	const ids = new Set<number>();
+	for (const monitor of monitors) {
+		if (typeof monitor.activeWorkspace?.id === "number") ids.add(monitor.activeWorkspace.id);
+		if (typeof monitor.specialWorkspace?.id === "number" && monitor.specialWorkspace.id !== 0) {
+			ids.add(monitor.specialWorkspace.id);
+		}
+	}
+	return ids;
+};
+
+const hyprClientIsUsable = (client: HyprClient): boolean => {
+	return (
+		typeof client.address === "string" &&
+		client.address.length > 0 &&
+		typeof client.workspace?.id === "number" &&
+		client.mapped !== false &&
+		client.hidden !== true
+	);
+};
+
+const hyprClientIsVisible = (client: HyprClient, visibleWorkspaceIds: Set<number>): boolean => {
+	const workspaceId = client.workspace?.id;
+	return hyprClientIsUsable(client) && typeof workspaceId === "number" && visibleWorkspaceIds.has(workspaceId) && client.visible !== false;
+};
+
+const getHyprState = async (pi: ExtensionAPI): Promise<{ clients: HyprClient[]; visibleWorkspaceIds: Set<number> } | undefined> => {
+	try {
+		const [clientsResult, monitorsResult] = await Promise.all([
+			pi.exec("hyprctl", ["clients", "-j"], { timeout: 3000 }),
+			pi.exec("hyprctl", ["monitors", "-j"], { timeout: 3000 }),
+		]);
+
+		const clients = parseJsonArray<HyprClient>(clientsResult.stdout);
+		const monitors = parseJsonArray<HyprMonitor>(monitorsResult.stdout);
+		if (!clients || !monitors) return undefined;
+
+		return { clients, visibleWorkspaceIds: getVisibleHyprWorkspaceIds(monitors) };
+	} catch {
+		return undefined;
+	}
+};
+
+const findHyprWindowForTmuxClient = async (
+	tmuxClientPid: number,
+	hyprClients: HyprClient[],
+): Promise<HyprClient | undefined> => {
+	const ancestorPids = new Set(await getAncestorPids(tmuxClientPid));
+	return hyprClients.find((client) => typeof client.pid === "number" && ancestorPids.has(client.pid) && hyprClientIsUsable(client));
+};
+
+const getPiTmuxWindowTarget = async (pi: ExtensionAPI, targetId: string): Promise<NotifiTarget | undefined> => {
+	const location = await getTmuxLocation(pi);
+	if (!location) return undefined;
+
+	const baseTarget: NotifiTarget = {
+		id: targetId,
+		tmuxSessionId: location.sessionId,
+		tmuxWindowId: location.windowId,
+		tmuxPaneId: location.paneId,
+		timestamp: Date.now(),
+	};
+
+	const [sessionClients, hyprState] = await Promise.all([getTmuxClientsForSession(pi, location), getHyprState(pi)]);
+	if (sessionClients.length === 0 || !hyprState) return baseTarget;
+
+	// Prefer a client already viewing the target window. If none exists, use any
+	// attached client for the same session, focus its Ghostty, then switch it to
+	// the target tmux window. This avoids opening a new Ghostty when the session
+	// is already visible but currently on a different tmux window.
+	const tmuxClients = [
+		...sessionClients.filter((client) => client.windowId === location.windowId),
+		...sessionClients.filter((client) => client.windowId !== location.windowId),
+	];
+
+	for (const tmuxClient of tmuxClients) {
+		const hyprWindow = await findHyprWindowForTmuxClient(tmuxClient.pid, hyprState.clients);
+		if (!hyprWindow || typeof hyprWindow.workspace?.id !== "number" || !hyprWindow.address) continue;
+
+		return {
+			...baseTarget,
+			workspaceId: hyprWindow.workspace.id,
+			hyprWindowAddress: hyprWindow.address,
+			tmuxClientTty: tmuxClient.tty,
+		};
+	}
+
+	return baseTarget;
+};
+
+const piTmuxWindowIsVisible = async (pi: ExtensionAPI): Promise<boolean> => {
+	const location = await getTmuxLocation(pi);
+	if (!location) return false;
+
+	const [tmuxClients, hyprState] = await Promise.all([getTmuxClientsForWindow(pi, location), getHyprState(pi)]);
+	if (tmuxClients.length === 0 || !hyprState) return false;
+
+	for (const tmuxClient of tmuxClients) {
+		const hyprWindow = await findHyprWindowForTmuxClient(tmuxClient.pid, hyprState.clients);
+		if (hyprWindow && hyprClientIsVisible(hyprWindow, hyprState.visibleWorkspaceIds)) return true;
+	}
+
+	return false;
+};
+
+const writeTarget = async (target: NotifiTarget | undefined): Promise<void> => {
+	if (!target) return;
+	const path = targetFile(target.id);
+	await mkdir(dirname(path), { recursive: true });
+	await writeFile(path, `${JSON.stringify(target, null, 2)}\n`, "utf8");
+};
+
+const getStatus = (messages: unknown[]): TaskStatus => {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const message = messages[i] as { role?: string; stopReason?: string };
+		if (message?.role !== "assistant") continue;
+		if (message.stopReason === "error") return "error";
+		if (message.stopReason === "aborted") return "aborted";
+		return "finished";
+	}
+	return "finished";
+};
+
+const sendNotification = async (pi: ExtensionAPI, config: NotifiConfig, targetId: string | undefined): Promise<void> => {
+	await pi.exec(
+		"bash",
+		[
+			"-c",
+			[
+				"set -euo pipefail",
+				"title=$1",
+				"body=$2",
+				"urgency=$3",
+				"expire_time=$4",
+				"target_id=$5",
+				"focus_script=$6",
+				"args=(--app-name pi --urgency \"$urgency\" --expire-time \"$expire_time\")",
+				"if [[ -z \"$target_id\" ]]; then",
+				"  notify-send \"${args[@]}\" \"$title\" \"$body\"",
+				"else",
+				"  args=(--wait --action=focus=Focus \"${args[@]}\")",
+				"  (",
+				"    action=$(notify-send \"${args[@]}\" \"$title\" \"$body\" || true)",
+				"    if [[ \"$action\" == \"focus\" ]]; then",
+				"      \"$focus_script\" \"$target_id\" >/dev/null 2>&1 || true",
+				"    fi",
+				"  ) >/dev/null 2>&1 &",
+				"fi",
+			].join("\n"),
+			"notifi-send",
+			config.title ?? "pi",
+			config.body ?? "Task Finished",
+			config.urgency ?? "normal",
+			config.expireTime ?? "0",
+			targetId ?? "",
+			focusScriptPath,
+		],
+		{ timeout: 5000 },
+	);
+};
+
+const notify = async (pi: ExtensionAPI, ctx: ExtensionContext, status: TaskStatus) => {
+	const config = await getConfig(pi, ctx, status);
+	if (config.disabled) return;
+	if (status === "aborted" && !config.notifyOnAbort) return;
+	if (status === "error" && !config.notifyOnError) return;
+	if (await piTmuxWindowIsVisible(pi)) return;
+
+	try {
+		const targetId = randomUUID();
+		const target = await getPiTmuxWindowTarget(pi, targetId);
+		await writeTarget(target);
+		await sendNotification(pi, config, target?.id);
+	} catch (error) {
+		if (ctx.hasUI) {
+			ctx.ui.notify(
+				`notifi: notify-send failed: ${error instanceof Error ? error.message : String(error)}`,
+				"warning",
+			);
+		}
+	}
+};
+
+export default function (pi: ExtensionAPI) {
+	let state: NotifiState = {
+		enabled: true,
+	};
+
+	pi.on("session_start", async (_event, ctx) => {
+		for (const entry of ctx.sessionManager.getEntries()) {
+			const custom = entry as { type?: string; customType?: string; data?: Partial<NotifiState> };
+			if (custom.type === "custom" && custom.customType === "notifi-state" && typeof custom.data?.enabled === "boolean") {
+				state.enabled = custom.data.enabled;
+			}
+		}
+	});
+
+	pi.on("agent_end", async (event, ctx) => {
+		if (!ctx.hasUI) return;
+		if (!state.enabled) return;
+		// If queued steering/follow-up messages remain, this is not the final idle point yet.
+		if (ctx.hasPendingMessages()) return;
+		await notify(pi, ctx, getStatus(event.messages as unknown[]));
+	});
+
+	pi.registerCommand("notifi", {
+		description: "Manage desktop notifications when pi finishes a task: status | test | on/enable | off/disable",
+		handler: async (args, ctx) => {
+			const subcommand = args.trim().toLowerCase() || "status";
+			if (subcommand === "on" || subcommand === "enable") {
+				state.enabled = true;
+				pi.appendEntry("notifi-state", { enabled: true });
+				ctx.ui.notify("notifi enabled", "info");
+				return;
+			}
+
+			if (subcommand === "off" || subcommand === "disable") {
+				state.enabled = false;
+				pi.appendEntry("notifi-state", { enabled: false });
+				ctx.ui.notify("notifi disabled", "info");
+				return;
+			}
+
+			if (subcommand === "test") {
+				await notify(pi, ctx, "finished");
+				ctx.ui.notify("notifi test sent", "info");
+				return;
+			}
+
+			ctx.ui.notify(`notifi is ${state.enabled ? "enabled" : "disabled"}`, "info");
+		},
+	});
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "pi-notifi",
+  "version": "0.1.0",
+  "description": "Pi extension that sends focus-aware desktop notifications when pi finishes a task.",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "notifications",
+    "notification",
+    "notify",
+    "notice",
+    "warning",
+    "ping",
+    "notify-send",
+    "hyprland",
+    "tmux",
+    "ghostty",
+    "dunst"
+  ],
+  "type": "module",
+  "files": [
+    "extensions/",
+    "scripts/",
+    "examples/",
+    "README.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "check": "tsc --noEmit && bash -n scripts/notifi-focus"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/notifi.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "latest",
+    "@types/node": "latest",
+    "typescript": "latest"
+  }
+}

package/scripts/notifi-focus

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+target_id="${1:-}"
+targets_dir="${XDG_CACHE_HOME:-$HOME/.cache}/notifi/targets"
+
+prune_targets() {
+  [[ -d "$targets_dir" ]] || return 0
+  find "$targets_dir" -maxdepth 1 -type f -name '*.json' -mmin +1440 -delete 2>/dev/null || true
+}
+
+if [[ -z "$target_id" ]]; then
+  prune_targets
+  exit 0
+fi
+
+# notifi currently generates UUIDs. Reject anything path-like so this helper
+# cannot be used to read/delete files outside the target cache directory.
+if [[ ! "$target_id" =~ ^[0-9a-fA-F-]{36}$ ]]; then
+  prune_targets
+  exit 0
+fi
+
+state_file="$targets_dir/${target_id}.json"
+
+if [[ ! -f "$state_file" ]]; then
+  prune_targets
+  exit 0
+fi
+
+consume_bad_target() {
+  rm -f -- "$state_file"
+  prune_targets
+  exit 0
+}
+
+workspace_id="$(jq -r '.workspaceId // empty' "$state_file" 2>/dev/null)" || consume_bad_target
+hypr_window_address="$(jq -r '.hyprWindowAddress // empty' "$state_file" 2>/dev/null)" || consume_bad_target
+tmux_session_id="$(jq -r '.tmuxSessionId // empty' "$state_file" 2>/dev/null)" || consume_bad_target
+tmux_window_id="$(jq -r '.tmuxWindowId // empty' "$state_file" 2>/dev/null)" || consume_bad_target
+tmux_pane_id="$(jq -r '.tmuxPaneId // empty' "$state_file" 2>/dev/null)" || consume_bad_target
+tmux_client_tty="$(jq -r '.tmuxClientTty // empty' "$state_file" 2>/dev/null)" || consume_bad_target
+
+rm -f -- "$state_file"
+prune_targets
+
+if [[ -z "$tmux_session_id" || -z "$tmux_window_id" ]]; then
+  exit 0
+fi
+
+if ! tmux has-session -t "$tmux_session_id" 2>/dev/null; then
+  exit 0
+fi
+
+if ! tmux list-windows -t "$tmux_session_id" -F '#{window_id}' | grep -Fxq "$tmux_window_id"; then
+  exit 0
+fi
+
+hypr_window_exists() {
+  [[ -n "$hypr_window_address" ]] && \
+    hyprctl clients -j | jq -e --arg address "$hypr_window_address" '.[] | select(.address == $address)' >/dev/null
+}
+
+select_saved_pane() {
+  [[ -n "$tmux_pane_id" ]] || return 0
+  tmux list-panes -a -F '#{pane_id}' 2>/dev/null | grep -Fxq "$tmux_pane_id" || return 0
+  tmux select-pane -t "$tmux_pane_id" 2>/dev/null || true
+}
+
+if [[ -n "$workspace_id" ]]; then
+  hyprctl dispatch workspace "$workspace_id" >/dev/null || true
+fi
+
+if hypr_window_exists; then
+  hyprctl dispatch focuswindow "address:$hypr_window_address" >/dev/null || true
+
+  if [[ -n "$tmux_client_tty" ]]; then
+    tmux switch-client -c "$tmux_client_tty" -t "$tmux_window_id" 2>/dev/null || tmux select-window -t "$tmux_window_id"
+  else
+    tmux select-window -t "$tmux_window_id"
+  fi
+  select_saved_pane
+else
+  tmux select-window -t "$tmux_window_id"
+  select_saved_pane
+  ghostty -e tmux attach-session -t "$tmux_session_id" >/dev/null 2>&1 &
+fi