pi-sticky-prompt 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pi-sticky-prompt contributors
+
+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,278 @@
+# pi-sticky-prompt
+
+> Always-on-top, full-width macOS prompt bar for [pi](https://github.com/earendil-works/pi).
+
+![sticky bar expanded](./assets/sticky-bar-expanded.png)
+
+Pi runs in normal terminal scrollback (not alternate-screen mode), so when
+you scroll the terminal up to read history, the input prompt scrolls out
+of view with everything else. **pi-sticky-prompt** solves that with a
+tiny native macOS window that sits permanently on top of every other
+window, on every space, and talks to your live pi sessions over a Unix
+domain socket.
+
+You can scroll the terminal as much as you want — the prompt stays glued
+to the bottom of the screen.
+
+### Demo
+
+https://github.com/user-attachments/assets/4b8a7e41-6df2-4bf2-98d3-4cd1513aefd9
+
+| Collapsed | Session picker |
+| --- | --- |
+| ![collapsed](./assets/sticky-bar-collapsed.png) | ![session picker](./assets/sticky-bar-session-picker.png) |
+
+```
+┌──────────────────────────────────┐         ┌──────────────────────────┐
+│ Terminal running pi              │  UDS    │ PiStickyPrompt.app       │
+│ (interactive, scrollback intact) │ ◄────── │ floating NSPanel         │
+│                                  │         │ always on top            │
+└──────────────────────────────────┘         └──────────────────────────┘
+```
+
+## Features
+
+- 🪟 **Native floating window** — `NSPanel` with `.floating` level + `.canJoinAllSpaces`. Visible above every app, every space, even fullscreen Ghostty / Terminal / iTerm.
+- 🖥️ **Auto-docked** to the bottom edge of whichever screen has a terminal app open. Plug in a monitor or move Terminal across screens — the bar follows.
+- 🔒 **Lock / unlock** — locked: full-width pinned to bottom; unlocked: free-move, resize, drag between monitors.
+- 📜 **Multi-session aware** — every pi process publishes its own socket; the bar lists all live sessions in a picker (`⌘L`) and remembers your selection across launches.
+- ⌨️ **Global hotkey** `⌘⌥P` to toggle visibility from anywhere on the system.
+- 📉 **Collapse to a one-line preview** of long input (`⌘M`); expanding grows upward leaving the toolbar flush with the screen edge.
+- 🚦 **Status echo** — model, session name, and a live streaming indicator (green = idle, yellow = streaming, red = disconnected).
+- ↩️ **Auto-focus the terminal** after sending — keystrokes you make right after pressing Enter land in the terminal hosting that pi session, not in the bar.
+- 🛑 **Abort current pi turn** with `Esc`; press `Esc` twice quickly to hide the bar.
+
+## Requirements
+
+- macOS 13+
+- A pi installation (`@mariozechner/pi-coding-agent`)
+- Xcode command-line tools for building the HUD: `xcode-select --install`
+- Swift 5.9+ (ships with current macOS)
+
+Tested with Ghostty, Terminal.app, iTerm2, Alacritty, WezTerm, kitty, and Warp.
+
+## Install
+
+pi-sticky-prompt has two halves and each lives in the registry that
+fits it best:
+
+| Half | What it does | Where it lives |
+| --- | --- | --- |
+| **Extension** | Lets pi sessions expose themselves over a Unix domain socket so the HUD can find them | npm — `npm:pi-sticky-prompt` |
+| **HUD app** | The native macOS floating window itself | Homebrew cask — `pi-sticky-prompt` |
+
+### 1. Install the pi extension
+
+```bash
+pi install npm:pi-sticky-prompt
+```
+
+Reload pi (`/reload`) or start a fresh session. Each session will now
+publish a socket + descriptor under `~/.pi/agent/sockets/`.
+
+### 2. Install the macOS HUD
+
+**Recommended — Homebrew:**
+
+```bash
+brew tap alonmartin2222/pi
+brew install --cask pi-sticky-prompt
+```
+
+First launch may show a Gatekeeper prompt because the app is ad-hoc
+signed — right-click `PiStickyPrompt.app` in `/Applications` and pick
+*Open* once to whitelist it.
+
+**Alternative — download the prebuilt zip from a GitHub release:**
+
+1. Grab `PiStickyPrompt.app.zip` from <https://github.com/alonmartin2222/pi-sticky-prompt/releases/latest>
+2. Unzip and drag `PiStickyPrompt.app` into `/Applications`
+
+**Alternative — build from source:**
+
+```bash
+git clone https://github.com/alonmartin2222/pi-sticky-prompt.git
+cd pi-sticky-prompt
+make install        # builds and copies the .app to ~/Applications
+make run            # builds + opens it
+```
+
+### 3. Launch
+
+Open `PiStickyPrompt.app` (Spotlight / Launchpad / `open -a PiStickyPrompt`).
+Add it to your Login Items in System Settings if you want it always
+running. Press **⌘⌥P** to toggle the bar.
+
+## Usage
+
+1. Start any number of `pi` sessions in any terminal. Each session writes:
+   - **socket**:     `~/.pi/agent/sockets/pi-<pid>.sock`
+   - **descriptor**: `~/.pi/agent/sockets/pi-<pid>.json`
+2. Launch `PiStickyPrompt.app`. It scans the descriptor directory and
+   auto-attaches to the most-recent live session (or the one you previously
+   chose).
+3. Type. **Enter** sends; **Shift+Enter** inserts a newline.
+
+### Keys
+
+While the bar has keyboard focus:
+
+| Key                | Action                                              |
+| ------------------ | --------------------------------------------------- |
+| **⌘⌥P** *(global)* | Toggle bar visibility from anywhere on the system   |
+| **Enter**          | Send the prompt to the attached pi session          |
+| **Shift+Enter**    | Insert a newline inside the editor                  |
+| **Esc**            | Abort current pi turn (twice quickly: hide bar)     |
+| **⌘M**             | Collapse to one-line preview / expand back          |
+| **⌘L**             | Open the session picker                             |
+| **⌘W**             | Hide the bar                                        |
+
+A status-bar icon (`π▸`) also exposes Toggle / Pick Session / Quit.
+
+### Toolbar
+
+```
+[●  session-name  │  model/name]                       [≡  🔒  ▲]
+ │   │                │                                 │   │   │
+ │   │                │                                 │   │   └ collapse / expand
+ │   │                │                                 │   └ lock / unlock
+ │   │                │                                 └ session picker
+ │   │                └ provider/model
+ │   └ session name (or cwd basename if unnamed)
+ └ status dot: green = idle · yellow = streaming · red = disconnected
+```
+
+When idle, sending a prompt triggers a new turn. When pi is mid-turn (yellow
+dot), sending **steers** the running turn instead of queueing — same
+behaviour as typing in the pi TUI itself.
+
+### Lock vs unlock
+
+- **🔒 locked** *(default)* — full screen-width, pinned to the bottom of
+  whichever screen has a terminal app open. Re-snaps automatically on
+  display changes (`NSApplication.didChangeScreenParametersNotification`).
+- **🔓 unlocked** *(orange tint)* — drag from any background pixel to
+  move, drag from the edges to resize, drag freely between monitors. The
+  last unlocked frame is remembered. Click again to re-dock.
+
+## Architecture
+
+Two pieces:
+
+```
+extensions/sticky-prompt.ts        ← TypeScript pi extension
+PiStickyPrompt/                    ← Swift Package for the macOS HUD
+├── Package.swift
+├── Sources/PiStickyPrompt/
+│   ├── main.swift                 ← entry point, sets accessory activation
+│   ├── AppDelegate.swift          ← menu-bar item + global hotkey wiring
+│   ├── HUDController.swift        ← owns the panel, picks a session, locking
+│   ├── HUDPanel.swift             ← NSPanel subclass; canBecomeKey overrides
+│   ├── PromptView.swift           ← top toolbar + editor + status row
+│   ├── PromptTextView.swift       ← NSTextView with Enter/Esc/⌘M handling
+│   ├── BridgeClient.swift         ← UDS client; line-delimited JSON protocol
+│   ├── SessionDiscovery.swift     ← scans ~/.pi/agent/sockets for live pids
+│   ├── TerminalScreen.swift       ← finds which NSScreen hosts a terminal
+│   ├── TerminalLocator.swift      ← walks parent PIDs to find owning terminal
+│   └── Hotkey.swift               ← Carbon RegisterEventHotKey wrapper
+└── make-app.sh                    ← bundles the binary into a .app
+```
+
+### Wire protocol
+
+Line-delimited JSON over the Unix domain socket (LF only, both directions):
+
+```
+server -> client
+  {"type":"hello",  pid, cwd, sessionFile, sessionName?, model?, streaming, started}
+  {"type":"state",  streaming, model?, sessionName?}
+  {"type":"ack",    ok, command:"prompt"|"abort", error?}
+  {"type":"bye"}
+
+client -> server
+  {"type":"prompt", text}
+  {"type":"abort"}
+  {"type":"ping"}
+```
+
+You can drive the bridge from the shell to verify it without the HUD:
+
+```bash
+SOCK=$(ls -t ~/.pi/agent/sockets/pi-*.sock | head -1)
+echo '{"type":"prompt","text":"hello from nc"}' | nc -U "$SOCK"
+```
+
+### Permissions
+
+- **No Accessibility permission** required. We never use AX APIs.
+- **No Screen Recording permission** required. `CGWindowListCopyWindowInfo`
+  returns window owner + bounds without it; we read only those, never
+  pixels or window names.
+- The global hotkey uses Carbon's `RegisterEventHotKey`, which works for
+  accessory (LSUIElement) apps without any permission prompts.
+
+### Auto-focus to terminal on send
+
+After a successful `prompt` ack, the HUD walks the BSD process tree
+upward from the pi session's PID using `sysctl(KERN_PROC_PID)` until it
+finds an ancestor whose bundle ID matches a known terminal app (Ghostty,
+Terminal, iTerm2, Alacritty, WezTerm, kitty, Warp, Hyper). It then calls
+`NSRunningApplication.activate(.activateIgnoringOtherApps)` on that app.
+This brings the terminal to the front so your next keystroke goes to pi
+output instead of the now-empty input bar.
+
+## Multiple pi sessions
+
+The pi extension publishes one socket + descriptor per pi process. The
+HUD scans the directory, hides any whose PID is no longer running, and
+shows the rest in the session picker (`⌘L`). The current selection is
+persisted in `UserDefaults` as `pi.preferredPID` so re-launches reattach
+to the same session if it's still alive.
+
+Heads-up: macOS doesn't expose per-window activation through
+`NSRunningApplication`. If you have multiple windows of the same terminal
+app, only the most-recently-focused one of that app comes forward. Per-
+window raising would require Accessibility permission, which this project
+deliberately avoids.
+
+## Disabling
+
+- Hide the bar with `⌘⌥P` or quit it from the menu bar.
+- To remove the extension half: `pi remove npm:pi-sticky-prompt` (or
+  whichever spec you used to install it).
+- To keep the extension but stop the HUD: just don't launch the app. The
+  socket sits unused; pi sessions don't notice.
+
+## Limitations
+
+- The bar is **viewport-pinned** because it is a separate macOS window,
+  not because pi affects terminal scrollback. Terminal scrollback itself
+  is unchanged.
+- One HUD process per machine is the intended deployment. Multiple HUDs
+  can connect to the same socket but they will all see each other's
+  state echoes.
+- macOS only. The HUD uses AppKit. The pi extension itself is
+  cross-platform Node code, but the only client implementation today is
+  the macOS app.
+- Tested only on macOS 13+ on Apple Silicon. Intel builds should work
+  (the binary is built for `arm64` only by default — drop in a
+  universal slice in `make-app.sh` if needed).
+
+## Contributing
+
+Issues and PRs welcome at <https://github.com/alonmartin2222/pi-sticky-prompt>.
+The codebase is intentionally small:
+
+- `extensions/sticky-prompt.ts` — ~250 lines TypeScript
+- `PiStickyPrompt/Sources/PiStickyPrompt/*.swift` — ~900 lines Swift
+
+Build the Swift app with `make debug` to get faster rebuild loops while
+iterating. Use `swift build -c debug` directly if you don't need the
+`.app` bundle.
+
+The Carbon `RegisterEventHotKey` symbol signature is `'piPb'` (`0x70695062`)
+— historical, but kept stable so config files stay portable.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/extensions/sticky-prompt.ts

@@ -0,0 +1,252 @@
+/**
+ * pi-sticky-prompt
+ *
+ * Exposes the active pi session over a Unix domain socket so an external,
+ * always-on-top input HUD (PiStickyPrompt.app) can send prompts and receive
+ * basic state. Each pi process gets its own socket; a sibling JSON
+ * descriptor file is published so the HUD can list and pick a session.
+ *
+ * Layout:
+ *   ~/.pi/agent/sockets/pi-<pid>.sock   — server socket
+ *   ~/.pi/agent/sockets/pi-<pid>.json   — descriptor (pid, cwd, started, ...)
+ *
+ * Wire protocol (line-delimited JSON, both directions, LF only):
+ *
+ *   server -> client
+ *     {"type":"hello", pid, cwd, sessionFile, sessionName?, model?, streaming, started}
+ *     {"type":"state", streaming, model?, sessionName?}
+ *     {"type":"ack",   ok:bool, command:"prompt"|"abort", error?:string}
+ *     {"type":"bye"}
+ *
+ *   client -> server
+ *     {"type":"prompt", text:string}
+ *     {"type":"abort"}
+ *     {"type":"ping"}
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { createServer, type Server, type Socket } from "node:net";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const SOCK_DIR = join(homedir(), ".pi", "agent", "sockets");
+const SOCK_PATH = join(SOCK_DIR, `pi-${process.pid}.sock`);
+const DESC_PATH = join(SOCK_DIR, `pi-${process.pid}.json`);
+
+interface ClientLine {
+	type?: string;
+	text?: string;
+}
+
+interface ExtState {
+	streaming: boolean;
+	model?: string;
+	sessionName?: string;
+	sessionFile?: string;
+}
+
+export default function (pi: ExtensionAPI) {
+	let server: Server | null = null;
+	const clients = new Set<Socket>();
+	const state: ExtState = { streaming: false };
+
+	const send = (sock: Socket, msg: unknown) => {
+		try {
+			sock.write(JSON.stringify(msg) + "\n");
+		} catch {
+			/* client gone */
+		}
+	};
+	const broadcast = (msg: unknown) => {
+		for (const c of clients) send(c, msg);
+	};
+
+	const writeDescriptor = async () => {
+		const desc = {
+			pid: process.pid,
+			cwd: process.cwd(),
+			socket: SOCK_PATH,
+			started: Date.now(),
+			sessionFile: state.sessionFile,
+			sessionName: state.sessionName,
+			model: state.model,
+			streaming: state.streaming,
+		};
+		await writeFile(DESC_PATH, JSON.stringify(desc, null, 2));
+	};
+
+	const handleLine = async (sock: Socket, line: string, ctx: any) => {
+		let msg: ClientLine;
+		try {
+			msg = JSON.parse(line);
+		} catch {
+			send(sock, { type: "ack", ok: false, command: "?", error: "bad json" });
+			return;
+		}
+
+		if (msg.type === "ping") {
+			send(sock, { type: "pong" });
+			return;
+		}
+
+		if (msg.type === "prompt") {
+			const text = (msg.text ?? "").trim();
+			if (!text) {
+				send(sock, { type: "ack", ok: false, command: "prompt", error: "empty" });
+				return;
+			}
+			try {
+				if (state.streaming) {
+					pi.sendUserMessage(text, { deliverAs: "steer" });
+				} else {
+					pi.sendUserMessage(text);
+				}
+				send(sock, { type: "ack", ok: true, command: "prompt" });
+			} catch (e: any) {
+				send(sock, { type: "ack", ok: false, command: "prompt", error: String(e?.message ?? e) });
+			}
+			return;
+		}
+
+		if (msg.type === "abort") {
+			try {
+				if (typeof ctx?.abort === "function") {
+					ctx.abort();
+				}
+				send(sock, { type: "ack", ok: true, command: "abort" });
+			} catch (e: any) {
+				send(sock, { type: "ack", ok: false, command: "abort", error: String(e?.message ?? e) });
+			}
+			return;
+		}
+
+		send(sock, { type: "ack", ok: false, command: msg.type ?? "?", error: "unknown command" });
+	};
+
+	const onConnection = (sock: Socket, ctx: any) => {
+		clients.add(sock);
+		sock.setEncoding("utf8");
+
+		send(sock, {
+			type: "hello",
+			pid: process.pid,
+			cwd: process.cwd(),
+			sessionFile: state.sessionFile,
+			sessionName: state.sessionName,
+			model: state.model,
+			streaming: state.streaming,
+			started: Date.now(),
+		});
+
+		let buf = "";
+		sock.on("data", (chunk) => {
+			buf += chunk.toString();
+			let idx: number;
+			while ((idx = buf.indexOf("\n")) !== -1) {
+				const line = buf.slice(0, idx).replace(/\r$/, "");
+				buf = buf.slice(idx + 1);
+				if (line.length > 0) void handleLine(sock, line, ctx);
+			}
+		});
+		const cleanup = () => {
+			clients.delete(sock);
+			try { sock.destroy(); } catch { /* ignore */ }
+		};
+		sock.on("error", cleanup);
+		sock.on("close", cleanup);
+	};
+
+	const startServer = async (ctx: any) => {
+		await mkdir(SOCK_DIR, { recursive: true });
+		// Stale socket from a previous crashed pi with same pid (very unlikely)
+		await rm(SOCK_PATH, { force: true });
+
+		server = createServer((sock) => onConnection(sock, ctx));
+		await new Promise<void>((resolve, reject) => {
+			server!.once("error", reject);
+			server!.listen(SOCK_PATH, () => {
+				server!.removeListener("error", reject);
+				resolve();
+			});
+		});
+		await writeDescriptor();
+	};
+
+	const stopServer = async () => {
+		broadcast({ type: "bye" });
+		for (const c of clients) {
+			try { c.end(); } catch { /* ignore */ }
+		}
+		clients.clear();
+		if (server) {
+			await new Promise<void>((resolve) => server!.close(() => resolve()));
+			server = null;
+		}
+		await rm(SOCK_PATH, { force: true });
+		await rm(DESC_PATH, { force: true });
+	};
+
+	const refreshState = (next: Partial<ExtState>) => {
+		Object.assign(state, next);
+		broadcast({
+			type: "state",
+			streaming: state.streaming,
+			model: state.model,
+			sessionName: state.sessionName,
+		});
+		// Best-effort descriptor refresh; non-fatal if it fails.
+		writeDescriptor().catch(() => undefined);
+	};
+
+	pi.on("session_start", async (_event, ctx) => {
+		state.sessionFile = ctx.sessionManager.getSessionFile() ?? undefined;
+		state.sessionName = pi.getSessionName?.() ?? undefined;
+		state.model = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined;
+		state.streaming = false;
+
+		try {
+			await startServer(ctx);
+			ctx.ui?.notify?.(`pi-sticky-prompt listening on ${SOCK_PATH}`, "info");
+		} catch (e: any) {
+			ctx.ui?.notify?.(`pi-sticky-prompt failed to start: ${e?.message ?? e}`, "error");
+		}
+	});
+
+	pi.on("session_shutdown", async () => {
+		await stopServer();
+	});
+
+	pi.on("agent_start", async () => {
+		refreshState({ streaming: true });
+	});
+	pi.on("agent_end", async () => {
+		refreshState({ streaming: false });
+	});
+
+	pi.on("model_select", async (event) => {
+		const m = event.model;
+		refreshState({ model: m ? `${m.provider}/${m.id}` : undefined });
+	});
+
+	// Reflect /set-session-name etc. — there is no dedicated event, so we
+	// poll on each turn end (cheap, only runs once per LLM turn).
+	pi.on("turn_end", async () => {
+		const name = pi.getSessionName?.();
+		if (name !== state.sessionName) refreshState({ sessionName: name });
+	});
+
+	pi.registerCommand("prompt-bar-status", {
+		description: "Show pi-sticky-prompt status",
+		handler: async (_args, ctx) => {
+			const lines = [
+				`socket : ${SOCK_PATH}`,
+				`desc   : ${DESC_PATH}`,
+				`clients: ${clients.size}`,
+				`stream : ${state.streaming}`,
+				`model  : ${state.model ?? "-"}`,
+			];
+			ctx.ui.notify(lines.join("\n"), "info");
+		},
+	});
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "pi-sticky-prompt",
+  "version": "0.1.1",
+  "description": "Always-on-top, full-width macOS prompt bar for pi. A floating native window that survives terminal scrollback and lets you keep typing while you read scrollback history.",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "macos",
+    "prompt-bar",
+    "hud",
+    "always-on-top",
+    "ghostty",
+    "terminal"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alonmartin2222/pi-sticky-prompt.git"
+  },
+  "homepage": "https://github.com/alonmartin2222/pi-sticky-prompt#readme",
+  "bugs": {
+    "url": "https://github.com/alonmartin2222/pi-sticky-prompt/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*"
+  },
+  "pi": {
+    "extensions": ["./extensions/sticky-prompt.ts"],
+    "video": "https://github.com/alonmartin2222/pi-sticky-prompt/releases/download/v0.1.1/demo.mp4",
+    "image": "https://raw.githubusercontent.com/alonmartin2222/pi-sticky-prompt/main/assets/sticky-bar-expanded.png"
+  },
+  "files": [
+    "extensions/",
+    "assets/",
+    "README.md",
+    "LICENSE"
+  ]
+}