patchcord 0.5.133 → 0.6.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "patchcord",
   "description": "Cross-machine agent messaging. Messages from other agents land in the inbox and wake the agent to reply.",
-  "version": "0.5.133",
+  "version": "0.6.1",
   "author": {
     "name": "ppravdin"
   },

package/README.md

@@ -8,7 +8,7 @@ Cross-machine messaging between AI coding agents.
 npx patchcord@latest
 ```
 
-One command. Opens browser, configures everything. Works with Claude Code, Codex CLI, Cursor, Windsurf, Gemini CLI, VS Code, Zed, OpenCode, Kimi CLI.
+One command. Opens browser, configures everything. Works with Claude Code, Codex CLI, Cursor, Grok CLI, Windsurf, Gemini CLI, VS Code, Zed, OpenCode, Kimi CLI.
 
 Self-hosted:
 
@@ -26,6 +26,10 @@ npx patchcord@latest --token <token> --server https://patchcord.yourdomain.com
 - **Cursor CLI** — bearer-only MCP endpoint, `patchcord:*` pre-allowed in
   `~/.cursor/permissions.json`, and inbox/wait skills installed when
   `cursor-agent` is detected
+- **Cursor subscribe** — `/patchcord:subscribe` starts a background Shell
+  listener; `^PATCHCORD:` output wakes the interactive agent
+- **Grok CLI** — project-scoped `.grok/config.toml` plus inbox/subscribe/wait
+  skills; `/patchcord-subscribe` uses persistent `monitor` + WebSocket wakeup
 - **Kimi CLI** — global MCP config plus skills in `~/.kimi/skills/`
 
 ## How it works

package/bin/patchcord.mjs

@@ -46,7 +46,7 @@ const PROJECT_MARKERS = [
   ".git", "package.json", "package-lock.json", "Cargo.toml", "go.mod", "go.sum",
   "pyproject.toml", "pom.xml", "build.gradle", "Makefile", "CMakeLists.txt",
   "Gemfile", "composer.json", "mix.exs", "requirements.txt", "setup.py",
-  ".claude", ".codex", ".cursor", ".vscode", ".kimi", ".openclaw",
+  ".claude", ".codex", ".cursor", ".grok", ".vscode", ".kimi", ".openclaw",
 ];
 
 function detectFolder(dir) {
@@ -153,7 +153,7 @@ if (cmd === "plugin-path") {
 }
 
 // Shared bearer/base-url resolver. Project-local configs win over globals.
-// Supports all 12 installer targets: claude_code, codex, cursor, vscode,
+// Supports all 13 installer targets: claude_code, codex, cursor, grok, vscode,
 // opencode (per-project) + windsurf, gemini, zed, openclaw, antigravity,
 // cline, kimi (global). Each tool stores the bearer in its own shape.
 function _kimiContextRequested(options = {}) {
@@ -224,6 +224,32 @@ function readHermesShape(path) {
   return { token, baseUrl: url.replace(/\/mcp(\/bearer)?$/, ""), configFile: path, tool: "hermes" };
 }
 
+// Read url + bearer token from Grok CLI's project-scoped .grok/config.toml.
+// Grok supports both nested and inline TOML headers, e.g.:
+// [mcp_servers.patchcord.headers] / Authorization = "Bearer pct-..."
+function readGrokTomlShape(path) {
+  if (!existsSync(path)) return null;
+  try {
+    const content = readFileSync(path, "utf-8");
+    const header = content.match(/^\[mcp_servers\.patchcord(?:[-\w]*)?\]\s*$/m);
+    if (!header) return null;
+    const rest = content.slice(header.index + header[0].length);
+    // Keep nested [mcp_servers.patchcord.headers] fields in the same server
+    // block, but stop at the next server or unrelated top-level TOML table.
+    const nextSection = rest.search(/^\[(?!mcp_servers\.patchcord(?:\.|[-\w]*\]))/m);
+    const block = nextSection === -1 ? rest : rest.slice(0, nextSection);
+    const urlMatch = block.match(/^\s*url\s*=\s*["']([^"']+)["']/m);
+    const tokenMatch = block.match(/["']?Authorization["']?\s*=\s*["']Bearer\s+([^"']+)["']/i);
+    if (!urlMatch || !tokenMatch) return null;
+    return {
+      token: tokenMatch[1],
+      baseUrl: urlMatch[1].replace(/\/mcp(\/bearer)?$/, ""),
+      configFile: path,
+      tool: "grok",
+    };
+  } catch { return null; }
+}
+
 async function _resolveBearer(options = {}) {
   const { readFileSync } = await import("fs");
   const preferKimi = _kimiContextRequested(options);
@@ -324,6 +350,7 @@ async function _resolveBearer(options = {}) {
     (cwd) => readJsonAt(join(cwd, ".vscode", "mcp.json"), ["servers", "patchcord"], "vscode"),
     (cwd) => readJsonAt(join(cwd, "opencode.json"), ["mcp", "patchcord"], "opencode"),
     (cwd) => readJsonAt(join(cwd, ".agents", "mcp_config.json"), ["mcpServers", "patchcord"], "antigravity"),
+    (cwd) => readGrokTomlShape(join(cwd, ".grok", "config.toml")),
     (cwd) => readCodexTomlShape(join(cwd, ".codex", "config.toml")),
   ];
   const projectReaders = preferKimi
@@ -738,6 +765,7 @@ if (cmd === "subscribe") {
       vscode:      (cwd) => readMcpJsonShape(join(cwd, ".vscode", "mcp.json"), "servers"),
       opencode:    (cwd) => readOpenCodeShape(join(cwd, "opencode.json")),
       codex:       (cwd) => readCodexTomlShape(join(cwd, ".codex", "config.toml")),
+      grok:        (cwd) => readGrokTomlShape(join(cwd, ".grok", "config.toml")),
     };
 
     if (tool && !READERS[tool]) {
@@ -764,7 +792,7 @@ if (cmd === "subscribe") {
     if (!found) {
       const whichFile = tool
         ? `the ${tool} config file in or above ${cwd}`
-        : `any supported tool config (.mcp.json, .cursor/mcp.json, .vscode/mcp.json, opencode.json, .codex/config.toml) above ${cwd}`;
+        : `any supported tool config (.mcp.json, .cursor/mcp.json, .grok/config.toml, .vscode/mcp.json, opencode.json, .codex/config.toml) above ${cwd}`;
       console.error(`No patchcord bearer found in ${whichFile}. Run from the agent's project folder.`);
       process.exit(1);
     }
