@yuriteixeira/pi-muxr 0.1.0

package/dist/web/protocol.d.ts

@@ -0,0 +1,25 @@
+import type { DashboardRow } from "../domain/status.js";
+export type ClientMessage = {
+    type: "input";
+    data: string;
+} | {
+    type: "resize";
+    cols: number;
+    rows: number;
+};
+export type ServerMessage = {
+    type: "output";
+    data: string;
+} | {
+    type: "exit";
+    code?: number;
+} | {
+    type: "error";
+    message: string;
+} | {
+    type: "notification";
+    title: string;
+    body: string;
+    row: NotificationRow;
+};
+export type NotificationRow = Pick<DashboardRow, "id" | "state" | "severity" | "summary" | "cwd" | "tmuxSession" | "tmuxWindowIndex" | "paneId" | "lastEventAt">;

package/dist/web/protocol.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=protocol.js.map

package/dist/web/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/web/protocol.ts"],"names":[],"mappings":""}

package/dist/web/server.d.ts

@@ -0,0 +1,5 @@
+export interface WebServerOptions {
+    host?: string;
+    port?: number;
+}
+export declare function runWebServer(options?: WebServerOptions): void;

package/dist/web/server.js

@@ -0,0 +1,51 @@
+import http from "node:http";
+import { WEB_PAGE } from "./page.js";
+import { readVendorAsset } from "./assets.js";
+import { getBase16TerminalTheme } from "./base16-theme.js";
+export function runWebServer(options = {}) {
+    void startWebServer(options);
+}
+async function startWebServer(options) {
+    const host = options.host ?? process.env.HOST ?? "127.0.0.1";
+    const port = options.port ?? Number(process.env.PORT ?? 3042);
+    const server = http.createServer(handleRequest);
+    const { attachTerminalGateway } = await import("./terminal-gateway.js");
+    attachTerminalGateway(server);
+    server.listen(port, host, () => {
+        console.log(`pi-muxr web listening on http://${host}:${port}`);
+    });
+}
+function handleRequest(request, response) {
+    void routeRequest(request, response).catch((error) => {
+        send(response, 500, "application/json; charset=utf-8", JSON.stringify({ message: formatError(error) }));
+    });
+}
+async function routeRequest(request, response) {
+    const url = new URL(request.url ?? "/", `http://${request.headers.host ?? "localhost"}`);
+    if (request.method !== "GET") {
+        send(response, 405, "text/plain; charset=utf-8", "Method not allowed");
+        return;
+    }
+    if (url.pathname === "/api/terminal-theme") {
+        send(response, 200, "application/json; charset=utf-8", JSON.stringify({ theme: await getBase16TerminalTheme() }));
+        return;
+    }
+    const asset = readVendorAsset(url.pathname);
+    if (asset) {
+        send(response, 200, asset.contentType, asset.body);
+        return;
+    }
+    if (url.pathname === "/" || url.pathname === "/index.html") {
+        send(response, 200, "text/html; charset=utf-8", WEB_PAGE);
+        return;
+    }
+    send(response, 404, "text/plain; charset=utf-8", "Not found");
+}
+function send(response, statusCode, contentType, body) {
+    response.writeHead(statusCode, { "content-type": contentType });
+    response.end(body);
+}
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=server.js.map

package/dist/web/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/web/server.ts"],"names":[],"mappings":"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"}

package/dist/web/terminal-gateway.d.ts

@@ -0,0 +1,2 @@
+import type http from "node:http";
+export declare function attachTerminalGateway(server: http.Server): void;

package/dist/web/terminal-gateway.js

