@manuelfedele/postino 0.1.1 → 0.2.0

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

@@ -16,7 +16,21 @@ const server = new McpServer({
 });
 registerMessagingTools(server, config.agentName);
 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);
@@ -33,6 +47,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.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}`,
@@ -21,6 +23,8 @@ export const keys = {
 };
 export async function connect() {
     await valkey.connect();
+    // Verify the connection actually works
+    await valkey.ping();
     await valkeySub.connect();
 }
 export async function disconnect() {

package/package.json

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