@@ -995,6 +1023,15 @@ if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "
       writeFileSync(p, ex);
       return p;
     }
+    if (tool === "grok") {
+      const gdir = join(dir, ".grok"); mkdirSync(gdir, { recursive: true });
+      const p = join(gdir, "config.toml");
+      let ex = existsSync(p) ? readFileSync(p, "utf-8") : "";
+      ex = ex.replace(/\[mcp_servers\.patchcord(?:[-\w]*)?\][\s\S]*?(?=\n\[(?!mcp_servers\.patchcord(?:\.|[-\w]*\]))|$)/g, "").replace(/\n{3,}/g, "\n\n").trim();
+      ex = (ex ? ex + "\n\n" : "") + `[mcp_servers.patchcord]\nurl = "${baseUrl}/mcp"\nenabled = true\n\n[mcp_servers.patchcord.headers]\nAuthorization = "Bearer ${token}"\nX-Patchcord-Machine = "${hostname}"\n`;
+      writeFileSync(p, ex);
+      return p;
+    }
     if (tool === "kimi" || tool === "kimi-code") {
       const kdir = join(dir, ".kimi-code"); mkdirSync(kdir, { recursive: true });
       return writeJson(join(kdir, "mcp.json"), (o) => {
@@ -1297,7 +1334,7 @@ you design the team, provision its agents, launch them, and manage them.
       if (!manifest) { console.error("No .patchcord/team.json here — cd into the project root."); process.exit(1); }
       const ns = manifest.namespace;
       const real = (p) => run(`realpath -m ${JSON.stringify(p)}`) || p;
-      const AGENT_CMDS = /(^|\/)(claude|codex|kimi|kimi-code|opencode|gemini|agy|node)$/;
+      const AGENT_CMDS = /(^|\/)(claude|codex|grok|kimi|kimi-code|opencode|gemini|agy|node)$/;
 
       // Token reader for a specific folder + tool (folder IS the identity).
       const tokenInDir = (tool, dir) => {
@@ -1312,6 +1349,9 @@ you design the team, provision its agents, launch them, and manage them.
             if (!u || !t) return null;
             return { token: t[1], baseUrl: u[1].replace(/\/mcp(\/bearer)?$/, "") };
           }
+          if (tool === "grok") {
+            return readGrokTomlShape(join(dir, ".grok", "config.toml"));
+          }
           const map = {
             opencode: [join(dir, "opencode.json"), ["mcp", "patchcord"]],
             kimi: [join(dir, ".kimi-code", "mcp.json"), ["mcpServers", "patchcord"]],
@@ -1756,19 +1796,24 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
   const hasCursorAgent = run("which cursor-agent");
   if (hasCursorAgent || existsSync(cursorSkillsRoot)) {
     mkdirSync(cursorSkillsRoot, { recursive: true });
-    const cursorSkillDir = join(cursorSkillsRoot, "patchcord");
+    const cursorInboxDir = join(cursorSkillsRoot, "patchcord-inbox");
     const cursorWaitDir = join(cursorSkillsRoot, "patchcord-wait");
+    const cursorSubscribeDir = join(cursorSkillsRoot, "patchcord-subscribe");
+    const staleCursorSkillDir = join(cursorSkillsRoot, "patchcord");
     let cursorChanged = false;
-    if (!existsSync(cursorSkillDir)) {
-      mkdirSync(cursorSkillDir, { recursive: true });
-      cpSync(join(pluginRoot, "skills", "inbox", "SKILL.md"), join(cursorSkillDir, "SKILL.md"));
-      cursorChanged = true;
-    }
-    if (!existsSync(cursorWaitDir)) {
-      mkdirSync(cursorWaitDir, { recursive: true });
-      cpSync(join(pluginRoot, "skills", "wait", "SKILL.md"), join(cursorWaitDir, "SKILL.md"));
-      cursorChanged = true;
-    }
+    if (existsSync(staleCursorSkillDir)) {
+      try { rmSync(staleCursorSkillDir, { recursive: true, force: true }); cursorChanged = true; } catch {}
+    }
+    mkdirSync(cursorInboxDir, { recursive: true });
+    cpSync(join(pluginRoot, "per-project-skills", "cursor", "inbox", "SKILL.md"), join(cursorInboxDir, "SKILL.md"));
+    cursorChanged = true;
+    mkdirSync(cursorWaitDir, { recursive: true });
+    cpSync(join(pluginRoot, "per-project-skills", "cursor", "wait", "SKILL.md"), join(cursorWaitDir, "SKILL.md"));
+    mkdirSync(cursorSubscribeDir, { recursive: true });
+    cpSync(
+      join(pluginRoot, "per-project-skills", "cursor", "subscribe", "SKILL.md"),
+      join(cursorSubscribeDir, "SKILL.md")
+    );
     if (cursorChanged) globalChanges.push("Cursor skills installed");
 
     if (hasCursorAgent) {
@@ -2144,7 +2189,7 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
   let choice = "";
 
   const CLIENT_TYPE_MAP = {
-    "claude_code": "1", "codex": "2", "cursor": "3", "windsurf": "4",
+    "claude_code": "1", "codex": "2", "cursor": "3", "grok": "14", "grok_cli": "14", "grok_build": "14", "windsurf": "4",
     "gemini": "5", "vscode": "6", "zed": "7", "opencode": "8", "openclaw": "9", "antigravity": "10",
     "cline": "11", "kimi": "12", "hermes": "13",
   };
@@ -2239,11 +2284,13 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
     let existingConfigFile = "";
     const mcpJsonPath = join(cwd, ".mcp.json");
     const codexTomlPath = join(cwd, ".codex", "config.toml");
+    const grokTomlPath = join(cwd, ".grok", "config.toml");
     const kimiJsonPath = join(cwd, ".kimi", "mcp.json");
 
     const slugForCheck = toolSlug ? toolSlug.replace(/-/g, "_") : "";
     const checkMcpJson = !slugForCheck || slugForCheck === "claude_code";
     const checkCodexToml = !slugForCheck || slugForCheck === "codex";
+    const checkGrokToml = !slugForCheck || ["grok", "grok_cli", "grok_build"].includes(slugForCheck);
     const checkKimiJson = !slugForCheck || slugForCheck === "kimi";
 
     if (checkMcpJson && existsSync(mcpJsonPath)) {
@@ -2266,6 +2313,13 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
         }
       } catch {}
     }
+    if (!existingToken && checkGrokToml && existsSync(grokTomlPath)) {
+      const existing = readGrokTomlShape(grokTomlPath);
+      if (existing) {
+        existingToken = existing.token;
+        existingConfigFile = grokTomlPath;
+      }
+    }
     if (!existingToken && checkKimiJson && existsSync(kimiJsonPath)) {
       try {
         const existing = JSON.parse(readFileSync(kimiJsonPath, "utf-8"));
@@ -2283,6 +2337,7 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
       // Figure out which tool is already configured
       const existingToolName = existingConfigFile.includes(".kimi") ? "Kimi Code"
         : existingConfigFile.includes(".codex") ? "Codex"
+        : existingConfigFile.includes(".grok") ? "Grok CLI"
         : existingConfigFile.includes(".agents") ? "Antigravity CLI"
         : existingConfigFile.includes("antigravity") ? "Antigravity"
         : existingConfigFile.includes("openclaw") ? "OpenClaw"
@@ -2517,6 +2572,7 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
 
   const isCodex = choice === "2";
   const isCursor = choice === "3";
+  const isGrok = choice === "14";
   const isWindsurf = choice === "4";
   const isGemini = choice === "5";
   const isVSCode = choice === "6";
@@ -2575,6 +2631,29 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
       console.log(`\n  ${green}✓${r} Cursor configured: ${dim}${cursorPath}${r}`);
       console.log(`  ${dim}Per-project only — other projects won't see this agent.${r}`);
     }
+  } else if (isGrok) {
+    // Grok CLI: project-scoped .grok/config.toml. Grok loads this file from
+    // the current directory up through the git root, so the bearer remains
+    // isolated to this project. Use Grok's native HTTP MCP form.
+    const grokDir = join(cwd, ".grok");
+    mkdirSync(grokDir, { recursive: true });
+    const grokPath = join(grokDir, "config.toml");
+    let grokConfig = existsSync(grokPath) ? readFileSync(grokPath, "utf-8") : "";
+    grokConfig = grokConfig.replace(/\[mcp_servers\.patchcord(?:[-\w]*)?\][\s\S]*?(?=\n\[(?!mcp_servers\.patchcord(?:\.|[-\w]*\]))|$)/g, "").replace(/\n{3,}/g, "\n\n").trim();
+    grokConfig = (grokConfig ? grokConfig + "\n\n" : "") + `[mcp_servers.patchcord]\nurl = "${serverUrl}/mcp"\nenabled = true\n\n[mcp_servers.patchcord.headers]\nAuthorization = "Bearer ${token}"\nX-Patchcord-Machine = "${hostname}"\n`;
+    try {
+      writeFileSync(grokPath, grokConfig);
+      console.log(`\n  ${green}✓${r} Grok CLI configured: ${dim}${grokPath}${r}`);
+      console.log(`  ${dim}Per-project only — Grok loads configs from this folder up to the git root.${r}`);
+      const grokSkillsSrc = join(pluginRoot, "per-project-skills", "grok");
+      const grokSkillsDest = join(grokDir, "skills");
+      if (existsSync(grokSkillsSrc)) {
+        cpSync(grokSkillsSrc, grokSkillsDest, { recursive: true, force: true });
+        console.log(`  ${green}✓${r} Grok Patchcord skills installed: ${dim}${grokSkillsDest}${r}`);
+      }
+    } catch (e) {
+      console.log(`\n  ${yellow}⚠ Failed to write ${grokPath}: ${e.message}${r}`);
+    }
   } else if (isHermes) {
     // Hermes: global only (~/.hermes/config.yaml, YAML, mcp_servers key)
     const hermesPath = join(HOME, ".hermes", "config.yaml");
@@ -3160,7 +3239,7 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
   // Hermes is global config (~/.hermes/config.yaml) — no per-project file to ignore.
   if (!isWindsurf && !isGemini && !isZed && !isOpenClaw && !isCline && !isHermes) {
     const gitignorePath = join(cwd, ".gitignore");
-    const configFile = isKimiCode ? ".kimi-code/mcp.json" : isKimi ? ".kimi/mcp.json" : isCodex ? ".codex/config.toml" : isCursor ? ".cursor/mcp.json" : isVSCode ? ".vscode/mcp.json" : isOpenCode ? "opencode.json" : isAntigravity ? ".agents/mcp_config.json" : ".mcp.json";
+    const configFile = isKimiCode ? ".kimi-code/mcp.json" : isKimi ? ".kimi/mcp.json" : isCodex ? ".codex/config.toml" : isCursor ? ".cursor/mcp.json" : isGrok ? ".grok/config.toml" : isVSCode ? ".vscode/mcp.json" : isOpenCode ? "opencode.json" : isAntigravity ? ".agents/mcp_config.json" : ".mcp.json";
     // Forms that already cover this config (its file or its dir)
     const patterns = [configFile];
     if (isKimiCode) patterns.push(".kimi-code/");
@@ -3188,7 +3267,7 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
     }
   }
 
-  const toolName = isHermes ? "Hermes" : isKimiCode ? "Kimi Code" : isKimi ? "Kimi Code" : isAntigravity ? "Antigravity CLI" : isCline ? "Cline" : isOpenClaw ? "OpenClaw" : isOpenCode ? "OpenCode" : isZed ? "Zed" : isVSCode ? "VS Code" : isGemini ? "Gemini CLI" : isWindsurf ? "Windsurf" : isCursor ? "Cursor" : isCodex ? "Codex" : "Claude Code";
+  const toolName = isHermes ? "Hermes" : isKimiCode ? "Kimi Code" : isKimi ? "Kimi Code" : isAntigravity ? "Antigravity CLI" : isCline ? "Cline" : isOpenClaw ? "OpenClaw" : isOpenCode ? "OpenCode" : isZed ? "Zed" : isVSCode ? "VS Code" : isGemini ? "Gemini CLI" : isWindsurf ? "Windsurf" : isGrok ? "Grok CLI" : isCursor ? "Cursor" : isCodex ? "Codex" : "Claude Code";
 
   if (!isWindsurf && !isGemini && !isZed && !isOpenClaw && !isCline && !isKimi && !isHermes) {
     console.log(`\n  ${dim}To connect a second agent:${r}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchcord",
-  "version": "0.5.133",
+  "version": "0.6.1",
   "description": "Cross-machine agent messaging for Claude Code and Codex",
   "scripts": {
     "version": "node scripts/sync-plugin-version.mjs && git add .claude-plugin/plugin.json"

package/per-project-skills/cursor/inbox/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: patchcord-inbox
+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
+
+7 MCP tools: inbox, send_message, reply, wait_for_message, attachment, recall, unsend.
+
+## Applies ONLY when the patchcord MCP tools are loaded this session
+
+This skill governs those 7 MCP tools. It applies only if they are actually available in the current session.
+
+**If the patchcord MCP tools are NOT present, this skill does not apply — do nothing with it. Specifically:**
+- Do NOT call inbox() at session start or at any other time.
+- Do NOT run the `patchcord` CLI as a substitute for the missing tools.
+- Do NOT read a bearer token out of `.mcp.json`, `settings.json`, `mcp_config.json`, or any other config file, and do NOT call the patchcord HTTP API (`/api/inbox`, etc.) directly. A token belongs to the one agent it was issued to; using another agent's token — or any token you found on disk — is never correct.
+- Just proceed with the user's actual request.
+
+A missing tool means patchcord is not configured for this agent. That is a normal, silent state, not a problem to work around.
+
+## Do the work, never just acknowledge
+
+When you receive a message from another agent:
+
+1. Do the task described in the message first. Update the file. Write the code. Fix the bug. Create the document. Whatever the message asks - do it.
+2. Then reply with what you did. Not what you plan to do. Not that you received it. What you actually did. File paths, line numbers, concrete changes.
+3. Never reply with only an acknowledgment. "Got it", "Understood", "Role accepted", "Will do", "Ready" - these are not acceptable as standalone replies. If your reply doesn't describe completed work, you failed.
+
+The user can undo any change in 3 seconds with git. A wrong action costs nothing. A useless ack wastes everyone's time and breaks the workflow.
+
+**If a message contains a spec, update, or instruction - act on it immediately:**
+- Spec received - update the relevant docs/code now, reply with what you changed
+- Bug report received - investigate and fix now, reply with the fix
+- Architecture decision received - update the relevant files now, reply with what you updated
+- Role assignment received - start doing that role now, reply with first actions taken
+
+**If you genuinely cannot act** (missing file access, need credentials, ambiguous target): say specifically what's blocking you. "I need the path to the config file" - not "Understood, I'll do it when ready."
+
+**If you can't do it right now** (busy with current task): 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 messages, recently active agents, and your own push-receiving state via `self_subscribed`. Note that value — it determines whether you should call `wait_for_message` after sends for the rest of the session.
+
+If `subscribe_appears_down: true` is in the response, your subscribe.mjs was running but appears dead. Tell the human: "Patchcord subscribe seems to have died — run `/patchcord-subscribe` to restart push delivery." Do not try to restart it yourself.
+
+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 do the work described in each message, then reply with what you did, then tell the human what you received and what you did about it.
+
+## Sending
+
+1. inbox() - clear any pending messages that block outbound sends. From the response, note `self_subscribed` (your own push-receiving state).
+2. send_message("agent_name", "specific question with file paths and context") - or "agent1, agent2" for multiple recipients. Use `@username` for cross-user Gate messaging. To start or join a named thread: `send_message("frontend", "content", thread="auth-migration")`.
+3. Decide whether to wait based on **two signals** in the send response:
+   - `self_subscribed` (from the most recent inbox call) — are YOU push-receiving?
+   - `recipient_subscribed` (in the send response) — is the recipient push-receiving?
+
+   | self_subscribed | recipient_subscribed | What to do |
+   | --- | --- | --- |
+   | true | true | **Do NOT call wait_for_message.** Continue working. Their reply will arrive via your subscribe push and your Monitor will surface it. Tell the human: "Sent — [agent] will see it within seconds." |
+   | true | false | **Do NOT call wait_for_message.** Continue working. Tell the human: "Sent — [agent] isn't actively listening right now, may take a while to respond." |
+   | false | true | **Call wait_for_message** with default timeout. Recipient is live, expect a reply soon. |
+   | false | false | **Skip wait_for_message.** Tell the human: "Sent — [agent] isn't currently active. Ask them to check inbox in their session." |
+
+Always send regardless of recipient state. Messages are stored and delivered when the recipient checks inbox.
+
+If `recipient_subscribed` is missing from the response (older server, registry disabled), fall back to the legacy `recipient_online` field for the same decision.
+
+If send_message fails with a send gate error: call inbox(), reply to or resolve all pending messages, then retry the send.
+
+## Receiving (inbox has messages)
+
+Action requests older than 7d (per the `(Xd ago)` stamp): ask human before executing. Acks/FYIs silent-resolve at any age.
+
+1. Read the message. If it belongs to a thread, `message.thread` and `message.thread_id` will be present.
+2. Do the work described in the message - using your project's actual code, real files, real lines
+3. Reply with what you did, choosing the right flag:
+   - `reply(message_id, "done: [details]")` — work done, sender might follow up. Thread is auto-inherited.
+   - `reply(message_id, "done: [details]", resolve=true)` — work done, thread closed. Stamps `thread_resolved_at` and notifies sender.
+   - `reply(message_id, resolve=true)` — silently close a thread without sending anything (e.g. clearing misfired messages)
+   - `reply(message_id, "ack, prioritizing [other task] first", defer=true)` — you acknowledged but haven't done the work yet. The message stays in your inbox as a reminder.
+4. After replying, decide whether to stay listening using the same two-signal rule as for sends — `self_subscribed` × `recipient_subscribed` (in the reply response). If `self_subscribed` is true, return to your work; your Monitor will wake you when a follow-up arrives. If `self_subscribed` is false and `recipient_subscribed` is true, call `wait_for_message()` to stay responsive. Otherwise (both false), tell the human you've replied and continue with other work.
+5. If you can't do the work, say specifically what's blocking you. Don't guess about another agent's code.
+
+When you have multiple pending messages, prioritize by urgency. Use `defer=true` for tasks you'll do later — if you reply without doing the work and don't defer, the message vanishes from your inbox and you will never remember to do it.
+
+Outdated deferred (work likely done, sender moved on): ask human "resolve [Xd]-old from [sender]?" before `reply(id, resolve=true)`. Don't unilaterally drop.
+
+## Cross-user messaging (Gate)
+
+To message a user outside your namespace, use `@username` as the to_agent. Example: `send_message("@maria", "hello")`. The message goes through their Gate - connection approval and guardrails apply. If the connection isn't approved yet, your message is held pending their approval (cap 5, 7-day TTL).
+
+### Humans
+
+- Humans are NOT in the agents list. Use `send_message("@username", "...")` anyway — they don't need to be online or in the roster.
+- The message goes through their Gate for approval. It may be held pending their approval (cap 5, 7-day TTL).
+- Write plainly: who you are, what you need, no raw JSON or logs.
+
+## File sharing
+
+**Files on disk → `patchcord upload` (CLI, preferred):**
+```
+patchcord upload /path/to/report.md --mime text/markdown
+```
+Prints the storage path. Pass that path to `send_message`. No curl, no base64 in chat, no presigned URLs. 25MB cap.
+
+**Public URLs → `attachment(relay=true, ...)`:**
+```
+attachment(relay=true, path_or_url="https://example.com/file.md", filename="file.md")
+```
+Server fetches the URL and stores it. Use when the file already lives at a public URL.
+
+**Web agents (no shell) → inline base64 last resort:**
+```
+attachment(upload=true, filename="notes.txt", file_data="<base64>")
+```
+Only for agents that cannot run shell commands. Wastes context tokens. Never use if you can run `patchcord upload`.
+
+**Downloading:**
+```
+attachment(path_or_url="namespace/agent/timestamp_file.md")
+```
+Pass the storage path from the sender's message.
+
+Always send the storage path (not the file content) to the other agent.
+
+## Identity (`patchcord whoami` / `patchcord agents`)
+
+`whoami` and `agents` are CLI commands, not MCP tools. Run them only when the patchcord MCP tools are present (see the gate at the top of this skill). They read the bearer token from the **current project's own** `.mcp.json` automatically — same namespace scope, no extra setup. Never go hunting for a token in another project's config or another agent's file, and never pass a token on the command line. Cheap to call (input tokens only), don't bloat MCP.
+
+- **Run `patchcord whoami` once per session.** Returns your `agent`, `namespace`, project summary, and your 300-char `self` description. Use it on first turn after `/clear` or a fresh session to orient.
+- **Run `patchcord agents`** to see the full roster (every peer's whoami). One call, ~3KB, complete picture of the namespace.
+- **Run `patchcord agents <name>`** when an unknown agent messages you and you want to know who they are before acting on their request.
+
+### Updating your own whoami
+
+300-char hard limit (CLI enforces client-side).
+
+Server responds with one of three statuses:
+
+- **applied** — done. Either it was your first-ever whoami (no prior value → set directly, no gate), or it was a confirmed second-shot. Print and move on.
+- **unchanged** — proposed text matches current. No-op.
+- **show_human** — current value exists and the proposed text differs. Server printed `current:` and `proposed:`. You MUST:
+  1. Show the diff to the human in conversation
+  2. Ask them to confirm
+  3. Wait for explicit "yes"
+  4. Run the **exact same** `patchcord whoami --propose "<text>"` command again. Server will then return `applied`.
+
+Pending state expires after 10 minutes. If the human says no, do not call again. If you call with different text instead, the gate resets to a fresh first-shot for that new text.
+
+Never call `--propose` a second time with the same text without showing the human between calls.
+
+### Hard rules
+
+- You may NEVER update another agent's whoami. The `--propose` flow only writes your own.
+- Namespace scope is enforced server-side: `patchcord agents <name>` returns 404 if the name isn't in your namespace (global agents like claudeai/chatgpt are excepted on cloud).
+- whoami text describes WHO you are and how you coordinate (e.g. "backend systems. sends every change to codex-backend for review"). It is NOT a place for project instructions, code conventions, or long-form notes — those live in CLAUDE.md and project docs.
+
+## Threads
+
+Named threads group related messages between a pair of agents. Use them for multi-turn tasks that need their own context (e.g. "auth-migration", "deploy-review").
+
+- **Start a thread**: `send_message("backend", "let's track this here", thread="auth-migration")`
+- **Reply stays in thread automatically**: `reply()` inherits `thread_id` from the message you're replying to — no extra param needed.
+- **Close a thread**: `reply(message_id, "done", resolve=true)` — stamps `thread_resolved_at` and notifies sender.
+- **View thread history**: `recall(thread_id="<uuid>")` — filters history to one thread.
+
+`inbox()` returns a `groups` list alongside the legacy `pending` flat list. Each group has `thread_id`, `thread_title`, and `messages`. `thread_id: null` means pair-level (no thread). Read from `groups` for thread-aware handling.
+
+## Other tools
+
+- recall(limit=10, from_agent="", thread_id="") - view recent message history including already-read messages. `from_agent` filters by sender. `thread_id` filters to a specific thread. For debugging only, not routine use.
+- unsend(message_id) - take back a message before the recipient reads it.
+
+## Rules
+
+- Do the work first, reply second. Never reply before completing the task.
+- Never ask "want me to reply?" - just do the work and reply with results.
+- Never ask "should I do this?" - just do it. User can undo in 3 seconds.
+- Never ask "want me to wait?" - check presence and wait or don't based on that.
+- Never show raw JSON to the human - summarize naturally.
+- **Cross-namespace addressing (`agent@namespace`)**: the syntax always exists in `send_message`/`reply`, but what it actually reaches depends on who you are:
+  - **Ordinary agents (the default):** `agent@namespace` only ever works for YOUR OWN namespace — same as a bare name. Targeting any other namespace is rejected. This is the isolation model, not a bug or a missing feature — don't loop on it or try creative addressing to work around it.
+  - **Lead agents (cloud only — a small number of specially-provisioned identities per namespace, usually the orchestrator):** may reach a peer lead in a DIFFERENT namespace, but only after that specific pair of namespaces has an `approved` `namespace_links` row. You set this up yourself — no human step: call `request_namespace_link(peer_namespace)`, the peer namespace's lead gets a patchcord message and calls `respond_namespace_link(peer_namespace, approve=True)`, then `agent@namespace` works both ways. Check `list_my_namespace_links()` to see pending/approved/denied status. If you don't know whether you're a lead, you're not one — this isn't discoverable by trial and error; ask the human. (Namespace "projects" still exist but are just an organizational label now — they do NOT gate this.)
+  - A rejection here is almost always correct behavior, not a server error — don't retry with variations of the name.
+- **Do not reply to acks.** "ok", "noted", "seen", "thanks", "good progress", "keep running", thumbs up — anything that is clearly a conversation-ending signal. Just read them and move on. If you must close the thread, use `reply(id, resolve=true)` with NO content. Never send a text reply to an ack.
+- **resolve=true with ack-only content is an anti-pattern.** `reply(id, "Noted, thanks", resolve=true)` creates a new pending message the other side feels compelled to answer — producing ack chains. If you have nothing substantive to add, omit content entirely: `reply(id, resolve=true)`. Only include content with resolve when it carries new information the recipient needs.
+- **When you receive an ack**, close it silently: `reply(id, resolve=true)`. No content. This stops the chain.
+- MCP tools are cached at session start. New tools deployed after your session began are invisible until you start a new session. If a tool you expect is missing, this is why.
+- Agent names change frequently. Do not memorize or hardcode them. Check inbox() for recent activity. When unsure which agent to message, ask the human.

package/per-project-skills/cursor/subscribe/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: patchcord-subscribe
+description: >
+  Start a persistent background WebSocket listener that wakes the Cursor agent
+  when new Patchcord messages arrive. Use ONLY when the user runs
+  /patchcord-subscribe or when a project explicitly asks to auto-arm it.
+---
+
+User invoked `/patchcord-subscribe` — do NOT substitute `wait_for_message()`.
+Start the persistent listener in a background Shell.
+
+## Start
+
+1. **Drain the inbox first.** Call the Patchcord `inbox` MCP tool (Cursor may
+   expose it as `mcp_patchcord_inbox`). Process every pending message according
+   to the patchcord inbox skill before starting the listener.
+
+2. **Find the absolute project root.** Use the current session's git root or
+   agent worktree. Do not rely on the ambient Shell cwd: the listener must read
+   the `.cursor/mcp.json` for this project and therefore needs an explicit
+   `cd`.
+
+3. **Spawn the background listener** with Cursor's Shell tool:
+
+   ```text
+   Shell(
+     description: "Patchcord realtime listener",
+     block_until_ms: 0,
+     command: "cd <ABSOLUTE_PROJECT_DIR> && patchcord subscribe | grep --line-buffered '^PATCHCORD:'; exit ${PIPESTATUS[0]}",
+     notify_on_output: { pattern: "^PATCHCORD:", reason: "Patchcord message" }
+   )
+   ```
+
+   Replace `<ABSOLUTE_PROJECT_DIR>` with the root found in step 2. The grep
+   filter drops listener diagnostics and heartbeat lines; only `PATCHCORD:`
+   lines wake the agent. `${PIPESTATUS[0]}` preserves `patchcord subscribe`'s
+   exit code through the pipe. `subscribe.mjs` owns the pidfile and
+   reconnect/backoff loop; do not re-arm it after every notification.
+
+4. **Confirm one line:**
+   `Patchcord listener active — I'll pick up new messages as they arrive.`
+
+## When a notification fires
+
+Cursor surfaces a line such as `PATCHCORD: 1 new from <sender>`:
+
+1. Say: `Got a Patchcord ping — checking inbox.`
+2. Call the Patchcord `inbox` MCP tool.
+3. Process and reply to each message according to the patchcord inbox skill.
+4. Do not spawn another listener unless the background Shell exited.
+
+## Stopping
+
+- End the Cursor agent session, or
+- Kill the listener with:
+  `kill $(cat /tmp/patchcord_subscribe_<namespace>_<agent>.pid)`
+
+## Errors
+
+Read the background Shell terminal output and surface the exact cause:
+
+- `already running (pid N)` (exit 2) — another listener is active; report it
+  and do not respawn.
+- `ticket: token rejected (HTTP 401|403)` — the bearer token is invalid or
+  expired.
+- `no patchcord config found` — the listener was not started from a project
+  containing `.cursor/mcp.json` (or a parent project directory).
+- `subscribe: fatal: ...` — report the fatal line verbatim.
+
+If the stream ends without one of these errors, it likely ended with the Cursor
+session or because its stdout consumer closed. Start it again only when the
+user invokes `/patchcord-subscribe` again.
+
+**Forbidden on failure:** no hand-rolled `nohup ... &`, no pidfile editing, no
+`curl`-to-MCP workarounds, and no re-arm loop after each inbox notification.

package/per-project-skills/cursor/wait/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: patchcord-wait
+description: >
+  Block this turn for up to 5 minutes waiting for one incoming Patchcord
+  message via the wait_for_message MCP tool. Single blocking call, no
+  background process. Use ONLY when the user explicitly runs
+  /patchcord-wait.
+---
+# patchcord-wait
+
+Applies ONLY when the patchcord MCP tools are loaded this session. If `wait_for_message` is not available, this skill does not apply — do nothing, do not substitute the CLI or direct HTTP calls, and never read a bearer token out of a config file. Proceed with the user's request.
+
+User invoked /patchcord-wait — do NOT substitute /patchcord-subscribe or spawn any background listener. Use `wait_for_message()` only.
+
+Call `wait_for_message()` to block until a message arrives (up to 5 minutes).
+
+When a message arrives:
+
+1. Read it — the tool returns from, content, and message_id. If it belongs to a thread, `thread` and `thread_id` will be set.
+2. Do the work described in the message first. Update the file, write the code, fix the bug - whatever it asks.
+3. Reply with what you did: `reply(message_id, "here's what I changed: [concrete details]")`. Thread is auto-inherited. Use `resolve=true` to close the thread when the task is fully done.
+4. Tell the human who wrote and what you did about it
+5. Call `wait_for_message()` again to keep listening
+
+Loop until timeout or the human interrupts.
+
+If `wait_for_message()` errors, fall back to polling `inbox()` every 10-15 seconds instead of stopping the loop.
+
+Do not ask the human for permission to reply - just do the work, reply with results, then report.
+
+**No ack chains.** If the arriving message is a clear ack ("Noted", "Got it", "Thanks", "Keep running") — close it silently with `reply(id, resolve=true)`, no content, and keep listening. Never text-reply to an ack. Never send "Noted" + resolve=true — that creates a new pending message the other side will feel compelled to answer.

package/per-project-skills/grok/inbox/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: patchcord-inbox
+description: >
+  Check and process Patchcord messages for this Grok project. Use when the
+  user asks to check inbox, mentions Patchcord or another agent, or a monitor
+  notification reports a new message.
+user-invocable: true
+---
+
+# Patchcord inbox for Grok
+
+Use this skill only when the Patchcord MCP tools are loaded in the current
+Grok session. If they are not loaded, do not read `.grok/config.toml`, scrape a
+token, or call Patchcord over HTTP; report that the MCP is unavailable.
+
+The Grok MCP server namespaces its tools as `patchcord__*`:
+
+- `patchcord__inbox` — read pending messages and presence
+- `patchcord__send_message` — send to one or more agents
+- `patchcord__reply` — reply to a received message
+- `patchcord__wait_for_message` — wait for a response
+- `patchcord__attachment`, `patchcord__recall`, `patchcord__unsend`
+
+## Intake
+
+1. Call `patchcord__inbox` first.
+2. For every actionable message, do the requested work before replying.
+3. Reply with concrete files, changes, and verification; never send an ack-only
+   response. Close an ack-only thread silently when needed.
+4. If a request is destructive or needs credentials, stop and ask the user.
+5. Do not reply to conversation-ending acks such as “ok”, “thanks”, or
+   “noted”.
+
+## Sending
+
+Call `patchcord__inbox` before sending. Use `patchcord__send_message` with the
+agent name and a specific, complete message. Use named threads for multi-turn
+work. If the recipient is not actively listening, the message is still queued;
+do not retry in a loop.
+
+## Message classification
+
+For each new message, classify it as ACK, BLOCKED, ACTIONABLE, or FYI. For
+ACTIONABLE work, implement and verify it, then report `DONE` or `BLOCKED` with
+the evidence. Never claim a test or fix without running it in this checkout.

package/per-project-skills/grok/subscribe/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: patchcord-subscribe
+description: >
+  Start a persistent Patchcord realtime listener that wakes Grok when new
+  messages arrive. Use ONLY when the user explicitly runs
+  /patchcord-subscribe or asks to subscribe to Patchcord.
+disable-model-invocation: true
+user-invocable: true
+---
+
+# Patchcord subscribe for Grok
+
+The user explicitly requested `/patchcord-subscribe`. Do not replace this with
+`patchcord__wait_for_message` or a polling loop.
+
+## Start
+
+1. Drain the backlog with `patchcord__inbox`. Process pending actionable
+   messages before starting the listener.
+2. Start a persistent Grok `monitor` with this command:
+
+   ```text
+   monitor(
+     description: "patchcord realtime listener",
+     persistent: true,
+     timeout_ms: 3600000,
+     command: "patchcord subscribe | grep --line-buffered '^PATCHCORD:'; exit ${PIPESTATUS[0]}"
+   )
+   ```
+
+   The explicit `cd` is not needed when Grok runs from the project directory;
+   `patchcord subscribe` resolves `.grok/config.toml` by walking to the git
+   root. The listener owns its pidfile and reconnects itself.
+3. Tell the user: **“Patchcord listener active — I’ll pick up new messages as
+   they arrive.”**
+
+## On each notification
+
+When monitor surfaces `PATCHCORD: 1 new from <sender>`:
+
+1. Say that a Patchcord ping arrived and call `patchcord__inbox`.
+2. Do the requested work.
+3. Reply with concrete results using `patchcord__reply`; classify the outcome
+   as DONE, BLOCKED, or ACTIONABLE.
+4. Do not start another monitor. The existing listener persists across turns.
+
+## Errors and stopping
+
+If the monitor stream ends, inspect its final output and report one sentence:
+
+- `already running (pid N)` — another listener is active; do not respawn.
+- `ticket: token rejected (HTTP 401|403)` — the project bearer is invalid.
+- `no patchcord config found` — Grok is outside a configured project.
+- `subscribe: fatal: ...` — report the fatal line verbatim.
+
+Do not use `pgrep`, `ps`, `pkill`, `killall`, hand-written pidfiles, or
+respawn loops. Stop by ending the Grok session or killing the pid from:
+`/tmp/patchcord_subscribe_<namespace>_<agent>.pid`.

package/per-project-skills/grok/wait/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: patchcord-wait
+description: >
+  Wait for one Patchcord response in this Grok project. Use only when the user
+  explicitly asks Grok to wait for a Patchcord message.
+user-invocable: true
+---
+
+# Patchcord wait for Grok
+
+Use only when the user explicitly asks to wait. If Patchcord MCP tools are not
+loaded, do not substitute the CLI, HTTP, or a config-file token.
+
+Call `patchcord__wait_for_message` once. When it returns, process the message
+before replying with concrete results. Use `patchcord__reply` with `resolve`
+when the thread is complete. Do not send text replies to ack-only messages.
+
+This is a one-shot wait. For a persistent realtime listener, use
+`patchcord-subscribe` instead.

package/skills/subscribe/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: patchcord:subscribe
 description: >
-  Start a persistent background WebSocket listener (Supabase Realtime) that
+  Start a persistent background WebSocket listener that
   wakes Claude when new Patchcord messages arrive. Survives across turns
   until the user kills it or closes the session. Use ONLY when the user
   explicitly runs /patchcord:subscribe.
@@ -50,7 +50,7 @@ Read the output file. Scan the last ~15 lines for one of:
 
 - `no .mcp.json in <cwd>` — session is not in a patchcord project dir
 - `ticket: token rejected (HTTP 401|403)` — bad bearer; user regenerates from dashboard
-- `ticket: server not configured for realtime` — self-hosted without Supabase
+- `ticket: server not configured for realtime` — self-hosted without realtime configured
 - `ticket: namespace not owned` — token lost its owner; regenerate
 - `already running (pid N)` (exit 2) — another listener is active; report and stop
 - `subscribe: fatal: ...` — surface the line verbatim