@@ -0,0 +1,110 @@
+import { URL } from "node:url";
+import { spawn } from "node-pty";
+import { WebSocketServer } from "ws";
+import { loadConfig } from "../config/config.js";
+import { openDatabase } from "../state/database.js";
+import { createNotificationMonitor } from "./notifications.js";
+import { ensurePiMuxrSession, hideTmuxStatus, isValidSessionName, restoreTmuxStatus } from "./tmux-session.js";
+export function attachTerminalGateway(server) {
+    const websocketServer = new WebSocketServer({ noServer: true });
+    server.on("upgrade", (request, socket, head) => {
+        const url = new URL(request.url ?? "/", `http://${request.headers.host ?? "localhost"}`);
+        if (url.pathname !== "/ws/terminal") {
+            socket.destroy();
+            return;
+        }
+        websocketServer.handleUpgrade(request, socket, head, (websocket) => {
+            websocketServer.emit("connection", websocket, request, url);
+        });
+    });
+    websocketServer.on("connection", (websocket, _request, url) => {
+        void attachTerminal(websocket, url);
+    });
+}
+async function attachTerminal(websocket, url) {
+    const session = url.searchParams.get("session")?.trim() || "pi-muxr-web";
+    if (!isValidSessionName(session)) {
+        sendJson(websocket, { type: "error", message: "Invalid tmux session name." });
+        websocket.close();
+        return;
+    }
+    try {
+        await ensurePiMuxrSession(session);
+        await hideTmuxStatus(session);
+    }
+    catch (error) {
+        sendJson(websocket, { type: "error", message: formatError(error) });
+        websocket.close();
+        return;
+    }
+    const terminal = spawn("tmux", ["attach-session", "-t", session], {
+        name: "xterm-256color",
+        cols: 80,
+        rows: 24,
+        cwd: process.env.HOME,
+        env: process.env,
+    });
+    const config = loadConfig();
+    const db = openDatabase(config.databasePath);
+    const notifications = createNotificationMonitor(db, config);
+    const notificationTimer = setInterval(() => sendMessages(websocket, notifications.poll()), 1_000);
+    let closed = false;
+    const close = () => {
+        if (closed)
+            return;
+        closed = true;
+        clearInterval(notificationTimer);
+        terminal.kill();
+        restoreTmuxStatus(session);
+        db.close();
+    };
+    const release = () => {
+        if (closed)
+            return;
+        closed = true;
+        clearInterval(notificationTimer);
+        restoreTmuxStatus(session);
+        db.close();
+    };
+    terminal.onData((data) => sendJson(websocket, { type: "output", data }));
+    terminal.onExit(({ exitCode }) => {
+        sendJson(websocket, { type: "exit", code: exitCode });
+        websocket.close();
+        release();
+    });
+    websocket.on("message", (message) => handleClientMessage(terminal, websocket, message.toString()));
+    websocket.on("close", close);
+    websocket.on("error", close);
+}
+function handleClientMessage(terminal, websocket, data) {
+    try {
+        const message = JSON.parse(data);
+        if (message.type === "input" && typeof message.data === "string") {
+            terminal.write(message.data);
+            return;
+        }
+        if (message.type === "resize" && isValidSize(message.cols, message.rows)) {
+            terminal.resize(message.cols, message.rows);
+            return;
+        }
+        sendJson(websocket, { type: "error", message: "Unsupported terminal message." });
+    }
+    catch {
+        sendJson(websocket, { type: "error", message: "Invalid terminal message." });
+    }
+}
+function isValidSize(cols, rows) {
+    return Number.isInteger(cols) && Number.isInteger(rows) && cols > 0 && rows > 0;
+}
+function sendMessages(websocket, messages) {
+    for (const message of messages)
+        sendJson(websocket, message);
+}
+function sendJson(websocket, message) {
+    if (websocket.readyState === websocket.OPEN)
+        websocket.send(JSON.stringify(message));
+}
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=terminal-gateway.js.map

package/dist/web/terminal-gateway.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-gateway.js","sourceRoot":"","sources":["../../src/web/terminal-gateway.ts"],"names":[],"mappings":"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"}

package/dist/web/tmux-session.d.ts

@@ -0,0 +1,4 @@
+export declare function isValidSessionName(name: string): boolean;
+export declare function ensurePiMuxrSession(session: string): Promise<void>;
+export declare function hideTmuxStatus(session: string): Promise<void>;
+export declare function restoreTmuxStatus(session: string): void;

package/dist/web/tmux-session.js

