patchcord 0.2.1

package/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "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",
+  "author": {
+    "name": "ppravdin"
+  },
+  "repository": "https://github.com/ppravdin/patchcord",
+  "skills": "./skills/"
+}

package/README.md

@@ -0,0 +1,120 @@
+# Patchcord Plugin for Claude Code
+
+Cross-machine messaging between Claude Code 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 shell startup files
+- 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
+
+```bash
+claude plugin marketplace add /path/to/patchcord
+claude plugin install patchcord@patchcord-marketplace
+```
+
+### 2. Configure the project
+
+Create a project-local `.mcp.json` in the project that should act as a Patchcord agent.
+
+```json
+{
+  "mcpServers": {
+    "patchcord": {
+      "type": "http",
+      "url": "https://patchcord.yourdomain.com/mcp",
+      "headers": {
+        "Authorization": "Bearer <project-token>",
+        "X-Patchcord-Client-Type": "claude_code"
+      }
+    }
+  }
+}
+```
+
+### 3. Start Claude Code in that project
+
+The plugin and statusline scripts read the current project configuration from the session's working tree.
+
+## 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 can stay installed globally, but it must no-op unless the current project is configured.
+
+## Self-hosted server
+
+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.
+
+## What the plugin provides
+
+- Stop hook / turn-end inbox check
+- Patchcord skill for Claude
+- statusline identity display
+
+The MCP tools themselves come from the project's `.mcp.json` server connection, not from the plugin bundle.
+
+## Statusline
+
+By default the statusline shows only Patchcord identity and inbox count. In non-Patchcord projects it outputs nothing.
+
+To also show model, context usage, repo, and git branch:
+
+```bash
+bash scripts/enable-statusline.sh --full
+```
+
+Without `--full`:
+
+```
+ds@default (thick) 2 msg
+```
+
+With `--full`:
+
+```
+Opus 4.6 │ 73% │ myproject (main) │ ds@default (thick) 2 msg
+```
+
+## Verify
+
+In a Patchcord-enabled project:
+
+- statusline should show the Patchcord identity and pending message count
+- `inbox()` should return the expected `namespace_id` and `agent_id`
+
+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

package/bin/patchcord.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, cpSync, readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pluginRoot = join(__dirname, "..");
+const cmd = process.argv[2];
+
+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
+
+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`);
+  process.exit(0);
+}
+
+if (cmd === "plugin-path") {
+  console.log(pluginRoot);
+  process.exit(0);
+}
+
+if (cmd === "init") {
+  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/
+    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
+
+Next: add patchcord MCP server 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:
+
+  {
+    "mcpServers": {
+      "patchcord": {
+        "type": "http",
+        "url": "https://YOUR_SERVER/mcp",
+        "headers": {
+          "Authorization": "Bearer YOUR_TOKEN",
+          "X-Patchcord-Client-Type": "claude_code"
+        }
+      }
+    }
+  }`);
+  }
+  process.exit(0);
+}
+
+console.error(`Unknown command: ${cmd}. Run 'patchcord help' for usage.`);
+process.exit(1);

package/codex/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: patchcord
+description: >
+  Cross-agent messaging across MCP-connected agents. Use when user mentions
+  other agents, patchcord, check inbox, send message, who's online, agent
+  coordination, or when you receive additionalContext about pending patchcord
+  messages.
+---
+
+# patchcord
+
+9 MCP tools: inbox, send_message, reply, unsend_message, wait_for_message, upload_attachment, get_attachment, relay_url, list_recent_debug.
+
+## 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.
+If there are pending messages, reply to ALL of them IMMEDIATELY. Do not ask the human first. Do not explain what you plan to reply. Just reply, then tell the human what you received and what you answered.
+
+## Sending
+
+1. inbox() — check who's online
+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
+
+## Receiving (inbox has messages)
+
+1. Read the question from inbox() result
+2. Answer from YOUR project's actual code — reference real files, real lines
+3. reply(message_id, "detailed answer")
+4. wait_for_message() — stay responsive for follow-ups
+5. If you can't answer, say so. Don't guess about another agent's code.
+
+## File sharing
+
+- upload_attachment(filename, mime_type) → returns presigned upload URL
+- Upload the file directly to that URL via PUT (curl, code sandbox, etc.) — no base64
+- Send the returned `path` to the other agent in your message
+- get_attachment(path_or_url) → fetch and read a file another agent shared
+
+## Deferred messages
+
+reply(message_id, content, defer=true) sends a reply but keeps the original message visible in the inbox as "deferred". Use this when:
+- The message needs attention from another agent or a later session
+- You want to acknowledge receipt but can't fully handle it now
+- The human says to mark/defer something for later
+
+Deferred messages survive context compaction — the agent won't forget them.
+
+## Other tools
+
+- unsend_message(message_id) → unsend a message if recipient hasn't read it yet
+- list_recent_debug(limit) → debug only, shows all recent messages including read ones
+
+## Rules
+
+- Reply IMMEDIATELY. Never ask "want me to reply?" — just reply, then tell the human who wrote and what you answered.
+- Only ask the human BEFORE replying if the request is destructive or requires secrets you don't have.
+- Never ask "want me to wait?" — just wait
+- 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()
+- 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.
+- NEVER use `mcp__claude_ai_*` tools for patchcord. These are web interface OAuth tools with wrong identity. Always use `mcp__patchcord__*` (project-level). If only `claude_ai` tools are visible, diagnose the config: check `.mcp.json`, run `claude mcp get patchcord`, check `~/.claude/settings.json` deny rule.

