patchcord 0.2.1 → 0.2.2

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "patchcord",
   "description": "Cross-machine agent messaging with auto-inbox checking. Agents automatically respond to messages from other agents without human intervention.",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "author": {
     "name": "ppravdin"
   },

package/README.md

@@ -2,42 +2,24 @@
 
 Cross-machine messaging between Claude Code agents.
 
-This plugin is not the connection itself.
+## Install
 
-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:
+```bash
+npm install -g patchcord
+patchcord init
+```
 
-- exporting `PATCHCORD_TOKEN` / `PATCHCORD_URL` globally in shell startup files
-- keeping Patchcord config in an ancestor directory like `~/.mcp.json`
-- assuming the plugin should make every project a Patchcord project
+The plugin provides skills, statusline integration, and turn-end inbox hooks. The actual Patchcord connection comes from the project's `.mcp.json`.
 
-## Setup
+## How it works
 
-### 1. Install the plugin
+- Install the plugin once (globally)
+- Keep `.mcp.json` inside each Patchcord-enabled project
+- The plugin no-ops in projects without Patchcord configured
 
-```bash
-claude plugin marketplace add /path/to/patchcord
-claude plugin install patchcord@patchcord-marketplace
-```
+Don't export `PATCHCORD_TOKEN` / `PATCHCORD_URL` globally or put config in `~/.mcp.json`.
 
-### 2. Configure the project
+## Configure the project
 
 Create a project-local `.mcp.json` in the project that should act as a Patchcord agent.
 

package/bin/patchcord.mjs

@@ -1,25 +1,31 @@
 #!/usr/bin/env node
 
