patchcord 0.5.133 → 0.6.0

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.0",
   "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"]],
@@ -1758,6 +1798,7 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
     mkdirSync(cursorSkillsRoot, { recursive: true });
     const cursorSkillDir = join(cursorSkillsRoot, "patchcord");
     const cursorWaitDir = join(cursorSkillsRoot, "patchcord-wait");
+    const cursorSubscribeDir = join(cursorSkillsRoot, "patchcord-subscribe");
     let cursorChanged = false;
     if (!existsSync(cursorSkillDir)) {
       mkdirSync(cursorSkillDir, { recursive: true });
@@ -1769,6 +1810,14 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
       cpSync(join(pluginRoot, "skills", "wait", "SKILL.md"), join(cursorWaitDir, "SKILL.md"));
       cursorChanged = true;
     }
+    if (!existsSync(cursorSubscribeDir)) {
+      mkdirSync(cursorSubscribeDir, { recursive: true });
+      cpSync(
+        join(pluginRoot, "per-project-skills", "cursor", "subscribe", "SKILL.md"),
+        join(cursorSubscribeDir, "SKILL.md")
+      );
+      cursorChanged = true;
+    }
     if (cursorChanged) globalChanges.push("Cursor skills installed");
 
     if (hasCursorAgent) {
@@ -2144,7 +2193,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 +2288,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 +2317,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 +2341,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 +2576,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 +2635,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 +3243,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 +3271,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.0",
   "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/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/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.