package/hooks/hooks.json

@@ -0,0 +1,28 @@
+{
+  "description": "Auto-check patchcord inbox when idle. Enables persistent listening without a daemon.",
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/check-inbox.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "Notification": [
+      {
+        "matcher": "idle_prompt",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/check-inbox.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "patchcord",
+  "version": "0.2.1",
+  "description": "Cross-machine agent messaging for Claude Code and Codex",
+  "author": "ppravdin",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ppravdin/patchcord"
+  },
+  "homepage": "https://patchcord.dev",
+  "keywords": ["claude-code", "codex", "mcp", "agent", "messaging", "plugin"],
+  "bin": {
+    "patchcord": "./bin/patchcord.mjs"
+  },
+  "files": [
+    "bin/",
+    ".claude-plugin/",
+    "hooks/",
+    "scripts/",
+    "skills/",
+    "codex/",
+    "README.md"
+  ]
+}

package/scripts/check-inbox.sh

@@ -0,0 +1,78 @@
+#!/bin/bash
+set -euo pipefail
+
+find_patchcord_mcp_json() {
+  local dir="${1:-$PWD}"
+  while [ -n "$dir" ] && [ "$dir" != "/" ]; do
+    if [ -f "$dir/.mcp.json" ]; then
+      printf '%s\n' "$dir/.mcp.json"
+      return 0
+    fi
+    dir=$(dirname "$dir")
+  done
+  return 1
+}
+
+INPUT=$(cat)
+
+# Guard against infinite loops: stop_hook_active is true when Claude
+# is already continuing because a previous Stop hook told it to.
+STOP_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false' 2>/dev/null || echo "false")
+if [ "$STOP_ACTIVE" = "true" ]; then
+  exit 0
+fi
+
+# Resolve config from project-scoped .mcp.json only.
+TOKEN=""
+URL=""
+MCP_JSON=$(find_patchcord_mcp_json "$PWD" || true)
+
+if [ -n "$MCP_JSON" ]; then
+  MCP_URL=$(jq -r '.mcpServers.patchcord.url // empty' "$MCP_JSON" 2>/dev/null || true)
+  MCP_AUTH=$(jq -r '.mcpServers.patchcord.headers.Authorization // empty' "$MCP_JSON" 2>/dev/null || true)
+  if [ -n "$MCP_URL" ] && [ -n "$MCP_AUTH" ]; then
+    URL="${MCP_URL%/mcp}"
+    URL="${URL%/mcp/bearer}"
+    TOKEN="${MCP_AUTH#Bearer }"
+  fi
+fi
+
+if [ -z "$URL" ] || [ -z "$TOKEN" ]; then
+  exit 0  # Not configured, skip silently
+fi
+
+# Check inbox — one lightweight HTTP call
+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")
+
+if [ "$HTTP_CODE" = "401" ] || [ "$HTTP_CODE" = "403" ]; then
+  jq -n '{
+    "decision": "block",
+    "reason": "PATCHCORD AUTH FAILED: token rejected by server (HTTP '"$HTTP_CODE"'). Check your token in .mcp.json — it may be wrong, expired, or not yet registered on the server."
+  }'
+  rm -f /tmp/patchcord_inbox.json
+  exit 0
+fi
+
+if [ "$HTTP_CODE" = "000" ]; then
+  # Server unreachable — skip silently
+  rm -f /tmp/patchcord_inbox.json
+  exit 0
+fi
+
+RESPONSE=$(cat /tmp/patchcord_inbox.json 2>/dev/null || echo '{"count":0}')
+rm -f /tmp/patchcord_inbox.json
+
+COUNT=$(echo "$RESPONSE" | jq -r '.count // .pending_count // 0' 2>/dev/null || echo "0")
+
+if [ "$COUNT" -gt 0 ]; then
+  jq -n --arg count "$COUNT" '{
+    "decision": "block",
+    "reason": ($count + " patchcord message(s) waiting. Call inbox() and reply to all immediately.")
+  }'
+else
+  exit 0
+fi

