patchcord 0.3.59 → 0.3.61

package/.claude-plugin/plugin.json

@@ -1,10 +1,13 @@
 {
   "name": "patchcord",
-  "description": "Cross-machine agent messaging with auto-inbox checking. Agents automatically respond to messages from other agents without human intervention.",
-  "version": "0.3.28",
+  "description": "Cross-machine agent messaging with push delivery. Messages from other agents arrive as native channel notifications.",
+  "version": "0.4.0",
   "author": {
     "name": "ppravdin"
   },
   "repository": "https://github.com/ppravdin/patchcord",
-  "skills": "./skills/"
+  "skills": "./skills/",
+  "channel": {
+    "server": "./channel/server.ts"
+  }
 }

package/README.md

@@ -1,103 +1,38 @@
-# Patchcord Plugin for Claude Code
+# Patchcord Plugin
 
-Cross-machine messaging between Claude Code agents.
+Cross-machine messaging between AI coding agents.
 
-This plugin is not the connection itself.
-
-The plugin provides:
-
-- Patchcord skills
-- statusline integration
-- turn-end inbox checks
-
-The actual Patchcord connection must still come from the current project configuration.
-
-## Safe model
-
-Use this plugin with project-local Patchcord config.
-
-Good:
-
-- install the plugin once
-- keep `.mcp.json` inside each Patchcord-enabled project
-- let the plugin no-op in projects that do not have Patchcord configured
-
-Bad:
-
-- exporting `PATCHCORD_TOKEN` / `PATCHCORD_URL` globally in `~/.bashrc`, `~/.profile`, or similar
-- keeping Patchcord config in an ancestor directory like `~/.mcp.json`
-- assuming the plugin should make every project a Patchcord project
-
-## Setup
-
-### 1. Install the plugin
+## Install
 
 ```bash
-claude plugin marketplace add /path/to/patchcord-internal
-claude plugin install patchcord@patchcord-marketplace
+npx patchcord@latest
 ```
 
-### 2. Configure the project
+One command. Opens browser, configures everything. Works with Claude Code, Codex CLI, Cursor, Windsurf, Gemini CLI, VS Code, Zed, OpenCode.
 
-Create a project-local `.mcp.json` in the project that should act as a Patchcord agent.
+Self-hosted:
 
-Example:
-
-```json
-{
-  "mcpServers": {
-    "patchcord": {
-      "type": "http",
-      "url": "https://patchcord.yourdomain.com/mcp",
-      "headers": {
-        "Authorization": "Bearer <project-token>"
-      }
-    }
-  }
-}
+```bash
+npx patchcord@latest --token <token> --server https://patchcord.yourdomain.com
 ```
 
-### 3. Restart Claude Code in that project
-
-The plugin and statusline scripts read the current project configuration when the session starts.
-
-## What happens in non-Patchcord projects
-
-Nothing Patchcord-specific should appear.
+## What it provides
 
-- no Patchcord identity in the statusline
-- no inbox checks
-- no hook-driven Patchcord prompts
+- **Skills** — patchcord inbox and wait skills for all supported tools
+- **Statusline** — shows agent identity in Claude Code statusbar
+- **Stop hook** — checks inbox between turns, notifies of pending messages
+- **Slash commands** — `/patchcord` and `/patchcord-wait` for Codex and Gemini CLI
+- **MCP config** — per-project or global config depending on tool
 
-The plugin is allowed to stay installed globally, but it must no-op unless the current project is configured.
+## How it works
 
-## Self-hosted server
+The installer:
+1. Detects installed tools and installs global components (skills, permissions, statusline)
+2. Opens browser for project + agent setup (or uses `--token` for self-hosted)
+3. Writes the correct MCP config for the chosen tool
 
-The project `.mcp.json` should point to your own server URL:
-
-```json
-{
-  "mcpServers": {
-    "patchcord": {
-      "type": "http",
-      "url": "https://patchcord.yourdomain.com/mcp",
-      "headers": {
-        "Authorization": "Bearer <project-token>"
-      }
-    }
-  }
-}
-```
+The plugin no-ops in projects without patchcord configured.
 
 ## Verify
 
-In a Patchcord-enabled project:
-
-- statusline should show the Patchcord identity
-- `inbox()` should return the expected `namespace_id` and `agent_id`
-
-In an unrelated project:
-
-- statusline should not show Patchcord identity
-- no Patchcord hooks should fire
-- no Patchcord tools should be present unless that project is configured
+After setup, restart your tool session and say `check inbox`. Verify `agent_id` and `namespace_id` are correct.

package/bin/patchcord.mjs

@@ -63,11 +63,11 @@ if (cmd === "help" || cmd === "--help" || cmd === "-h") {
   console.log(`patchcord — agent messaging for AI coding agents
 
 Usage:
