@manuelfedele/postino 0.1.1 → 0.2.1

package/.claude-plugin/marketplace.json

@@ -0,0 +1,19 @@
+{
+  "name": "postino",
+  "owner": {
+    "name": "Manuel Fedele",
+    "url": "https://github.com/manuelfedele"
+  },
+  "plugins": [
+    {
+      "name": "postino",
+      "description": "Inter-agent messaging, broadcasts, and real-time web GUI for Claude Code. Let your agents talk to each other across tabs and processes.",
+      "category": "productivity",
+      "source": {
+        "source": "url",
+        "url": "https://github.com/manuelfedele/postino.git"
+      },
+      "homepage": "https://github.com/manuelfedele/postino"
+    }
+  ]
+}

package/README.md

@@ -35,11 +35,22 @@
 
 ## Quick Start
 
+### As a Claude Code plugin (recommended)
+
+```bash
+claude plugin marketplace add manuelfedele/postino
+claude plugin install postino
+```
+
+Or from within Claude Code: `/plugin marketplace add manuelfedele/postino` then `/plugin install postino`.
+
+### Via npx
+
 ```bash
 npx @manuelfedele/postino install
 ```
 
-That's it. Restart Claude Code. Your agent is online.
+Restart Claude Code after either method. Your agent is online.
 
 > **Prerequisite:** Valkey or Redis running on `localhost:6379`
 
@@ -122,28 +133,81 @@ Updates in real-time via Server-Sent Events. When an agent sends a message from
 
 ## How It Works
 
+### 1-to-1 Messaging
+
+Messages work like a queue: send pushes, read pops.
+
+```mermaid
+sequenceDiagram
+    participant A as Tab 1 (agent-A)
+    participant V as Valkey
+    participant B as Tab 2 (agent-B)
+
+    A->>V: msg_send(to=B, "run tests")
+    V-->>B: pub/sub notify
+    Note over B: hook fires on next prompt
+    B->>V: msg_check()
+    V-->>B: "1 unread message"
+    B->>V: msg_read()
+    V-->>B: [{from: A, body: "run tests"}]
+    Note over V: message consumed
 ```
-Tab 1 (agent-A)                    Valkey                     Tab 2 (agent-B)
-     |                               |                              |
-     |-- msg_send(to=B, "do X") ---->|                              |
-     |                               |-- pub/sub notify ----------->|
-     |                               |                              |-- msg_check()
-     |                               |                              |   "1 unread message"
-     |                               |                              |-- msg_read()
-     |                               |<-- consume --------------------|   [{from: A, body: "do X"}]
-     |                               |                              |
-     |-- msg_broadcast("deploy") --->|-- shared list -------------->|
-     |                               |                              |-- msg_broadcasts()
-     |                               |                              |   [{from: A, body: "deploy"}]
+
+### Broadcasts
+
+Broadcasts are shared. Every agent reads independently via a per-agent cursor.
+
+```mermaid
+sequenceDiagram
+    participant A as Tab 1 (agent-A)
+    participant V as Valkey
+    participant B as Tab 2 (agent-B)
+    participant C as Tab 3 (agent-C)
+
+    A->>V: msg_broadcast("deploy freeze")
+    V-->>B: SSE event
+    V-->>C: SSE event
+    B->>V: msg_broadcasts()
+    V-->>B: [{from: A, body: "deploy freeze"}]
+    Note over V: cursor advanced for B
+    C->>V: msg_broadcasts()
+    V-->>C: [{from: A, body: "deploy freeze"}]
+    Note over V: cursor advanced for C
+    Note over V: message still exists (TTL expiry)
 ```
 
-**Messages** are Valkey lists (one per agent inbox). `msg_send` pushes, `msg_read` pops. Messages have a 24h TTL as a safety net for unread messages.
+### Architecture
+
+```mermaid
+graph LR
+    subgraph Claude Code
+        T1[Tab 1<br/>MCP client] -->|stdio| M1[Postino<br/>MCP server]
+        T2[Tab 2<br/>MCP client] -->|stdio| M2[Postino<br/>MCP server]
+    end
+
+    M1 -->|ioredis| VK[(Valkey)]
+    M2 -->|ioredis| VK
+
+    M1 -->|Hono :3333| GUI[Web GUI]
+    VK -->|pub/sub| GUI
+    GUI -->|SSE| Browser
+
+    H[Hook<br/>check-messages.sh] -->|curl /api/check| M1
+
+    style VK fill:#e63030,color:#fff,stroke:none
+    style GUI fill:#2563eb,color:#fff,stroke:none
+    style H fill:#d97706,color:#fff,stroke:none
+```
+
+### Under the Hood
+
+**Messages** are Valkey lists (one per inbox). `msg_send` pushes, `msg_read` pops. Unread messages expire after 24h (configurable).
 