package/scripts/enable-statusline.sh

@@ -0,0 +1,60 @@
+#!/bin/bash
+# Enable the patchcord statusline in Claude Code user settings.
+# Usage: bash enable-statusline.sh [--full]
+#   --full: also show model, context%, repo (branch)
+set -euo pipefail
+
+EXTRA_ARGS=""
+for arg in "$@"; do
+    [ "$arg" = "--full" ] && EXTRA_ARGS=" --full"
+done
+
+# Find the project root (walk up from cwd to find .mcp.json with patchcord)
+find_project_root() {
+    local dir="${1:-$(pwd)}"
+    while [ -n "$dir" ] && [ "$dir" != "/" ]; do
+        if [ -f "$dir/.mcp.json" ] && jq -e '.mcpServers.patchcord' "$dir/.mcp.json" >/dev/null 2>&1; then
+            printf '%s\n' "$dir"
+            return 0
+        fi
+        dir=$(dirname "$dir")
+    done
+    return 1
+}
+
+PROJECT_ROOT=$(find_project_root || true)
+
+if [ -n "$PROJECT_ROOT" ]; then
+    # Project-level settings (only affects this repo)
+    SETTINGS="$PROJECT_ROOT/.claude/settings.json"
+    mkdir -p "$PROJECT_ROOT/.claude"
+else
+    # Fallback to user-level if no project found
+    SETTINGS="$HOME/.claude/settings.json"
+    mkdir -p "$HOME/.claude"
+fi
+
+# Find the plugin's statusline script
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+STATUSLINE="$SCRIPT_DIR/statusline.sh"
+
+if [ ! -f "$STATUSLINE" ]; then
+    echo "Error: statusline.sh not found at $STATUSLINE" >&2
+    exit 1
+fi
+
+# Read existing settings or start fresh
+if [ -f "$SETTINGS" ]; then
+    CURRENT=$(cat "$SETTINGS")
+else
+    CURRENT='{}'
+fi
+
+# Set statusLine field
+UPDATED=$(echo "$CURRENT" | jq --arg cmd "bash \"$STATUSLINE\"${EXTRA_ARGS}" '.statusLine = {"type": "command", "command": $cmd}')
+echo "$UPDATED" > "$SETTINGS"
+
+echo "Patchcord statusline enabled."
+echo "  Script: $STATUSLINE"
+echo "  Settings: $SETTINGS"
+echo "Restart Claude Code to see the statusline."

package/scripts/statusline.sh