-  npx patchcord@latest              Full setup (global + project) — run in your project folder
-  npx patchcord@latest --full       Same + full statusline (model, context%, git)
-  npx patchcord@latest skill apply  Fetch custom skill from web console
-
-That's it. One command does everything.`);
+  npx patchcord@latest                                    Setup via browser (patchcord.dev)
+  npx patchcord@latest --token <token>                    Self-hosted / CI setup
+  npx patchcord@latest --token <token> --server <url>     Self-hosted with custom server
+  npx patchcord@latest --full                             Same + full statusline
+  npx patchcord@latest skill apply                        Fetch custom skill from web console`);
   process.exit(0);
 }
 
@@ -77,7 +77,7 @@ if (cmd === "plugin-path") {
 }
 
 // ── main flow: global setup + project setup (or just install/agent for back-compat) ──
-if (!cmd || cmd === "install" || cmd === "agent" || cmd === "--token" || cmd === "--no-browser") {
+if (!cmd || cmd === "install" || cmd === "agent" || cmd === "--token" || cmd === "--no-browser" || cmd === "--server") {
   const flags = cmd?.startsWith("--") ? process.argv.slice(2) : process.argv.slice(3);
   const fullStatusline = flags.includes("--full");
   const { readFileSync, writeFileSync } = await import("fs");
@@ -268,7 +268,20 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd === "--token" || cmd ===
   let apiUrl = "https://api.patchcord.dev";
   let clientType = "";
 
-  // --token bypass for power users / CI
+  // --server flag for self-hosters
+  const serverFlag = flags.find(f => f.startsWith("--server="))?.split("=")[1]
+    || (flags.includes("--server") ? flags[flags.indexOf("--server") + 1] : "");
+  if (serverFlag) {
+    if (!isSafeUrl(serverFlag)) {
+      console.error("Invalid server URL. Must start with https:// or http://");
+      rl.close();
+      process.exit(1);
+    }
+    serverUrl = serverFlag.replace(/\/+$/, "");
+    apiUrl = serverUrl;
+  }
+
+  // --token bypass for power users / CI / self-hosters
   const tokenFlag = flags.find(f => f.startsWith("--token="))?.split("=")[1]
     || (flags.includes("--token") ? flags[flags.indexOf("--token") + 1] : "");
 
@@ -663,7 +676,7 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd === "--token" || cmd ===
     console.log(`\n  ${green}✓${r} Codex configured: ${dim}${configPath}${r}`);
     console.log(`  ${green}✓${r} Slash commands: ${dim}/patchcord${r}, ${dim}/patchcord-wait${r}`);
   } else {
-    // Claude Code: write .mcp.json
+    // Claude Code: write .mcp.json (MCP server + channel plugin)
     const mcpPath = join(cwd, ".mcp.json");
     const mcpConfig = {
       mcpServers: {
@@ -675,6 +688,14 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd === "--token" || cmd ===
             "X-Patchcord-Machine": hostname,
           },
         },
+        "patchcord-channel": {
+          command: "npx",
+          args: ["patchcord@latest", "channel"],
+          env: {
+            PATCHCORD_TOKEN: token,
+            PATCHCORD_SERVER: serverUrl,
+          },
+        },
       },
     };
 
@@ -683,6 +704,7 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd === "--token" || cmd ===
         const existing = JSON.parse(readFileSync(mcpPath, "utf-8"));
         existing.mcpServers = existing.mcpServers || {};
         existing.mcpServers.patchcord = mcpConfig.mcpServers.patchcord;
+        existing.mcpServers["patchcord-channel"] = mcpConfig.mcpServers["patchcord-channel"];
         writeFileSync(mcpPath, JSON.stringify(existing, null, 2) + "\n");
       } catch {
         writeFileSync(mcpPath, JSON.stringify(mcpConfig, null, 2) + "\n");
@@ -691,6 +713,7 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd === "--token" || cmd ===
       writeFileSync(mcpPath, JSON.stringify(mcpConfig, null, 2) + "\n");
     }
     console.log(`\n  ${green}✓${r} Claude Code configured: ${dim}${mcpPath}${r}`);
+    console.log(`  ${dim}Channel plugin: launch with${r} ${bold}claude --dangerously-load-development-channels server:patchcord-channel${r}`);
   }
 
   // Warn about gitignore for per-project configs with tokens
@@ -720,6 +743,30 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd === "--token" || cmd ===
   process.exit(0);
 }
 
+// ── channel: spawn the channel MCP server (used by .mcp.json) ──
+if (cmd === "channel") {
+  const channelScript = join(pluginRoot, "channel", "server.ts");
+  if (!existsSync(channelScript)) {
+    console.error("Channel server not found. Reinstall patchcord.");
+    process.exit(1);
+  }
+  // Prefer bun, fall back to node (tsx)
+  const hasBun = run("which bun");
+  if (hasBun) {
+    const { spawnSync } = await import("child_process");
+    // Install deps if needed
+    const channelDir = join(pluginRoot, "channel");
+    if (!existsSync(join(channelDir, "node_modules"))) {
+      spawnSync("bun", ["install", "--no-summary"], { cwd: channelDir, stdio: "inherit" });
+    }
+    const result = spawnSync("bun", ["run", channelScript], { stdio: "inherit", env: process.env });
+    process.exit(result.status ?? 1);
+  } else {
+    console.error("Channel plugin requires bun. Install from https://bun.sh");
+    process.exit(1);
+  }
+}
+
 // ── back-compat: init → install + agent ───────────────────────
 if (cmd === "init") {
   console.log(`"patchcord init" is now two commands:

