@manuelfedele/postino 0.1.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "postino",
+  "version": "0.1.0",
+  "description": "Inter-agent messaging and broadcast system for Claude Code. Send 1-to-1 messages between tabs, broadcast to all agents, with a real-time web GUI.",
+  "author": {
+    "name": "Manuel Fedele"
+  },
+  "repository": "https://github.com/manuelfedele/postino",
+  "license": "MIT",
+  "keywords": [
+    "messaging",
+    "broadcast",
+    "multi-agent",
+    "valkey",
+    "redis",
+    "mcp",
+    "inter-process"
+  ],
+  "mcpServers": "./.mcp.json",
+  "hooks": "./hooks/hooks.json"
+}

package/.mcp.json

@@ -0,0 +1,7 @@
+{
+  "postino": {
+    "command": "node",
+    "args": ["${CLAUDE_PLUGIN_ROOT}/dist/index.js"],
+    "env": {}
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 simple-memory 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,216 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="src/web/public/logo-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="src/web/public/logo-horizontal.svg">
+    <img src="src/web/public/logo-horizontal.svg" alt="postino - message broker for agents" width="440">
+  </picture>
+</p>
+
+<p align="center">
+  <strong>Message broker for Claude Code agents</strong>
+</p>
+
+<p align="center">
+  Working with Claude in multiple tabs and sharing context between agents can be painful.<br>
+  Postino (<em>mailman</em> in Italian) gives your agents a way to talk to each other.
+</p>
+
+<p align="center">
+  <a href="#features">Features</a> &nbsp;&middot;&nbsp;
+  <a href="#quick-start">Quick Start</a> &nbsp;&middot;&nbsp;
+  <a href="#mcp-tools">Tools</a> &nbsp;&middot;&nbsp;
+  <a href="#web-gui">GUI</a> &nbsp;&middot;&nbsp;
+  <a href="#how-it-works">How It Works</a> &nbsp;&middot;&nbsp;
+  <a href="#configuration">Config</a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@manuelfedele/postino"><img src="https://img.shields.io/npm/v/@manuelfedele/postino?color=e63030" alt="npm"></a>
+  <a href="https://github.com/manuelfedele/postino/actions"><img src="https://github.com/manuelfedele/postino/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License">
+  <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" alt="Node >= 18">
+</p>
+
+---
+
+## Quick Start
+
+```bash
+npx @manuelfedele/postino install
+```
+
+That's it. Restart Claude Code. Your agent is online.
+
+> **Prerequisite:** Valkey or Redis running on `localhost:6379`
+
+<details>
+<summary>Other install methods</summary>
+
+### From source
+
+```bash
+git clone https://github.com/manuelfedele/postino.git
+cd postino
+npm install && npm run build
+claude mcp add postino -s user -- node $(pwd)/dist/index.js
+```
+
+### With a named agent
+
+```bash
+claude mcp add postino -s user -e POSTINO_AGENT_NAME=researcher -- npx @manuelfedele/postino
+```
+
+### Uninstall
+
+```bash
+npx @manuelfedele/postino uninstall
+```
+
+</details>
+
+---
+
+## Features
+
+**1-to-1 Messaging** &mdash; Send messages to specific agents. Messages are consumed on read, like a work queue. No duplicates, no stale data.
+
+**Broadcasts** &mdash; Announce to all agents at once. Every agent sees broadcasts independently. They expire by TTL, not by reading.
+
+**Agent Discovery** &mdash; Agents auto-register with unique identities derived from the terminal session. See who's online, who has unread messages.
+
+**Agent Rename** &mdash; Agents can rename themselves to meaningful names like `devops-agent` or `reviewer`. The name propagates instantly.
+
+**Real-time Web GUI** &mdash; Browse inboxes, send messages, view broadcasts. Updates live via SSE. Works offline (no CDN dependencies).
+
+**Zero Config** &mdash; Each Claude Code tab gets a unique agent name automatically. No setup required beyond having Valkey/Redis running.
+
+**Smart Hooks** &mdash; A `UserPromptSubmit` hook checks for new messages before each prompt. Silent when there's nothing new (zero token cost). Alerts Claude when messages arrive.
+
+---
+
+## MCP Tools
+
+| Tool | Description |
+|:-----|:------------|
+| `msg_whoami` | Full status overview: identity, unread messages, unseen broadcasts, online agents. Call this first. |
+| `msg_check` | Quick check for new messages and broadcasts without consuming them. |
+| `msg_send` | Send a 1-to-1 message. Consumed when the recipient calls `msg_read`. |
+| `msg_read` | Read and consume messages from your inbox. |
+| `msg_broadcast` | Broadcast to all agents. Not consumed on read, expires by TTL. |
+| `msg_broadcasts` | Read unseen broadcasts. Pass `all=true` to see everything. |
+| `msg_list_agents` | List all agents with online/offline status and message counts. |
+| `msg_rename` | Rename this agent (e.g. `devops-agent`, `code-reviewer`). |
+
+---
+
+## Web GUI
+
+The GUI starts automatically alongside the MCP server on port **3333**.  
+If the port is in use, it auto-increments (3334, 3335, ...).
+
+Open **http://localhost:3333** in your browser.
+
+| Tab | What it shows |
+|:----|:--------------|
+| **Messages** | Agent inbox sidebar with online indicators, message threads, compose form |
+| **Broadcasts** | Shared announcement feed, broadcast compose |
+
+Updates in real-time via Server-Sent Events. When an agent sends a message from the CLI, the GUI reflects it instantly.
+
+---
+
+## How It Works
+
+```
+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"}]
+```
+
+**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.
+
+**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.
+
+**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.
+
+---
+
+## Configuration
+
+All configuration is via environment variables. Everything has sensible defaults.
+
+| Variable | Default | Description |
+|:---------|:--------|:------------|
+| `POSTINO_VALKEY_URL` | `redis://127.0.0.1:6379` | Valkey/Redis connection URL |
+| `POSTINO_WEB_PORT` | `3333` | Web GUI port (auto-increments on collision) |
+| `POSTINO_WEB_ENABLED` | `true` | Set to `false` for MCP-only mode |
+| `POSTINO_AGENT_NAME` | auto-detected | Override agent name (auto-derived from terminal session ID) |
+| `POSTINO_MSG_TTL` | `86400` | Message/broadcast TTL in seconds (24h) |
+| `POSTINO_KEY_PREFIX` | `po:` | Valkey key prefix (change to run multiple instances) |
+
+### Named agents
+
+```bash
+claude mcp add postino -e POSTINO_AGENT_NAME=researcher -- node /path/to/postino/dist/index.js
+```
+
+Or rename at runtime:
+
+> "Rename yourself to devops-agent"
+
+---
+
+## Development
+
+```bash
+npm install          # Install dependencies
+npm run build        # Compile TypeScript + copy static assets
+npm run dev          # Watch mode
+npm test             # Run test suite (requires Valkey on localhost)
+```
+
+### Project structure
+
+```
+postino/
+  src/
+    index.ts              # Entry point: MCP server + web server
+    types.ts              # Config, interfaces
+    valkey.ts             # Valkey client, agent presence, pub/sub
+    tools/
+      messaging.ts        # All 8 MCP tools
+    web/
+      server.ts           # Hono HTTP server, static files
+      api.ts              # REST API + SSE
+      public/
+        index.html        # Single-file GUI (no build step, no CDN)
+        favicon.svg       # Favicon
+        logo.svg          # Logo sheet
+  hooks/
+    check-messages.sh     # UserPromptSubmit hook (zero-token check)
+    hooks.json            # Hook configuration
+  commands/
+    postino.md            # /postino slash command
+  test/                   # Integration tests (vitest)
+  .claude-plugin/
+    plugin.json           # Claude Code plugin manifest
+  .mcp.json               # MCP server registration
+```
+
+---
+
+## License
+
+MIT

package/commands/postino.md

@@ -0,0 +1,20 @@
+---
+name: postino
+description: Check your postino inbox, list agents, and manage messages
+argument-hint: [check|agents|broadcast <message>]
+allowed-tools: []
+---
+
+# Postino - Inter-agent messaging
+
+When the user runs `/postino`, help them with their messaging needs.
+
+## Behavior
+
+- `/postino` or `/postino check`: Check your inbox for new messages using `msg_check`, then read them with `msg_read` if any exist.
+- `/postino agents`: List all agents using `msg_list_agents`.
+- `/postino broadcast <message>`: Send a broadcast using `msg_broadcast`.
+- `/postino rename <name>`: Rename this agent using `msg_rename`.
+- `/postino whoami`: Show your agent identity using `msg_whoami`.
+
+Always use the postino MCP tools (msg_whoami, msg_check, msg_read, msg_send, msg_broadcast, msg_list_agents, msg_rename, msg_broadcasts) to accomplish these tasks. Do not fabricate responses.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+import { execSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const args = process.argv.slice(2);
+const command = args[0];
+function run(cmd) {
+    try {
+        return execSync(cmd, { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+    }
+    catch (e) {
+        const err = e;
+        return err.stderr?.trim() || err.message || "";
+    }
+}
+function hasClaude() {
+    const result = run("which claude");
+    return result.length > 0 && !result.includes("not found");
+}
+function install() {
+    console.log("\n  postino - message broker for Claude Code agents\n");
+    if (!hasClaude()) {
+        console.error("  Error: 'claude' CLI not found. Install Claude Code first:");
+        console.error("  https://docs.anthropic.com/en/docs/claude-code\n");
+        process.exit(1);
+    }
+    // Find the MCP server entry point (relative to this CLI script)
+    const serverPath = join(__dirname, "index.js");
+    // Check if already registered
+    const existing = run("claude mcp list 2>&1");
+    if (existing.includes("postino")) {
+        console.log("  Updating existing postino registration...\n");
+        run("claude mcp remove postino -s user 2>&1");
+    }
+    // Register globally (user scope)
+    const result = run(`claude mcp add postino -s user -- node ${serverPath}`);
+    if (result.includes("Added")) {
+        console.log("  Installed successfully!\n");
+        console.log("  Restart Claude Code to activate postino.");
+        console.log("  Web GUI will be at http://localhost:3333\n");
+        console.log("  Prerequisites:");
+        console.log("    - Valkey or Redis running on localhost:6379\n");
+        console.log("  To uninstall:  npx postino uninstall\n");
+    }
+    else {
+        console.log("  Registration output:", result);
+        console.log("\n  If this failed, try manually:");
+        console.log(`  claude mcp add postino -s user -- node ${serverPath}\n`);
+    }
+}
+function uninstall() {
+    console.log("\n  Removing postino...\n");
+    if (!hasClaude()) {
+        console.error("  Error: 'claude' CLI not found.\n");
+        process.exit(1);
+    }
+    const result = run("claude mcp remove postino -s user 2>&1");
+    if (result.includes("Removed") || result.includes("removed")) {
+        console.log("  Uninstalled successfully. Restart Claude Code.\n");
+    }
+    else {
+        console.log("  " + (result || "postino was not registered.") + "\n");
+    }
+}
+function printHelp() {
+    console.log(`
+  postino - message broker for Claude Code agents
+
+  Usage:
+    npx postino install       Register postino with Claude Code
+    npx postino uninstall     Remove postino from Claude Code
+
+  After installing, restart Claude Code. Your agents will have
+  access to messaging, broadcasts, and a web GUI.
+
+  Docs: https://github.com/manuelfedele/postino
+`);
+}
+switch (command) {
+    case "install":
+        install();
+        break;
+    case "uninstall":
+        uninstall();
+        break;
+    case "help":
+    case "--help":
+    case "-h":
+        printHelp();
+        break;
+    default:
+        // No CLI command: start the MCP server (normal operation)
+        import("./index.js");
+        break;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+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 { registerMessagingTools } from "./tools/messaging.js";
+import { startWebServer } from "./web/server.js";
+const config = loadConfig();
+const server = new McpServer({
+    name: "postino",
+    version: "0.1.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+registerMessagingTools(server, config.agentName);
+async function main() {
+    await connect();
+    await registerAgent(config.agentName);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    if (config.webEnabled) {
+        startWebServer(config.webPort);
+    }
+    process.stderr.write(`postino agent: ${config.agentName}\n`);
+    const shutdown = async () => {
+        await deregisterAgent(config.agentName);
+        await disconnect();
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+main().catch((err) => {
+    console.error("Failed to start postino:", err);
+    process.exit(1);
+});

package/dist/tools/messaging.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerMessagingTools(server: McpServer, initialName: string): void;