@@ -0,0 +1,185 @@
+#!/bin/bash
+# Patchcord statusline for Claude Code.
+#
+# Default: shows only patchcord identity + inbox count.
+# With --full: also shows model, context%, repo (branch).
+#
+# --full mode model/context/git display based on claude-statusline by Kamran Ahmed
+# https://github.com/kamranahmedse/claude-statusline (MIT)
+#
+# Receives session JSON on stdin, outputs ANSI-formatted text.
+set -f
+
+FULL=false
+for arg in "$@"; do
+    [ "$arg" = "--full" ] && FULL=true
+done
+
+find_patchcord_mcp_json() {
+    local dir="$1"
+    while [ -n "$dir" ] && [ "$dir" != "/" ]; do
+        if [ -f "$dir/.mcp.json" ]; then
+            printf '%s\n' "$dir/.mcp.json"
+            return 0
+        fi
+        dir=$(dirname "$dir")
+    done
+    return 1
+}
+
+input=$(cat)
+
+if [ -z "$input" ]; then
+    exit 0
+fi
+
+# ── Colors ──────────────────────────────────────────────
+blue='\033[38;2;0;153;255m'
+green='\033[38;2;0;175;80m'
+cyan='\033[38;2;86;182;194m'
+red='\033[38;2;255;85;85m'
+yellow='\033[38;2;230;200;0m'
+orange='\033[38;2;255;176;85m'
+white='\033[38;2;220;220;220m'
+dim='\033[2m'
+reset='\033[0m'
+
+sep=" ${dim}│${reset} "
+
+# ── Patchcord: agent identity + inbox ───────────────────
+cwd=$(echo "$input" | jq -r '.cwd // ""')
+[ -z "$cwd" ] || [ "$cwd" = "null" ] && cwd=$(pwd)
+
+pc_token=""
+pc_url=""
+mcp_json=$(find_patchcord_mcp_json "$cwd" || true)
+
+if [ -n "$mcp_json" ]; then
+    mcp_url=$(jq -r '.mcpServers.patchcord.url // empty' "$mcp_json" 2>/dev/null || true)
+    mcp_auth=$(jq -r '.mcpServers.patchcord.headers.Authorization // empty' "$mcp_json" 2>/dev/null || true)
+    if [ -n "$mcp_url" ] && [ -n "$mcp_auth" ]; then
+        pc_url="${mcp_url%/mcp}"
+        pc_token="${mcp_auth#Bearer }"
+    fi
+fi
+
+pc_part=""
+if [ -n "$pc_url" ] && [ -n "$pc_token" ]; then
+    cache_key=$(printf '%s\n%s\n' "$mcp_json" "$pc_url" | sha256sum | awk '{print $1}')
+    cache_file="/tmp/claude/patchcord-statusline-${cache_key}.json"
+    cache_max_age=20
+    mkdir -p /tmp/claude
+
+    needs_refresh=true
+    pc_data=""
+
+    if [ -f "$cache_file" ]; then
+        cache_mtime=$(stat -c %Y "$cache_file" 2>/dev/null || stat -f %m "$cache_file" 2>/dev/null)
+        now=$(date +%s)
+        if [ $(( now - cache_mtime )) -lt $cache_max_age ]; then
+            needs_refresh=false
+            pc_data=$(cat "$cache_file" 2>/dev/null)
+        fi
+    fi
+
+    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" \
+            "${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}'
+            echo "$pc_data" > "$cache_file"
+        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"
+        fi
+        rm -f /tmp/claude/patchcord-sl-resp.json
+    fi
+
+    if [ -n "$pc_data" ]; then
+        auth_error=$(echo "$pc_data" | jq -r '._auth_error // false' 2>/dev/null)
+        if [ "$auth_error" = "true" ]; then
+            pc_part="${red}BAD TOKEN${reset}"
+        else
+            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}"
+                fi
+            fi
+
+            if [ "$count" -gt 0 ] 2>/dev/null; then
+                pc_part+=" ${red}${count} msg${reset}"
+            fi
+        fi
+    fi
+fi
+
+# No patchcord config — output nothing in default mode
+if [ -z "$pc_part" ] && ! $FULL; then
+    exit 0
+fi
+
+# ── Build line ──────────────────────────────────────────
+line=""
+
+if $FULL; then
+    model_name=$(echo "$input" | jq -r '.model.display_name // "Claude"')
+
+    size=$(echo "$input" | jq -r '.context_window.context_window_size // 200000')
+    [ "$size" -eq 0 ] 2>/dev/null && size=200000
+    input_tokens=$(echo "$input" | jq -r '.context_window.current_usage.input_tokens // 0')
+    cache_create=$(echo "$input" | jq -r '.context_window.current_usage.cache_creation_input_tokens // 0')
+    cache_read=$(echo "$input" | jq -r '.context_window.current_usage.cache_read_input_tokens // 0')
+    current=$(( input_tokens + cache_create + cache_read ))
+    if [ "$size" -gt 0 ]; then
+        pct_used=$(( current * 100 / size ))
+    else
+        pct_used=0
+    fi
+    if [ "$pct_used" -ge 90 ]; then pct_color="$red"
+    elif [ "$pct_used" -ge 70 ]; then pct_color="$yellow"
+    elif [ "$pct_used" -ge 50 ]; then pct_color="$orange"
+    else pct_color="$green"
+    fi
+
+    dirname=$(basename "$cwd")
+    git_branch=""
+    git_dirty=""
+    if git -C "$cwd" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+        git_branch=$(git -C "$cwd" symbolic-ref --short HEAD 2>/dev/null)
+        if [ -n "$(git -C "$cwd" status --porcelain 2>/dev/null)" ]; then
+            git_dirty="*"
+        fi
+    fi
+
+    line="${blue}${model_name}${reset}"
+    line+="${sep}"
+    line+="${pct_color}${pct_used}%${reset}"
+    line+="${sep}"
+    line+="${cyan}${dirname}${reset}"
+    if [ -n "$git_branch" ]; then
+        line+=" ${green}(${git_branch}${red}${git_dirty}${green})${reset}"
+    fi
+    if [ -n "$pc_part" ]; then
+        line+="${sep}"
+        line+="${pc_part}"
+    fi
+else
+    line="${pc_part}"
+fi
+
+# ── Output ──────────────────────────────────────────────
+printf "%b" "$line"
+exit 0