@@ -0,0 +1,50 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const SESSION_NAME_PATTERN = /^[A-Za-z0-9_.:-]+$/;
+const hiddenStatusSessions = new Map();
+export function isValidSessionName(name) {
+    return SESSION_NAME_PATTERN.test(name);
+}
+export async function ensurePiMuxrSession(session) {
+    if (!isValidSessionName(session))
+        throw new Error("Invalid tmux session name.");
+    if (await hasSession(session))
+        return;
+    await execFileAsync("tmux", ["new-session", "-d", "-s", session, piMuxrCommand()]);
+}
+export async function hideTmuxStatus(session) {
+    const existing = hiddenStatusSessions.get(session);
+    if (existing) {
+        existing.clients += 1;
+        return;
+    }
+    const { stdout } = await execFileAsync("tmux", ["show-options", "-t", session, "-v", "status"]);
+    const previousStatus = stdout.trim() || "on";
+    await execFileAsync("tmux", ["set-option", "-t", session, "status", "off"]);
+    hiddenStatusSessions.set(session, { clients: 1, previousStatus });
+}
+export function restoreTmuxStatus(session) {
+    const existing = hiddenStatusSessions.get(session);
+    if (!existing)
+        return;
+    existing.clients -= 1;
+    if (existing.clients > 0)
+        return;
+    hiddenStatusSessions.delete(session);
+    execFile("tmux", ["set-option", "-t", session, "status", existing.previousStatus], () => { });
+}
+async function hasSession(session) {
+    try {
+        await execFileAsync("tmux", ["has-session", "-t", session]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function piMuxrCommand() {
+    const entrypoint = JSON.stringify(process.argv[1] ?? "pi-muxr");
+    return `${JSON.stringify(process.execPath)} ${entrypoint}`;
+}
+//# sourceMappingURL=tmux-session.js.map

package/dist/web/tmux-session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tmux-session.js","sourceRoot":"","sources":["../../src/web/tmux-session.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAC1C,MAAM,oBAAoB,GAAG,oBAAoB,CAAC;AAClD,MAAM,oBAAoB,GAAG,IAAI,GAAG,EAAuD,CAAC;AAE5F,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,OAAO,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACzC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,OAAe;IACvD,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;IAChF,IAAI,MAAM,UAAU,CAAC,OAAO,CAAC;QAAE,OAAO;IACtC,MAAM,aAAa,CAAC,MAAM,EAAE,CAAC,aAAa,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC;AACrF,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAAe;IAClD,MAAM,QAAQ,GAAG,oBAAoB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACnD,IAAI,QAAQ,EAAE,CAAC;QACb,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAC;QACtB,OAAO;IACT,CAAC;IAED,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,aAAa,CAAC,MAAM,EAAE,CAAC,cAAc,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;IAChG,MAAM,cAAc,GAAG,MAAM,CAAC,IAAI,EAAE,IAAI,IAAI,CAAC;IAC7C,MAAM,aAAa,CAAC,MAAM,EAAE,CAAC,YAAY,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC;IAC5E,oBAAoB,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC;AACpE,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,MAAM,QAAQ,GAAG,oBAAoB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACnD,IAAI,CAAC,QAAQ;QAAE,OAAO;IAEtB,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAC;IACtB,IAAI,QAAQ,CAAC,OAAO,GAAG,CAAC;QAAE,OAAO;IAEjC,oBAAoB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,CAAC,YAAY,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC,cAAc,CAAC,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;AAC/F,CAAC;AAED,KAAK,UAAU,UAAU,CAAC,OAAe;IACvC,IAAI,CAAC;QACH,MAAM,aAAa,CAAC,MAAM,EAAE,CAAC,aAAa,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;QAC5D,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,SAAS,aAAa;IACpB,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,SAAS,CAAC,CAAC;IAChE,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,UAAU,EAAE,CAAC;AAC7D,CAAC"}

package/docs/ARCHITECTURE.md

@@ -0,0 +1,287 @@
+# `pi-muxr` architecture
+
+## Purpose
+
+`pi-muxr` gives one view of Pi sessions that run in tmux. It answers three questions:
+
+1. Which sessions are active?
+2. Which sessions need attention?
+3. Which tmux pane owns each session?
+
+The project does not read terminal output. A Pi extension receives Pi events and publishes structured state. The terminal and browser interfaces read that shared state.
+
+## System overview
+
+```text
+Pi session
+    |
+    | Pi extension events
+    v
+SQLite database: ~/.pi-muxr/pi-muxr.sqlite
+    |
+    +--> CLI dashboard
+    |       |
+    |       +--> terminal input and display
+    |       +--> tmux pane focus
+    |       +--> terminal bell
+    |
+    +--> Web terminal gateway
+    |       |
+    |       +--> browser xterm terminal
+    |       +--> tmux session through node-pty
+    |       +--> browser notifications
+    |
+    +--> Desktop notifications
+```
+
+SQLite is the shared boundary between the Pi extension and the user interfaces. It allows the extension and one or more dashboard processes to read and update state without a separate service.
+
+## Source layout
+
+```text
+src/
+├── domain/          State types and rules that do not depend on I/O
+├── extension/       Pi event integration and session state publishing
+├── state/           SQLite schema and state reads and writes
+├── tmux/            Pane discovery and pane focus
+├── cli/             Terminal entry point and dashboard rendering
+├── web/             HTTP server, browser assets, and terminal gateway
+├── config/          Configuration and path resolution
+└── notifications/   Desktop notification integration
+```
+
+The domain layer is kept independent from the terminal, web, tmux, and database layers. This makes state rules easier to test and keeps the user interfaces as clients of the same data model.
+
+## State model
+
+Each Pi process owns one row in the `sessions` table.
+
+Important fields include:
+
+- `id`: Stable identifier for the Pi session and tmux pane.
+- `pane_id`: tmux pane identifier such as `%12`.
+- `tmux_session`, `tmux_window`, and `tmux_window_index`: Pane location.
+- `pid`: Pi process ID.
+- `cwd`: Project directory.
+- `pi_session_file`: Pi session file when available.
+- `model`: Selected model.
+- `state`: Current Pi state.
+- `severity`: `low`, `medium`, or `high`.
+- `summary`: Short description of the latest event.
+- `last_event_at`: Time of the latest meaningful event.
+- `heartbeat_at`: Time of the latest process heartbeat.
+- Read, dismissal, and notification markers.
+
+The database also contains `dashboard_presence`. Dashboard processes update this table so the extension can avoid sending desktop notifications when a dashboard is already open.
+
+## Session states
+
+The domain supports these states:
+
+| State | Meaning |
+| --- | --- |
+| `ASK` | Pi is waiting for user input through `ask_user`. |
+| `ERROR` | A turn or tool ended with an error. |
+| `DONE` | A turn completed. |
+| `QUEUED` | Work is waiting to start. |
+| `RUN` | Pi is processing a turn or tool. |
+| `IDLE` | The session is alive but not active. |
+| `STALE` | Internal display classification for an expired heartbeat or a missing tmux pane. |
+
+By default, `ASK`, `ERROR`, and `DONE` are actionable. The configuration can change the actionable states used by the dashboard, dashboard bell, dismissal actions, and browser notifications. Desktop notifications always use the default actionable states.
+
+An event is unread when its `last_event_at` is newer than `read_until_event_at` and it has not been dismissed. Unread and actionable are separate properties. The dashboard can therefore show an unread marker for a state that is not actionable. An event is dismissed when `dismissed_until_event_at` is at least as recent as `last_event_at`. This means a new event becomes visible again after an older event was read or dismissed.
+
+## Pi extension flow
+
+The extension is loaded by Pi and listens to Pi lifecycle events.
+
+```text
+session_start
+    -> open database
+    -> create session ID
+    -> publish IDLE state
+    -> start heartbeat timer
+
+agent_start / turn_start
+    -> publish RUN state
+
+tool_call
+    -> publish ASK for ask_user
+    -> publish RUN for other tools
+
+tool_result
+    -> retain error information
+    -> publish tool summary when needed
+
+agent_end
+    -> publish ERROR when the turn failed
+    -> otherwise publish DONE
+
+session_shutdown
+    -> stop heartbeat
+    -> remove session row
+    -> close database
+```
+
+The extension also refreshes tmux information when it writes a state update. It uses `TMUX_PANE` and tmux pane discovery to associate a Pi process with its owning pane.
+
+Summaries are truncated before storage. This keeps the database small and limits the amount of event data retained for display.
+
+## Heartbeats and stale sessions
+
+The extension updates `heartbeat_at` on a timer. The dashboard does not trust clean shutdown alone because a process can be killed or a pane can disappear.
+
+When dashboard rows are built:
+
+- A session is stale when its heartbeat is older than `staleAfterMs`.
+- A session is also stale when its recorded pane is missing.
+- Stale rows are classified as `STALE`, marked as not actionable, and removed from the displayed rows.
+
+This check is performed when rows are read. The database does not need a cleanup process for abandoned rows, but abandoned rows remain stored and are hidden from the interfaces.
+
+## CLI dashboard flow
+
+The CLI has four modes:
+
+- Interactive dashboard: `pi-muxr`
+- Tmux sidebar toggle: `pi-muxr --sidebar [left|right]`
+- Plain output: `pi-muxr --list`
+- Browser server: `pi-muxr --web`
+
+The interactive dashboard follows this flow:
+
+```text
+load configuration
+    -> open SQLite database
+    -> record dashboard presence
+    -> read session rows
+    -> list tmux panes
+    -> join sessions with panes
+    -> mark and remove stale rows
+    -> sort active rows
+    -> render dashboard
+```
+
+The dashboard refreshes once per second. It keeps the selected row, tracks events already seen during the current run, and emits a terminal bell for new unread actionable events.
+
+User actions update SQLite before they affect the display:
+
+- `Enter` marks the event as read and focuses its pane.
+- `d` dismisses the selected event.
+- `D` dismisses all read actionable events.
+- `r` refreshes the rows.
+- `q`, `Esc`, or `Ctrl+C` cleans up presence and exits.
+
+The rendering layer uses `@earendil-works/pi-tui`. Dashboard orchestration, state updates, tmux commands, and rendering are separate responsibilities.
+
+## Tmux integration
+
+The extension uses `tmux list-panes` to discover pane metadata. The dashboard joins this data with the session rows by pane ID.
+
+When the user focuses a row, `src/tmux/focus.ts` selects the pane and switches to its tmux session and window. When the CLI runs outside tmux, it reports the commands needed to focus the pane instead of pretending that the focus succeeded.
+
+The sidebar command splits every window in every tmux session and starts the same `pi-muxr` entrypoint in each new pane. The default side is right, and each pane uses at most 25 percent of the window width. A tmux pane option marks each pane. A global tmux option stores the selected side. Indexed `after-new-session` and `after-new-window` hooks add the sidebar to new sessions and windows without replacing other hooks. The next sidebar command finds the markers, closes all dashboard sidebar panes, and removes the option and hooks.
+
+The browser gateway uses a separate tmux session, named `pi-muxr-web` by default. A query parameter can select another valid session name.
+
+## Browser interface
+
+The web interface is a local HTTP server with a WebSocket terminal gateway.
+
+```text
+Browser
+  | HTTP
+  v
+Web server
+  | serves page, assets, and terminal theme
+  |
+  | WebSocket
+  v
+Terminal gateway
+  | node-pty
+  v
+ tmux attach-session
+```
+
+When a browser connects, the gateway:
+
+1. Validates the requested tmux session name.
+2. Creates the session when it does not exist.
+3. Temporarily hides the tmux status line.
+4. Starts `tmux attach-session` through `node-pty`.
+5. Forwards terminal output to the browser.
+6. Forwards keyboard input and valid resize messages to the terminal.
+7. Polls SQLite for unread actionable events and sends browser notification messages.
+8. Restores tmux status and closes resources when the connection ends.
+
+The web interface is a terminal view, not a second dashboard implementation. It attaches to the tmux session that runs the normal CLI dashboard.
+
+## Notifications
+
+The dashboard bell and browser notifications use the configured actionable states. Desktop notifications use the fixed default states: `ASK`, `ERROR`, and `DONE`.
+
+Desktop notification flow:
+
+```text
+extension state update
+    -> check default desktop notification state
+    -> check previous notification marker
+    -> check dashboard presence
+    -> send desktop notification
+    -> store last_notified_event_at
+```
+
+The extension avoids repeated desktop notifications for the same state. When configured, a fresh dashboard presence suppresses desktop notifications because the user can already see the event.
+
+The interactive CLI uses a separate in process event set for its terminal bell. The browser gateway polls notification state and sends browser messages for new unread actionable rows. Both paths use the configured actionable states.
+
+## Configuration boundary
+
+Configuration is loaded from `~/.pi-muxr/config.json`. If the file does not exist, built in defaults are used.
+
+Configuration controls:
+
+- Database and state paths.
+- Actionable states for the dashboard, dashboard bell, dismissal actions, and browser notifications.
+- Desktop notification behavior for the fixed `ASK`, `ERROR`, and `DONE` states.
+- Dashboard bell behavior.
+- Whether dismissed rows are shown.
+- Stale and heartbeat timing.
+- Dashboard presence timing.
+
+The CLI, extension, and web gateway all load the same configuration. They share state and timing rules, while desktop notifications retain their fixed default state list.
+
+## Design decisions
+
+### Structured events instead of screen scraping
+
+Pi events provide clear meaning and stable summaries. Screen scraping would depend on terminal formatting and would not reliably identify questions, errors, or completed turns.
+
+### SQLite instead of per process files
+
+SQLite supports concurrent reads and writes, preserves read and dismissal markers, and keeps the state model in one place.
+
+### tmux as the focus layer
+
+Pi sessions already run in tmux. Storing the pane ID allows the dashboard to move from an event directly to the owning session without controlling Pi itself.
+
+### Shared domain rules
+
+Actionable, unread, dismissed, and stale behavior is defined in the domain and used by every interface. This prevents the terminal and browser paths from making different decisions about the same event.
+
+### Best effort cleanup with display time checks
+
+Clean shutdown removes rows, but stale detection remains necessary for crashes, closed panes, and killed processes.
+
+## Extension points
+
+The design leaves room for future changes without changing the main data flow:
+
+- Add new Pi event mappings in the extension.
+- Add new states to the domain model and configuration.
+- Add another client that reads the SQLite state.
+- Add notification providers beside desktop and browser notifications.
+- Add more tmux actions without changing session publishing.
+
+A new interface should read the domain state and reuse the existing row rules. It should not create a second session protocol.

package/docs/BUILDING.md

@@ -0,0 +1,78 @@
+# Building `pi-muxr`
+
+This guide explains how to build and run a local copy of `pi-muxr`.
+
+## Requirements
+
+- Node.js 24 or later
+- pnpm
+- tmux for running the dashboard
+- Pi for testing the extension
+
+The CLI uses the built in `node:sqlite` module.
+
+## Install and build
+
+```bash
+pnpm install
+pnpm build
+```
+
+The build output is written to `dist`.
+
+For an automatic rebuild during development, run:
+
+```bash
+pnpm start
+```
+
+## Check the code
+
+```bash
+pnpm typecheck
+pnpm test
+```
+
+## Link the CLI
+
+To run the local CLI from any directory:
+
+```bash
+pnpm link --global
+```
+
+The command points to `dist/cli/index.js`. Rebuild after source changes, or keep `pnpm start` running.
+
+## Load the Pi extension
+
+Build the package, then link the complete extension directory:
+
+```bash
+pnpm build
+mkdir -p ~/.pi/agent/extensions
+rm -f ~/.pi/agent/extensions/pi-muxr.js ~/.pi/agent/extensions/pi-muxr
+ln -sfn "$PWD/dist/extension" ~/.pi/agent/extensions/pi-muxr
+```
+
+The directory link is required because the built extension imports sibling modules from `dist`.
+
+If Pi is already running, use `/reload` after creating or changing the link.
+
+The extension stores state in:
+
+```text
+~/.pi-muxr/pi-muxr.sqlite
+```
+
+It removes its row during a clean shutdown. Wrappers around Pi are supported when they load the extension.
+
+## Run the CLI
+
+```bash
+pi-muxr --help
+pi-muxr --list
+pi-muxr
+pi-muxr --web
+```
+
+See the main [README](../README.md) for user configuration, key bindings, and usage details.