-import { existsSync, mkdirSync, cpSync, readFileSync } from "fs";
+import { existsSync, mkdirSync, cpSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
+import { execSync } from "child_process";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pluginRoot = join(__dirname, "..");
 const cmd = process.argv[2];
 
+function run(cmd) {
+  try {
+    return execSync(cmd, { stdio: "pipe", encoding: "utf-8" }).trim();
+  } catch {
+    return null;
+  }
+}
+
 if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
   console.log(`patchcord — agent messaging for Claude Code & Codex
 
-Usage:
-  patchcord init              Auto-detect and set up for current project
-  patchcord init --codex      Set up Codex skill in current project
-  patchcord init --claude     Set up Claude Code plugin
-  patchcord plugin-path       Print path to Claude Code plugin directory
+Commands:
+  patchcord install       Install/update plugin globally (Claude Code)
+  patchcord agent         Set up MCP config for an agent in this project
+  patchcord agent --codex Set up Codex skill + MCP config in this project
 
-Setup after init:
-  1. Add your MCP server to .mcp.json (Claude Code) or ~/.codex/config.toml (Codex)
-  2. Start your agent — patchcord tools are available immediately`);
+Run "patchcord install" once. Run "patchcord agent" in each project.`);
   process.exit(0);
 }
 
@@ -28,31 +34,52 @@ if (cmd === "plugin-path") {
   process.exit(0);
 }
 
-if (cmd === "init") {
+// ── install: global plugin + skills (idempotent) ──────────────
+if (cmd === "install") {
+  const hasClaude = run("which claude");
+  if (!hasClaude) {
+    console.log(`Claude Code CLI not found. Install it first:
+  https://claude.ai/code
+
+Then run: patchcord install`);
+    process.exit(1);
+  }
+
+  console.log("Installing patchcord plugin into Claude Code...");
+  const result = run(`claude plugin install --path "${pluginRoot}"`);
+  if (result !== null) {
+    console.log(`✓ Plugin installed. Skills, hooks, and statusline are active.
+
+Run "patchcord agent" in each project to set up MCP.`);
+  } else {
+    console.log(`✗ Plugin install failed. Try manually:
+  claude plugin install --path "${pluginRoot}"`);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+// ── agent: per-project MCP setup ──────────────────────────────
+if (cmd === "agent") {
   const flag = process.argv[3];
   const cwd = process.cwd();
 
   if (flag === "--codex" || (!flag && existsSync(join(cwd, ".agents")))) {
-    // Codex setup: copy SKILL.md to .agents/skills/patchcord/
+    // Codex: copy skill + print MCP config
     const dest = join(cwd, ".agents", "skills", "patchcord");
     mkdirSync(dest, { recursive: true });
     cpSync(join(pluginRoot, "codex", "SKILL.md"), join(dest, "SKILL.md"));
-    console.log(`Codex skill installed: ${dest}/SKILL.md
+    console.log(`✓ Codex skill installed: ${dest}/SKILL.md
 
-Next: add patchcord MCP server to ~/.codex/config.toml:
+Add to ~/.codex/config.toml:
 
   [mcp_servers.patchcord]
   url = "https://YOUR_SERVER/mcp"
   bearer_token_env_var = "PATCHCORD_TOKEN"
   http_headers = { "X-Patchcord-Client-Type" = "codex" }`);
-  } else if (flag === "--claude" || !flag) {
-    // Claude Code setup: install plugin
-    console.log(`Claude Code plugin path: ${pluginRoot}
-
-Install with:
-  claude plugin install --path "${pluginRoot}"
-
-Then add .mcp.json to your project:
+  } else {
+    // Claude Code: print .mcp.json template
+    console.log(`Add .mcp.json to this project:
 
   {
     "mcpServers": {
@@ -65,8 +92,24 @@ Then add .mcp.json to your project:
         }
       }
     }
-  }`);
   }
+
+Or use the CLI:
+
+  claude mcp add patchcord "https://YOUR_SERVER/mcp" \\
+    --transport http -s project \\
+    -H "Authorization: Bearer YOUR_TOKEN" \\
+    -H "X-Patchcord-Client-Type: claude_code"`);
+  }
+  process.exit(0);
+}
+
+// ── back-compat: init → install + agent ───────────────────────
+if (cmd === "init") {
+  console.log(`"patchcord init" is now two commands:
+
+  patchcord install    Install/update plugin globally (once)
+  patchcord agent      Set up MCP for this project (per project)`);
   process.exit(0);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchcord",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Cross-machine agent messaging for Claude Code and Codex",
   "author": "ppravdin",
   "license": "MIT",

package/scripts/statusline.sh

@@ -126,8 +126,36 @@ if [ -n "$pc_url" ] && [ -n "$pc_token" ]; then
     fi
 fi
 
+# ── Update check (once per 24h) ───────────────────────
+update_part=""
+plugin_json="${CLAUDE_PLUGIN_ROOT:-.}/.claude-plugin/plugin.json"
+if [ -f "$plugin_json" ]; then
+    installed_ver=$(jq -r '.version // ""' "$plugin_json" 2>/dev/null)
+    if [ -n "$installed_ver" ]; then
+        update_cache="/tmp/claude/patchcord-update-check.json"
+        mkdir -p /tmp/claude
+        update_stale=true
+        if [ -f "$update_cache" ]; then
+            uc_mtime=$(stat -c %Y "$update_cache" 2>/dev/null || stat -f %m "$update_cache" 2>/dev/null)
+            uc_now=$(date +%s)
+            [ $(( uc_now - uc_mtime )) -lt 86400 ] && update_stale=false
+        fi
+        if $update_stale; then
+            latest=$(npm view patchcord version --json 2>/dev/null | tr -d '"' || true)
+            if [ -n "$latest" ]; then
+                echo "{\"latest\":\"$latest\"}" > "$update_cache"
+            fi
+        else
+            latest=$(jq -r '.latest // ""' "$update_cache" 2>/dev/null)
+        fi
+        if [ -n "$latest" ] && [ "$latest" != "$installed_ver" ]; then
+            update_part="${yellow}⬆ ${latest} (npm update -g patchcord)${reset}"
+        fi
+    fi
+fi
+
 # No patchcord config — output nothing in default mode
-if [ -z "$pc_part" ] && ! $FULL; then
+if [ -z "$pc_part" ] && [ -z "$update_part" ] && ! $FULL; then
     exit 0
 fi
 
@@ -176,8 +204,18 @@ if $FULL; then
         line+="${sep}"
         line+="${pc_part}"
     fi
+    if [ -n "$update_part" ]; then
+        line+="${sep}"
+        line+="${update_part}"
+    fi
 else
     line="${pc_part}"
+    if [ -n "$update_part" ]; then
+        if [ -n "$line" ]; then
+            line+="${sep}"
+        fi
+        line+="${update_part}"
+    fi
 fi
 
 # ── Output ──────────────────────────────────────────────

package/skills/inbox/SKILL.md

@@ -18,7 +18,7 @@ If there are pending messages, reply to ALL of them IMMEDIATELY. Do not ask the
 
 ## Sending
 
-1. inbox() — check who's online
+1. inbox() — read pending mail and recent presence for routing
 2. send_message("agent_name", "specific question with file paths and context")
 3. wait_for_message() — auto-wait for any response, don't ask human whether to wait
 
@@ -59,6 +59,8 @@ Deferred messages survive context compaction — the agent won't forget them.
 - Never show raw JSON to the human — summarize naturally
 - One inbox() to orient. Don't call it repeatedly.
 - 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
 - list_recent_debug is for debugging only — never call it routinely
 - 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.