patchcord 0.3.3 → 0.3.5

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.3.3",
+  "version": "0.3.5",
   "author": {
     "name": "ppravdin"
   },

package/README.md

@@ -2,20 +2,85 @@
 
 Cross-machine messaging between Claude Code agents.
 
+<<<<<<< Updated upstream
 ## Install
+||||||| Stash base
+## Setup (3 steps)
 
+**1.** Copy `.env.example` to `.env` and paste your token:
+=======
+This plugin is not the connection itself.
+
+The plugin provides:
+>>>>>>> Stashed changes
+
+<<<<<<< Updated upstream
 ```bash
 npx patchcord@latest install
 ```
+||||||| Stash base
+```bash
+cp .env.example .env
+# Open .env, replace paste-your-token-here with your actual token
+```
+=======
+- Patchcord skills
+- statusline integration
+- turn-end inbox checks
+>>>>>>> Stashed changes
 
+<<<<<<< Updated upstream
 Or with full statusline (model, context%, git branch):
+||||||| Stash base
+**2.** Load the env vars (pick one):
+=======
+The actual Patchcord connection must still come from the current project configuration.
+>>>>>>> Stashed changes
 
+<<<<<<< Updated upstream
 ```bash
 npx patchcord@latest install --full
 ```
+||||||| Stash base
+```bash
+# Option A: add to your shell profile (~/.bashrc or ~/.zshrc)
+echo 'source /path/to/your/.env' >> ~/.bashrc
+
+# Option B: use direnv (if you have it)
+cp .env .envrc && direnv allow
+
+# Option C: just export manually
+export PATCHCORD_TOKEN="your-token"
+```
+=======
+## Safe model
+
+Use this plugin with project-local Patchcord config.
 
+Good:
+>>>>>>> Stashed changes
+
+<<<<<<< Updated upstream
 The plugin provides skills, statusline integration, and turn-end inbox hooks. The actual Patchcord connection comes from the project's `.mcp.json`.
+||||||| Stash base
+**3.** Install the plugin and start Claude Code:
+=======
+- 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
+>>>>>>> Stashed changes
+
+<<<<<<< Updated upstream
 ## How it works
 
 - Install the plugin once (globally)
@@ -41,8 +106,19 @@ Create a project-local `.mcp.json` in the project that should act as a Patchcord
     }
   }
 }
+||||||| Stash base
+```bash
+claude plugin marketplace add /path/to/patchcord-internal
+claude plugin install patchcord@patchcord-marketplace
+claude
+=======
+```bash
+claude plugin marketplace add /path/to/patchcord-internal
+claude plugin install patchcord@patchcord-marketplace
+>>>>>>> Stashed changes
 ```
 
+<<<<<<< Updated upstream
 ### 3. Start Claude Code in that project
 
 The plugin and statusline scripts read the current project configuration from the session's working tree.
@@ -56,9 +132,47 @@ Nothing Patchcord-specific should appear.
 - no hook-driven Patchcord prompts
 
 The plugin can stay installed globally, but it must no-op unless the current project is configured.
+||||||| Stash base
+That's it. Inbox, send messages, reply — all works automatically.
+=======
+### 2. Configure the project
+
+Create a project-local `.mcp.json` in the project that should act as a Patchcord agent.
+
+Example:
+
+```json
+{
+  "mcpServers": {
+    "patchcord": {
+      "type": "http",
+      "url": "https://patchcord.yourdomain.com/mcp",
+      "headers": {
+        "Authorization": "Bearer <project-token>"
+      }
+    }
+  }
+}
+```
+
+### 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.
+
+- no Patchcord identity in the statusline
+- no inbox checks
+- no hook-driven Patchcord prompts
+
+The plugin is allowed to stay installed globally, but it must no-op unless the current project is configured.
+>>>>>>> Stashed changes
 
 ## Self-hosted server
 
+<<<<<<< Updated upstream
 Point the project `.mcp.json` at your own server URL.
 
 Bearer-token clients can also use `/mcp/bearer` if you want the dedicated bearer-only endpoint.
@@ -82,8 +196,26 @@ npx patchcord@latest install --full
 ```
 
 Without `--full`:
+||||||| Stash base
+By default the plugin connects to `https://patchcord.dev`. If you run your own server, add to your `.env`:
+=======
+The project `.mcp.json` should point to your own server URL:
+>>>>>>> Stashed changes
 
+```json
+{
+  "mcpServers": {
+    "patchcord": {
+      "type": "http",
+      "url": "https://patchcord.yourdomain.com/mcp",
+      "headers": {
+        "Authorization": "Bearer <project-token>"
+      }
+    }
+  }
+}
 ```
+<<<<<<< Updated upstream
 ds@default (thick) 2 msg
 ```
 
@@ -105,3 +237,21 @@ In an unrelated project:
 - statusline should be empty (default) or show only model/context/git (`--full`)
 - no Patchcord hooks should fire
 - no Patchcord tools should be present unless that project is configured
+||||||| Stash base
+PATCHCORD_URL=https://your-server.example.com
+```
+=======
+
+## 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
+>>>>>>> Stashed changes

package/bin/patchcord.mjs

@@ -204,38 +204,13 @@ if (cmd === "skill") {
     process.exit(1);
   }
 
-  const START_DELIM = "########## PATCHCORD CUSTOM SKILL ##########";
-  const END_DELIM = "########## END CUSTOM SKILL ##########";
-
-  // Find the skill file
-  const skillFile = join(cwd, "PATCHCORD.md");
-  const pluginSkill = join(pluginRoot, "skills", "inbox", "SKILL.md");
-
-  function applyCustomSkill(skillText) {
-    let content = "";
-    if (existsSync(skillFile)) {
-      content = readFileSync(skillFile, "utf-8");
-    } else if (existsSync(pluginSkill)) {
-      content = readFileSync(pluginSkill, "utf-8");
-    }
-
-    // Remove existing custom skill block
-    const startIdx = content.indexOf(START_DELIM);
-    const endIdx = content.indexOf(END_DELIM);
-    if (startIdx !== -1 && endIdx !== -1) {
-      content = content.substring(0, startIdx).trimEnd();
-    }
-
-    // Append new custom skill
-    if (skillText && skillText.trim()) {
-      content = content.trimEnd() + "\n\n" + START_DELIM + "\n" + skillText.trim() + "\n" + END_DELIM + "\n";
-    }
-
-    writeFileSync(skillFile, content);
-  }
+  // Custom skill goes to .claude/skills/patchcord-custom/SKILL.md
+  // Claude Code auto-discovers project-level skills from this directory.
+  // Only the custom part — default patchcord skill is already loaded globally by the plugin.
+  const skillDir = join(cwd, ".claude", "skills", "patchcord-custom");
+  const skillFile = join(skillDir, "SKILL.md");
 
   if (sub === "apply" || !sub) {
-    // Fetch and apply custom skill
     console.log(`Fetching custom skill for ${namespace}:${agentId}...`);
     const resp = run(`curl -s -H "Authorization: Bearer ${token}" "${baseUrl}/api/skills/${namespace}/${agentId}"`);
     if (!resp) {
@@ -245,7 +220,8 @@ if (cmd === "skill") {
     try {
       const data = JSON.parse(resp);
       if (data.skill_text) {
-        applyCustomSkill(data.skill_text);
+        mkdirSync(skillDir, { recursive: true });
+        writeFileSync(skillFile, data.skill_text.trim() + "\n");
         console.log(`✓ Custom skill applied to ${skillFile}`);
       } else {
         console.log("No custom skill set for this agent.");
@@ -255,30 +231,38 @@ if (cmd === "skill") {
       process.exit(1);
     }
   } else if (sub === "reinstall") {
-    // Full rewrite: default skill + custom skill
-    console.log("Reinstalling patchcord skill...");
-    if (existsSync(pluginSkill)) {
-      let defaultContent = readFileSync(pluginSkill, "utf-8");
-      writeFileSync(skillFile, defaultContent);
-    }
-    // Then apply custom on top
+    console.log(`Fetching custom skill for ${namespace}:${agentId}...`);
     const resp = run(`curl -s -H "Authorization: Bearer ${token}" "${baseUrl}/api/skills/${namespace}/${agentId}"`);
     try {
       const data = JSON.parse(resp || "{}");
       if (data.skill_text) {
-        applyCustomSkill(data.skill_text);
-        console.log(`✓ Skill reinstalled with custom block at ${skillFile}`);
+        mkdirSync(skillDir, { recursive: true });
+        writeFileSync(skillFile, data.skill_text.trim() + "\n");
+        console.log(`✓ Custom skill applied to ${skillFile}`);
       } else {
-        console.log(`✓ Skill reinstalled (no custom block) at ${skillFile}`);
+        // Remove custom skill if none set
+        if (existsSync(skillFile)) {
+          const { unlinkSync } = await import("fs");
+          unlinkSync(skillFile);
+          console.log("Custom skill removed (none set on server).");
+        } else {
+          console.log("No custom skill set for this agent.");
+        }
       }
     } catch {
-      console.log(`✓ Skill reinstalled (no custom block) at ${skillFile}`);
+      console.log("No custom skill set or server unreachable.");
     }
   } else {
     console.log(`Unknown skill subcommand: ${sub}
 Usage:
   patchcord skill apply      Fetch and apply custom skill from server
-  patchcord skill reinstall  Full rewrite: default + custom skill`);
+  patchcord skill reinstall  Re-fetch custom skill from server`);
+  }
+  // Clean up old PATCHCORD.md if it exists
+  const oldFile = join(cwd, "PATCHCORD.md");
+  if (existsSync(oldFile)) {
+    const { unlinkSync } = await import("fs");
+    unlinkSync(oldFile);
   }
   process.exit(0);
 }

package/codex/SKILL.md

@@ -22,6 +22,10 @@ If there are pending messages, reply to ALL of them IMMEDIATELY. Do not ask the
 2. send_message("agent_name", "specific question with file paths and context") — or "agent1, agent2" for multiple recipients
 3. wait_for_message() — auto-wait for any response, don't ask human whether to wait
 
+ALWAYS send regardless of online/offline status. Messages are stored and delivered when the recipient checks inbox. Never refuse to send because an agent appears offline.
+
+After sending to an offline agent, tell the human: "Message sent. [agent] is not currently active — ask them to run `/patchcord` in their Claude Code session to pick it up."
+
 ## Receiving (inbox has messages)
 
 1. Read the question from inbox() result

package/package.json

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

package/scripts/check-inbox.sh

@@ -62,7 +62,7 @@ MACHINE_NAME=$(hostname -s 2>/dev/null || echo "unknown")
 HTTP_CODE=$(curl -s -o /tmp/patchcord_inbox.json -w "%{http_code}" --max-time 5 \
   -H "Authorization: Bearer ${TOKEN}" \
   -H "x-patchcord-machine: ${MACHINE_NAME}" \
-  "${URL}/api/inbox?status=pending&limit=1" 2>/dev/null || echo "000")
+  "${URL}/api/inbox?status=pending&limit=5&count_only=1" 2>/dev/null || echo "000")
 
 if [ "$HTTP_CODE" = "401" ] || [ "$HTTP_CODE" = "403" ]; then
   jq -n '{
@@ -83,8 +83,8 @@ RESPONSE=$(cat /tmp/patchcord_inbox.json 2>/dev/null || echo '{"count":0}')
 rm -f /tmp/patchcord_inbox.json
 
 # ── Auto-apply custom skill from web console ──────────────────
-# Fetch custom skill and update PATCHCORD.md if changed.
-# Runs silently alongside inbox check — no user action needed.
+# Writes to .claude/skills/patchcord-custom/SKILL.md — Claude Code
+# native project-level skill directory. Auto-discovered by Claude.
 NAMESPACE=$(echo "$RESPONSE" | jq -r '.namespace_id // empty' 2>/dev/null || true)
 AGENT_ID=$(echo "$RESPONSE" | jq -r '.agent_id // empty' 2>/dev/null || true)
 
@@ -100,21 +100,14 @@ if [ -n "$NAMESPACE" ] && [ -n "$AGENT_ID" ]; then
     OLD_HASH=$(cat "$CACHE_FILE" 2>/dev/null || echo "")
 
     if [ -n "$SKILL_TEXT" ] && [ "$SKILL_HASH" != "$OLD_HASH" ]; then
-      # Find the skill file (project root PATCHCORD.md)
       PROJECT_ROOT=$(dirname "$MCP_JSON")
-      SKILL_FILE="${PROJECT_ROOT}/PATCHCORD.md"
-      START_DELIM="########## PATCHCORD CUSTOM SKILL ##########"
-      END_DELIM="########## END CUSTOM SKILL ##########"
-
-      if [ -f "$SKILL_FILE" ]; then
-        # Remove existing custom block and append new one
-        BEFORE=$(sed "/${START_DELIM}/,\$d" "$SKILL_FILE")
-        printf '%s\n\n%s\n%s\n%s\n' "$BEFORE" "$START_DELIM" "$SKILL_TEXT" "$END_DELIM" > "$SKILL_FILE"
-      else
-        # Create with just the custom block
-        printf '%s\n%s\n%s\n' "$START_DELIM" "$SKILL_TEXT" "$END_DELIM" > "$SKILL_FILE"
-      fi
+      SKILL_DIR="${PROJECT_ROOT}/.claude/skills/patchcord-custom"
+      SKILL_FILE="${SKILL_DIR}/SKILL.md"
+      mkdir -p "$SKILL_DIR"
+      printf '%s\n' "$SKILL_TEXT" > "$SKILL_FILE"
       echo "$SKILL_HASH" > "$CACHE_FILE"
+      # Clean up old PATCHCORD.md if it exists
+      rm -f "${PROJECT_ROOT}/PATCHCORD.md"
     fi
   fi
 fi

package/scripts/statusline.sh

@@ -85,6 +85,7 @@ if [ -n "$pc_url" ] && [ -n "$pc_token" ]; then
     if $needs_refresh; then
         http_code=$(curl -s -o /tmp/claude/patchcord-sl-resp.json -w "%{http_code}" --max-time 3 \
             -H "Authorization: Bearer $pc_token" \
+<<<<<<< Updated upstream
             "${pc_url}/api/inbox?status=pending&limit=50" 2>/dev/null || echo "000")
         if [ "$http_code" = "401" ] || [ "$http_code" = "403" ]; then
             pc_data='{"_auth_error":true}'
@@ -92,11 +93,25 @@ if [ -n "$pc_url" ] && [ -n "$pc_token" ]; then
         elif [ "$http_code" = "200" ]; then
             pc_data=$(cat /tmp/claude/patchcord-sl-resp.json 2>/dev/null)
             [ -n "$pc_data" ] && echo "$pc_data" > "$cache_file"
+||||||| Stash base
+            "${pc_url}/api/inbox?status=pending&limit=50" 2>/dev/null || true)
+        if [ -n "$response" ]; then
+            pc_data="$response"
+            echo "$response" > "$cache_file"
+        elif [ -f "$cache_file" ]; then
+            pc_data=$(cat "$cache_file" 2>/dev/null)
+=======
+            "${pc_url}/api/inbox?status=pending&limit=50" 2>/dev/null || true)
+        if [ -n "$response" ]; then
+            pc_data="$response"
+            echo "$response" > "$cache_file"
+>>>>>>> Stashed changes
         fi
         rm -f /tmp/claude/patchcord-sl-resp.json
     fi
 
     if [ -n "$pc_data" ]; then
+<<<<<<< Updated upstream
         auth_error=$(echo "$pc_data" | jq -r '._auth_error // false' 2>/dev/null)
         if [ "$auth_error" = "true" ]; then
             pc_part="${red}BAD TOKEN${reset}"
@@ -106,6 +121,32 @@ if [ -n "$pc_url" ] && [ -n "$pc_token" ]; then
             machine=$(echo "$pc_data" | jq -r '.machine_name // empty' 2>/dev/null)
             if [ -z "$machine" ] || [ "$machine" = "null" ]; then
                 machine=$(hostname -s 2>/dev/null || hostname 2>/dev/null || echo "")
+||||||| Stash base
+        agent_id=$(echo "$pc_data" | jq -r '.agent_id // empty' 2>/dev/null)
+        machine=$(hostname -s 2>/dev/null || hostname 2>/dev/null || echo "")
+        count=$(echo "$pc_data" | jq -r '.count // .pending_count // 0' 2>/dev/null)
+
+        if [ -n "$agent_id" ]; then
+            pc_part="${white}${agent_id}${reset}"
+            if [ -n "$machine" ]; then
+                pc_part+="${dim}@${machine}${reset}"
+=======
+        agent_id=$(echo "$pc_data" | jq -r '.agent_id // empty' 2>/dev/null)
+        namespace_id=$(echo "$pc_data" | jq -r '.namespace_id // empty' 2>/dev/null)
+        machine=$(echo "$pc_data" | jq -r '.machine_name // empty' 2>/dev/null)
+        if [ -z "$machine" ] || [ "$machine" = "null" ]; then
+            machine=$(hostname -s 2>/dev/null || hostname 2>/dev/null || echo "")
+        fi
+        count=$(echo "$pc_data" | jq -r '.count // .pending_count // 0' 2>/dev/null)
+
+        if [ -n "$agent_id" ]; then
+            pc_part="${white}${agent_id}${reset}"
+            if [ -n "$namespace_id" ] && [ "$namespace_id" != "null" ]; then
+                pc_part+="${dim}@${namespace_id}${reset}"
+            fi
+            if [ -n "$machine" ]; then
+                pc_part+=" ${dim}(${machine})${reset}"
+>>>>>>> Stashed changes
             fi
             count=$(echo "$pc_data" | jq -r '.count // .pending_count // 0' 2>/dev/null)
 

package/skills/inbox/SKILL.md

@@ -28,6 +28,8 @@ The user can undo any change in 3 seconds with git. A wrong action costs nothing
 
 **If you genuinely cannot act** (missing file access, need credentials, ambiguous target): say SPECIFICALLY what's blocking you. "I need the path to the docs folder" — not "Understood, I'll do it when ready."
 
+**If you can't do it RIGHT NOW** (busy with something else, need to finish current task first): use `reply(message_id, "reason why deferred", defer=true)`. This keeps the message visible in your inbox so you WILL come back to it. NEVER silently skip a message — you WILL forget it. If you don't act and don't defer, the message is lost forever.
+
 ## On session start or when prompted by a hook
 
 Call inbox(). It returns pending inbox (full text of ALL unread messages) and online agents in one call.
@@ -40,6 +42,10 @@ If there are pending messages, reply to ALL of them IMMEDIATELY. Do not ask the
 2. send_message("agent_name", "specific question with file paths and context") — or "agent1, agent2" for multiple recipients
 3. wait_for_message() — auto-wait for any response, don't ask human whether to wait
 
+ALWAYS send the message regardless of whether the recipient appears online or offline. Messages are stored and delivered when the recipient checks inbox. "Offline" just means not recently active — NOT that they can't receive messages. Never refuse to send.
+
+After sending to an offline agent, tell the human: "Message sent. [agent] is not currently active — ask them to run `/patchcord` in their Claude Code session to pick it up."
+
 ## Receiving (inbox has messages)
 
 1. Read the message