-**Broadcasts** are a shared Valkey list. Each agent tracks a cursor (last-seen index). Reading broadcasts advances the cursor without deleting the data, so every agent sees every broadcast.
+**Broadcasts** are a shared Valkey list. Each agent tracks a cursor (last-seen index). Reading advances the cursor without deleting, so every agent sees every broadcast.
 
 **Agent presence** uses Valkey keys with a 30-second TTL, refreshed by a heartbeat. If a process dies, it goes offline within 30 seconds.
 
-**The hook** (`UserPromptSubmit`) calls `GET /api/check/:agent` via curl. If there are no new messages or broadcasts, it outputs nothing (zero tokens). If there's something new, it injects a one-line hint so Claude knows to check.
+**The hook** (`UserPromptSubmit`) calls `GET /api/check/:agent` via curl. Zero output when there's nothing new (zero token cost). One-line hint when messages arrive.
 
 ---
 

package/dist/index.js

@@ -2,9 +2,9 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { loadConfig } from "./types.js";
-import { connect, disconnect, registerAgent, deregisterAgent } from "./valkey.js";
+import { connect, disconnect, valkey, valkeySub, keys, registerAgent, deregisterAgent } from "./valkey.js";
 import { registerMessagingTools } from "./tools/messaging.js";
-import { startWebServer } from "./web/server.js";
+import { startWebServer, getGuiState, restartOnPort } from "./web/server.js";
 const config = loadConfig();
 const server = new McpServer({
     name: "postino",
@@ -15,16 +15,70 @@ const server = new McpServer({
     },
 });
 registerMessagingTools(server, config.agentName);
+function subscribeGuiTakeover() {
+    const channel = keys.guiTakeoverChannel();
+    valkeySub.subscribe(channel).catch(() => {
+        process.stderr.write("postino: failed to subscribe to GUI takeover channel\n");
+    });
+    valkeySub.on("message", (ch, message) => {
+        if (ch !== channel)
+            return;
+        let data;
+        try {
+            data = JSON.parse(message);
+        }
+        catch {
+            return;
+        }
+        const state = getGuiState();
+        // Skip if we already have a GUI on an equal or lower port
+        if (state.running && state.port !== null && state.port <= data.port)
+            return;
+        // Random jitter (100-500ms) so not all instances race at once
+        const jitter = 100 + Math.random() * 400;
+        setTimeout(async () => {
+            const ok = await restartOnPort(data.port);
+            if (ok) {
+                process.stderr.write(`postino: took over GUI on port ${data.port}\n`);
+            }
+        }, jitter);
+    });
+}
 async function main() {
-    await connect();
+    try {
+        await connect();
+    }
+    catch (err) {
+        const url = config.valkeyUrl;
+        process.stderr.write(`\n  postino: cannot connect to Valkey/Redis at ${url}\n\n`);
+        process.stderr.write(`  Postino requires Valkey or Redis. Start one with:\n\n`);
+        process.stderr.write(`    docker run -d --name valkey -p 6379:6379 valkey/valkey:8\n\n`);
+        process.stderr.write(`  Or install natively:\n\n`);
+        process.stderr.write(`    macOS:  brew install valkey && brew services start valkey\n`);
+        process.stderr.write(`    Linux:  apt install valkey-server\n\n`);
+        process.stderr.write(`  To use a different host/port:\n\n`);
+        process.stderr.write(`    POSTINO_VALKEY_URL=redis://host:port\n\n`);
+        process.exit(1);
+    }
     await registerAgent(config.agentName);
     const transport = new StdioServerTransport();
     await server.connect(transport);
     if (config.webEnabled) {
         startWebServer(config.webPort);
+        subscribeGuiTakeover();
     }
     process.stderr.write(`postino agent: ${config.agentName}\n`);
     const shutdown = async () => {
+        // If this instance had a GUI, notify others so they can take over the port
+        const state = getGuiState();
+        if (state.running && state.port !== null) {
+            try {
+                await valkey.publish(keys.guiTakeoverChannel(), JSON.stringify({ port: state.port }));
+            }
+            catch {
+                // Best-effort, connection may already be closing
+            }
+        }
         await deregisterAgent(config.agentName);
         await disconnect();
         process.exit(0);
@@ -33,6 +87,6 @@ async function main() {
     process.on("SIGTERM", shutdown);
 }
 main().catch((err) => {
-    console.error("Failed to start postino:", err);
+    process.stderr.write(`postino: ${err.message || err}\n`);
     process.exit(1);
 });

package/dist/valkey.d.ts

@@ -9,6 +9,7 @@ export declare const keys: {
     broadcastCursor: (agent: string) => string;
     notifyChannel: (agent: string) => string;
     eventsChannel: () => string;
+    guiTakeoverChannel: () => string;
 };
 export declare function connect(): Promise<void>;
 export declare function disconnect(): Promise<void>;

package/dist/valkey.js

@@ -5,10 +5,12 @@ export const valkey = new Redis(config.valkeyUrl, {
     lazyConnect: true,
     maxRetriesPerRequest: 3,
 });
+valkey.on("error", () => { }); // Handled in connect()
 export const valkeySub = new Redis(config.valkeyUrl, {
     lazyConnect: true,
     maxRetriesPerRequest: 3,
 });
+valkeySub.on("error", () => { }); // Handled in connect()
 const prefix = config.keyPrefix;
 export const keys = {
     inbox: (agent) => `${prefix}inbox:${agent}`,
@@ -18,9 +20,12 @@ export const keys = {
     broadcastCursor: (agent) => `${prefix}bcursor:${agent}`,
     notifyChannel: (agent) => `${prefix}notify:${agent}`,
     eventsChannel: () => `${prefix}events`,
+    guiTakeoverChannel: () => `${prefix}gui:takeover`,
 };
 export async function connect() {
     await valkey.connect();
+    // Verify the connection actually works
+    await valkey.ping();
     await valkeySub.connect();
 }
 export async function disconnect() {

package/dist/web/api.js

@@ -101,7 +101,9 @@ function ensureEventSubscription() {
     valkeySub.subscribe(keys.eventsChannel()).catch(() => {
         subscribedToEvents = false;
     });
-    valkeySub.on("message", (_channel, message) => {
+    valkeySub.on("message", (channel, message) => {
+        if (channel !== keys.eventsChannel())
+            return;
         for (const client of sseClients) {
             try {
                 client.send(message);

package/dist/web/server.d.ts

@@ -1 +1,7 @@
+export interface GuiState {
+    running: boolean;
+    port: number | null;
+}
+export declare function getGuiState(): GuiState;
 export declare function startWebServer(port: number, attempt?: number): void;
+export declare function restartOnPort(port: number): Promise<boolean>;

package/dist/web/server.js

@@ -49,9 +49,16 @@ app.get("/", (c) => {
     return c.html(html);
 });
 const MAX_PORT_ATTEMPTS = 10;
+let currentServer = null;
+let currentPort = null;
+export function getGuiState() {
+    return { running: currentServer !== null, port: currentPort };
+}
 export function startWebServer(port, attempt = 0) {
     try {
         const server = serve({ fetch: app.fetch, port }, () => {
+            currentServer = server;
+            currentPort = port;
             process.stderr.write(`postino GUI: http://localhost:${port}\n`);
         });
         server.on("error", (err) => {
@@ -69,3 +76,45 @@ export function startWebServer(port, attempt = 0) {
         process.stderr.write(`postino GUI failed to start: ${err}\n`);
     }
 }
+export function restartOnPort(port) {
+    return new Promise((resolve) => {
+        const oldServer = currentServer;
+        const oldPort = currentPort;
+        const launchNew = () => {
+            try {
+                const server = serve({ fetch: app.fetch, port }, () => {
+                    currentServer = server;
+                    currentPort = port;
+                    process.stderr.write(`postino GUI: takeover http://localhost:${port}\n`);
+                    resolve(true);
+                });
+                server.on("error", (err) => {
+                    if (err.code === "EADDRINUSE") {
+                        process.stderr.write(`postino: takeover port ${port} already claimed\n`);
+                    }
+                    else {
+                        process.stderr.write(`postino: takeover failed: ${err.message}\n`);
+                    }
+                    // Restore old state if we had one
+                    currentServer = oldServer;
+                    currentPort = oldPort;
+                    resolve(false);
+                });
+            }
+            catch {
+                currentServer = oldServer;
+                currentPort = oldPort;
+                resolve(false);
+            }
+        };
+        if (oldServer) {
+            // Close existing server first, then start on the new port
+            currentServer = null;
+            currentPort = null;
+            oldServer.close(() => launchNew());
+        }
+        else {
+            launchNew();
+        }
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manuelfedele/postino",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Inter-agent messaging and broadcast system for Claude Code",
   "type": "module",
   "main": "dist/index.js",