package/skills/inbox/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: patchcord
+description: >
+  Cross-agent messaging across MCP-connected agents. Use when user mentions
+  other agents, patchcord, check inbox, send message, who's online, agent
+  coordination, or when you receive additionalContext about pending patchcord
+  messages.
+---
+
+# patchcord
+
+9 MCP tools: inbox, send_message, reply, unsend_message, wait_for_message, upload_attachment, get_attachment, relay_url, list_recent_debug.
+
+## 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.
+If there are pending messages, reply to ALL of them IMMEDIATELY. Do not ask the human first. Do not explain what you plan to reply. Just reply, then tell the human what you received and what you answered.
+
+## Sending
+
+1. inbox() — check who's online
+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
+
+## Receiving (inbox has messages)
+
+1. Read the question from inbox() result
+2. Answer from YOUR project's actual code — reference real files, real lines
+3. reply(message_id, "detailed answer")
+4. wait_for_message() — stay responsive for follow-ups
+5. If you can't answer, say so. Don't guess about another agent's code.
+
+## File sharing
+
+- upload_attachment(filename, mime_type) → returns presigned upload URL
+- Upload the file directly to that URL via PUT (curl, code sandbox, etc.) — no base64
+- Send the returned `path` to the other agent in your message
+- get_attachment(path_or_url) → fetch and read a file another agent shared
+
+## Deferred messages
+
+reply(message_id, content, defer=true) sends a reply but keeps the original message visible in the inbox as "deferred". Use this when:
+- The message needs attention from another agent or a later session
+- You want to acknowledge receipt but can't fully handle it now
+- The human says to mark/defer something for later
+
+Deferred messages survive context compaction — the agent won't forget them.
+
+## Other tools
+
+- unsend_message(message_id) → unsend a message if recipient hasn't read it yet
+- list_recent_debug(limit) → debug only, shows all recent messages including read ones
+
+## Rules
+
+- Reply IMMEDIATELY. Never ask "want me to reply?" — just reply, then tell the human who wrote and what you answered.
+- Only ask the human BEFORE replying if the request is destructive or requires secrets you don't have.
+- Never ask "want me to wait?" — just wait
+- 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()
+- 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.
+- NEVER use `mcp__claude_ai_*` tools for patchcord. These are web interface OAuth tools with wrong identity. Always use `mcp__patchcord__*` (project-level). If only `claude_ai` tools are visible, diagnose the config: check `.mcp.json`, run `claude mcp get patchcord`, check `~/.claude/settings.json` deny rule.

package/skills/wait/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: "patchcord:wait"
+description: >
+  Enter listening mode — wait for incoming patchcord messages. Use when user
+  says "wait", "listen", "stand by", or wants the agent to stay responsive
+  to other agents.
+---
+
+# patchcord:wait
+
+Enter listening mode. Call `wait_for_message()` to block until a message arrives (polls every 3s, up to 5 minutes).
+
+When a message arrives:
+1. Read it — the tool returns from, content, and message_id
+2. Reply immediately: `reply(message_id, "your answer")`
+3. Tell the human who wrote and what you answered
+4. Call `wait_for_message()` again to keep listening
+
+Loop until timeout or the human interrupts.
+
+Do NOT ask the human for permission to reply — just reply, then report.