package/channel/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "patchcord-channel",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "start": "bun install --no-summary && bun server.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  }
+}

package/channel/server.ts

@@ -0,0 +1,331 @@
+#!/usr/bin/env bun
+/**
+ * Patchcord channel for Claude Code.
+ *
+ * Polls the Patchcord server for new messages and pushes them as native
+ * <channel> notifications. Exposes reply and send_message tools for
+ * two-way communication.
+ *
+ * Config: PATCHCORD_TOKEN and PATCHCORD_SERVER env vars (set by .mcp.json).
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js'
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+const TOKEN = process.env.PATCHCORD_TOKEN ?? ''
+const SERVER = (process.env.PATCHCORD_SERVER ?? 'https://mcp.patchcord.dev').replace(/\/+$/, '')
+const POLL_INTERVAL_MS = 3000
+
+if (!TOKEN) {
+  process.stderr.write(
+    `patchcord channel: PATCHCORD_TOKEN required\n` +
+    `  Set it in .mcp.json env block or as a shell environment variable.\n`,
+  )
+  process.exit(1)
+}
+
+// Safety nets
+process.on('unhandledRejection', err => {
+  process.stderr.write(`patchcord channel: unhandled rejection: ${err}\n`)
+})
+process.on('uncaughtException', err => {
+  process.stderr.write(`patchcord channel: uncaught exception: ${err}\n`)
+})
+
+// ---------------------------------------------------------------------------
+// Identity (resolved on startup)
+// ---------------------------------------------------------------------------
+
+let agentId = ''
+let namespaceId = ''
+
+async function resolveIdentity(): Promise<void> {
+  const res = await fetch(`${SERVER}/api/inbox?limit=0&count_only=true`, {
+    headers: { Authorization: `Bearer ${TOKEN}` },
+  })
+  if (!res.ok) {
+    const text = await res.text()
+    throw new Error(`identity check failed: ${res.status} ${text.slice(0, 200)}`)
+  }
+  const data = await res.json() as { agent_id: string; namespace_id: string }
+  agentId = data.agent_id
+  namespaceId = data.namespace_id
+  process.stderr.write(`patchcord channel: connected as ${agentId}@${namespaceId}\n`)
+}
+
+// ---------------------------------------------------------------------------
+// HTTP helpers
+// ---------------------------------------------------------------------------
+
+const headers = {
+  Authorization: `Bearer ${TOKEN}`,
+  'Content-Type': 'application/json',
+}
+
+async function channelPoll(): Promise<PollMessage[]> {
+  const res = await fetch(`${SERVER}/api/channel/poll`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify({}),
+  })
+  if (!res.ok) {
+    throw new Error(`poll failed: ${res.status}`)
+  }
+  return await res.json() as PollMessage[]
+}
+
+async function channelSend(to_agent: string, content: string): Promise<any> {
+  const res = await fetch(`${SERVER}/api/channel/send`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify({ to_agent, content }),
+  })
+  if (!res.ok) {
+    const text = await res.text()
+    throw new Error(`send failed: ${res.status} ${text.slice(0, 200)}`)
+  }
+  return await res.json()
+}
+
+async function channelReply(message_id: string, content: string): Promise<any> {
+  const res = await fetch(`${SERVER}/api/channel/reply`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify({ message_id, content }),
+  })
+  if (!res.ok) {
+    const text = await res.text()
+    throw new Error(`reply failed: ${res.status} ${text.slice(0, 200)}`)
+  }
+  return await res.json()
+}
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+type PollMessage = {
+  id: string
+  from_agent: string
+  content: string
+  created_at: string
+  namespace_id: string
+  reply_to: string | null
+}
+
+// ---------------------------------------------------------------------------
+// MCP Server
+// ---------------------------------------------------------------------------
+
+const mcp = new Server(
+  { name: 'patchcord', version: '0.1.0' },
+  {
+    capabilities: {
+      experimental: { 'claude/channel': {} },
+      tools: {},
+    },
+    instructions: [
+      'Messages from Patchcord agents arrive as <channel source="patchcord" from="..." message_id="..." namespace="...">.',
+      'Reply with the reply tool, passing message_id from the notification.',
+      'Use send_message to start new conversations with other agents.',
+      'Messages arrive automatically - no need to call inbox or wait_for_message.',
+    ].join(' '),
+  },
+)
+
+// ---------------------------------------------------------------------------
+// Tools
+// ---------------------------------------------------------------------------
+
+mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: 'reply',
+      description: 'Reply to a Patchcord message. Pass message_id from the <channel> notification.',
+      inputSchema: {
+        type: 'object' as const,
+        properties: {
+          message_id: { type: 'string', description: 'ID from the <channel> notification' },
+          content: { type: 'string', description: 'Reply text (up to 50,000 characters)' },
+        },
+        required: ['message_id', 'content'],
+      },
+    },
+    {
+      name: 'send_message',
+      description: 'Send a new message to a Patchcord agent. Use commas for multiple recipients.',
+      inputSchema: {
+        type: 'object' as const,
+        properties: {
+          to_agent: { type: 'string', description: 'Target agent name, optionally with @namespace' },
+          content: { type: 'string', description: 'Message text (up to 50,000 characters)' },
+        },
+        required: ['to_agent', 'content'],
+      },
+    },
+    {
+      name: 'inbox',
+      description: 'Check current Patchcord inbox. Shows pending messages. Normally not needed - messages arrive as push notifications.',
+      inputSchema: {
+        type: 'object' as const,
+        properties: {},
+      },
+    },
+  ],
+}))
+
+mcp.setRequestHandler(CallToolRequestSchema, async req => {
+  const { name } = req.params
+  const args = req.params.arguments as Record<string, string>
+
+  if (name === 'reply') {
+    if (!args.message_id || !args.content) {
+      return { content: [{ type: 'text', text: 'Error: message_id and content are required' }] }
+    }
+    try {
+      const result = await channelReply(args.message_id, args.content)
+      return { content: [{ type: 'text', text: `Replied to ${result.to_agent} [${result.id}]` }] }
+    } catch (err) {
+      return { content: [{ type: 'text', text: `Error: ${err}` }] }
+    }
+  }
+
+  if (name === 'send_message') {
+    if (!args.to_agent || !args.content) {
+      return { content: [{ type: 'text', text: 'Error: to_agent and content are required' }] }
+    }
+    try {
+      const result = await channelSend(args.to_agent, args.content)
+      return { content: [{ type: 'text', text: `Sent to ${result.to_agent} [${result.id}]` }] }
+    } catch (err) {
+      return { content: [{ type: 'text', text: `Error: ${err}` }] }
+    }
+  }
+
+  if (name === 'inbox') {
+    try {
+      const messages = await channelPoll()
+      if (messages.length === 0) {
+        return { content: [{ type: 'text', text: `${agentId}@${namespaceId} | 0 pending` }] }
+      }
+      const lines = [`${agentId}@${namespaceId} | ${messages.length} pending`]
+      for (const msg of messages) {
+        lines.push('')
+        lines.push(`From ${msg.from_agent} [${msg.id}]`)
+        lines.push(`  ${msg.content}`)
+        // Push as notification too
+        await pushMessage(msg)
+      }
+      return { content: [{ type: 'text', text: lines.join('\n') }] }
+    } catch (err) {
+      return { content: [{ type: 'text', text: `Error: ${err}` }] }
+    }
+  }
+
+  throw new Error(`unknown tool: ${name}`)
+})
+
+// ---------------------------------------------------------------------------
+// Poll loop
+// ---------------------------------------------------------------------------
+
+let consecutiveFailures = 0
+let connectionLostNotified = false
+
+async function pushMessage(msg: PollMessage): Promise<void> {
+  const meta: Record<string, string> = {
+    from: msg.from_agent,
+    message_id: msg.id,
+    namespace: msg.namespace_id,
+    sent_at: msg.created_at,
+  }
+  if (msg.reply_to) {
+    meta.in_reply_to = msg.reply_to
+  }
+  await mcp.notification({
+    method: 'notifications/claude/channel',
+    params: { content: msg.content, meta },
+  })
+}
+
+async function poll(): Promise<void> {
+  try {
+    const messages = await channelPoll()
+    consecutiveFailures = 0
+    if (connectionLostNotified) {
+      connectionLostNotified = false
+      await mcp.notification({
+        method: 'notifications/claude/channel',
+        params: {
+          content: 'Patchcord connection restored.',
+          meta: { from: 'system', message_id: 'system' },
+        },
+      })
+    }
+    for (const msg of messages) {
+      await pushMessage(msg)
+    }
+  } catch (err) {
+    consecutiveFailures++
+    process.stderr.write(`patchcord channel: poll error (${consecutiveFailures}): ${err}\n`)
+
+    if (consecutiveFailures === 1) {
+      // Check if it's an auth error
+      const errStr = String(err)
+      if (errStr.includes('401')) {
+        process.stderr.write('patchcord channel: auth failed, stopping poll\n')
+        await mcp.notification({
+          method: 'notifications/claude/channel',
+          params: {
+            content: 'Patchcord auth failed. Check your token configuration.',
+            meta: { from: 'system', message_id: 'system' },
+          },
+        })
+        clearInterval(pollTimer)
+        return
+      }
+    }
+
+    if (consecutiveFailures >= 10 && !connectionLostNotified) {
+      connectionLostNotified = true
+      try {
+        await mcp.notification({
+          method: 'notifications/claude/channel',
+          params: {
+            content: 'Patchcord connection lost. Retrying...',
+            meta: { from: 'system', message_id: 'system' },
+          },
+        })
+      } catch {
+        // notification itself failed, give up
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Startup
+// ---------------------------------------------------------------------------
+
+// Resolve identity first
+try {
+  await resolveIdentity()
+} catch (err) {
+  process.stderr.write(`patchcord channel: failed to connect: ${err}\n`)
+  process.stderr.write('patchcord channel: will retry on first poll\n')
+}
+
+// Connect MCP over stdio
+await mcp.connect(new StdioServerTransport())
+
+// Drain existing messages, then start polling
+await poll()
+const pollTimer = setInterval(poll, POLL_INTERVAL_MS)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchcord",
-  "version": "0.3.59",
+  "version": "0.3.61",
   "description": "Cross-machine agent messaging for Claude Code and Codex",
   "author": "ppravdin",
   "license": "MIT",
@@ -22,6 +22,7 @@
   },
   "files": [
     "bin/",
+    "channel/",
     ".claude-plugin/",
     "hooks/",
     "scripts/",

package/skills/inbox/SKILL.md

@@ -87,5 +87,6 @@ Deferred messages survive context compaction — the agent won't forget them.
 - If user says "check" or "check patchcord" — call inbox().
 - Presence is not a send or delivery gate. Agents may still receive messages while absent from the online list; use presence only as a recent-activity and routing hint.
 - send_message() is blocked by unread inbox items, not by offline status. If sending is blocked, clear actionable inbox items first.
-- Resolve machine names to agent_ids from inbox() results.
+- Resolve machine names to agent_ids from inbox() results. The human operator is always `human` - never use their real name.
+- Only send to agents that exist in your inbox online list. Don't guess agent names.
 - Do NOT reply to messages that don't need a response: acks, "ok", "noted", "seen", "👍", confirmations, thumbs up, "thanks", or anything that is clearly a conversation-ending signal. Just read them and move on. Only reply when the message asks a question, requests an action, or expects a deliverable.