patchcord 0.3.95 → 0.3.97

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "patchcord",
   "description": "Cross-machine agent messaging with push delivery. Messages from other agents arrive as native channel notifications.",
-  "version": "0.4.0",
+  "version": "0.3.96",
   "author": {
     "name": "ppravdin"
   },

package/bin/patchcord.mjs

@@ -173,12 +173,12 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd === "--token" || cmd ===
     let cursorChanged = false;
     if (!existsSync(cursorSkillDir)) {
       mkdirSync(cursorSkillDir, { recursive: true });
-      cpSync(join(pluginRoot, "skills", "inbox", "SKILL.md"), join(cursorSkillDir, "SKILL.md"));
+      cpSync(join(pluginRoot, "skills", "patchcord", "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"));
+      cpSync(join(pluginRoot, "skills", "patchcord-wait", "SKILL.md"), join(cursorWaitDir, "SKILL.md"));
       cursorChanged = true;
     }
     if (cursorChanged) globalChanges.push("Cursor skills installed");
@@ -191,12 +191,12 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd === "--token" || cmd ===
     let windsurfChanged = false;
     if (!existsSync(windsurfSkillDir)) {
       mkdirSync(windsurfSkillDir, { recursive: true });
-      cpSync(join(pluginRoot, "skills", "inbox", "SKILL.md"), join(windsurfSkillDir, "SKILL.md"));
+      cpSync(join(pluginRoot, "skills", "patchcord", "SKILL.md"), join(windsurfSkillDir, "SKILL.md"));
       windsurfChanged = true;
     }
     if (!existsSync(windsurfWaitDir)) {
       mkdirSync(windsurfWaitDir, { recursive: true });
-      cpSync(join(pluginRoot, "skills", "wait", "SKILL.md"), join(windsurfWaitDir, "SKILL.md"));
+      cpSync(join(pluginRoot, "skills", "patchcord-wait", "SKILL.md"), join(windsurfWaitDir, "SKILL.md"));
       windsurfChanged = true;
     }
     if (windsurfChanged) globalChanges.push("Windsurf skills installed");
@@ -210,12 +210,12 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd === "--token" || cmd ===
     let geminiChanged = false;
     if (!existsSync(geminiSkillDir)) {
       mkdirSync(geminiSkillDir, { recursive: true });
-      cpSync(join(pluginRoot, "skills", "inbox", "SKILL.md"), join(geminiSkillDir, "SKILL.md"));
+      cpSync(join(pluginRoot, "skills", "patchcord", "SKILL.md"), join(geminiSkillDir, "SKILL.md"));
       geminiChanged = true;
     }
     if (!existsSync(geminiWaitDir)) {
       mkdirSync(geminiWaitDir, { recursive: true });
-      cpSync(join(pluginRoot, "skills", "wait", "SKILL.md"), join(geminiWaitDir, "SKILL.md"));
+      cpSync(join(pluginRoot, "skills", "patchcord-wait", "SKILL.md"), join(geminiWaitDir, "SKILL.md"));
       geminiChanged = true;
     }
     if (!existsSync(join(geminiCmdDir, "patchcord.toml"))) {
@@ -264,6 +264,7 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd === "--token" || cmd ===
   const CLIENT_TYPE_MAP = {
     "claude_code": "1", "codex": "2", "cursor": "3", "windsurf": "4",
     "gemini": "5", "vscode": "6", "zed": "7", "opencode": "8", "openclaw": "9", "antigravity": "10",
+    "cline": "11",
   };
 
 
@@ -298,9 +299,9 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd === "--token" || cmd ===
     console.log(`  ${cyan}2.${r} Codex CLI     ${cyan}6.${r} VS Code`);
     console.log(`  ${cyan}3.${r} Cursor        ${cyan}7.${r} Zed`);
     console.log(`  ${cyan}4.${r} Windsurf      ${cyan}8.${r} OpenCode`);
-    console.log(`                    ${cyan}9.${r} OpenClaw\n`);
-    choice = (await ask(`${dim}Choose (1-9):${r} `)).trim();
-    if (!["1","2","3","4","5","6","7","8","9"].includes(choice)) {
+    console.log(`  ${cyan}11.${r} Cline         ${cyan}9.${r} OpenClaw\n`);
+    choice = (await ask(`${dim}Choose (1-9, 11):${r} `)).trim();
+    if (!["1","2","3","4","5","6","7","8","9","11"].includes(choice)) {
       console.error("Invalid choice.");
       rl.close();
       process.exit(1);
@@ -566,6 +567,7 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd === "--token" || cmd ===
   const isOpenCode = choice === "8";
   const isOpenClaw = choice === "9";
   const isAntigravity = choice === "10";
+  const isCline = choice === "11";
 
   const hostname = run("hostname -s") || run("hostname") || "unknown";
 
@@ -765,10 +767,68 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd === "--token" || cmd ===
     const agWaitDir = join(agDir, "skills", "patchcord-wait");
     mkdirSync(agSkillDir, { recursive: true });
     mkdirSync(agWaitDir, { recursive: true });
-    cpSync(join(pluginRoot, "skills", "inbox", "SKILL.md"), join(agSkillDir, "SKILL.md"));
-    cpSync(join(pluginRoot, "skills", "wait", "SKILL.md"), join(agWaitDir, "SKILL.md"));
+    cpSync(join(pluginRoot, "skills", "patchcord", "SKILL.md"), join(agSkillDir, "SKILL.md"));
+    cpSync(join(pluginRoot, "skills", "patchcord-wait", "SKILL.md"), join(agWaitDir, "SKILL.md"));
     console.log(`  ${green}✓${r} Skills installed: ${dim}patchcord${r}, ${dim}patchcord-wait${r}`);
     console.log(`  ${yellow}Global config — all Antigravity projects share this agent.${r}`);
+  } else if (isCline) {
+    // Cline VS Code extension: global cline_mcp_settings.json
+    // Config lives in VS Code's globalStorage for saoudrizwan.claude-dev
+    // Try stable VS Code first, then Insiders, then Cursor
+    const vsCodeVariants = process.platform === "darwin"
+      ? [
+          join(HOME, "Library", "Application Support", "Code", "User", "globalStorage"),
+          join(HOME, "Library", "Application Support", "Code - Insiders", "User", "globalStorage"),
+          join(HOME, "Library", "Application Support", "Cursor", "User", "globalStorage"),
+        ]
+      : process.platform === "win32"
+      ? [
+          join(process.env.APPDATA || join(HOME, "AppData", "Roaming"), "Code", "User", "globalStorage"),
+          join(process.env.APPDATA || join(HOME, "AppData", "Roaming"), "Code - Insiders", "User", "globalStorage"),
+          join(process.env.APPDATA || join(HOME, "AppData", "Roaming"), "Cursor", "User", "globalStorage"),
+        ]
+      : [
+          join(HOME, ".config", "Code", "User", "globalStorage"),
+          join(HOME, ".config", "Code - Insiders", "User", "globalStorage"),
+          join(HOME, ".config", "Cursor", "User", "globalStorage"),
+        ];
+
+    // Find the first variant that has Cline's globalStorage directory (or exists at all)
+    const clineExtDir = "saoudrizwan.claude-dev";
+    let clineSettingsDir = null;
+    for (const base of vsCodeVariants) {
+      const candidate = join(base, clineExtDir, "settings");
+      const extDir = join(base, clineExtDir);
+      if (existsSync(extDir)) {
+        clineSettingsDir = candidate;
+        break;
+      }
+    }
+    // Fall back to stable VS Code path even if it doesn't exist yet
+    if (!clineSettingsDir) {
+      const fallbackBase = vsCodeVariants[0];
+      clineSettingsDir = join(fallbackBase, clineExtDir, "settings");
+    }
+
+    const clinePath = join(clineSettingsDir, "cline_mcp_settings.json");
+    let clineConfig = {};
+    if (existsSync(clinePath)) {
+      try { clineConfig = JSON.parse(readFileSync(clinePath, "utf-8")); } catch {}
+    }
+    if (!clineConfig.mcpServers) clineConfig.mcpServers = {};
+    clineConfig.mcpServers.patchcord = {
+      url: `${serverUrl}/mcp`,
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "X-Patchcord-Machine": hostname,
+      },
+      disabled: false,
+      alwaysAllow: [],
+    };
+    mkdirSync(clineSettingsDir, { recursive: true });
+    writeFileSync(clinePath, JSON.stringify(clineConfig, null, 2) + "\n");
+    console.log(`\n  ${green}✓${r} Cline configured: ${dim}${clinePath}${r}`);
+    console.log(`  ${yellow}Global config — all Cline projects share this agent.${r}`);
   } else if (isVSCode) {
     // VS Code: write .vscode/mcp.json (per-project)
     const vscodeDir = join(cwd, ".vscode");
@@ -811,7 +871,7 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd === "--token" || cmd ===
     const waitDest = join(cwd, ".agents", "skills", "patchcord-wait");
     mkdirSync(waitDest, { recursive: true });
     writeFileSync(join(waitDest, "SKILL.md"),
-      readFileSync(join(pluginRoot, "skills", "wait", "SKILL.md"), "utf-8"));
+      readFileSync(join(pluginRoot, "skills", "patchcord-wait", "SKILL.md"), "utf-8"));
 
     const codexDir = join(cwd, ".codex");
     mkdirSync(codexDir, { recursive: true });
@@ -873,7 +933,7 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd === "--token" || cmd ===
     writeFileSync(join(pluginDir, "skills", "patchcord", "SKILL.md"),
       readFileSync(join(pluginRoot, "per-project-skills", "codex", "SKILL.md"), "utf-8"));
     writeFileSync(join(pluginDir, "skills", "patchcord-wait", "SKILL.md"),
-      readFileSync(join(pluginRoot, "skills", "wait", "SKILL.md"), "utf-8"));
+      readFileSync(join(pluginRoot, "skills", "patchcord-wait", "SKILL.md"), "utf-8"));
 
     // Personal marketplace entry (relative path from marketplace root)
     const marketplacePath = join(marketplaceDir, "marketplace.json");
@@ -899,7 +959,7 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd === "--token" || cmd ===
     const globalWaitDir = join(homedir(), ".agents", "skills", "patchcord-wait");
     mkdirSync(globalWaitDir, { recursive: true });
     writeFileSync(join(globalWaitDir, "SKILL.md"),
-      readFileSync(join(pluginRoot, "skills", "wait", "SKILL.md"), "utf-8"));
+      readFileSync(join(pluginRoot, "skills", "patchcord-wait", "SKILL.md"), "utf-8"));
 
     console.log(`\n  ${green}✓${r} Codex configured: ${dim}${configPath}${r}`);
     console.log(`  ${green}✓${r} Plugin installed: ${dim}@patchcord${r}, ${dim}@patchcord-wait${r}`);
@@ -944,24 +1004,27 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd === "--token" || cmd ===
   }
 
   // Warn about gitignore for per-project configs with tokens
-  if (!isWindsurf && !isGemini && !isZed && !isOpenClaw && !isAntigravity) {
+  if (!isWindsurf && !isGemini && !isZed && !isOpenClaw && !isAntigravity && !isCline) {
     const gitignorePath = join(cwd, ".gitignore");
     const configFile = isCodex ? ".codex/config.toml" : isCursor ? ".cursor/mcp.json" : isVSCode ? ".vscode/mcp.json" : isOpenCode ? "opencode.json" : ".mcp.json";
     let needsWarning = true;
     if (existsSync(gitignorePath)) {
       const gi = readFileSync(gitignorePath, "utf-8");
-      if (gi.includes(configFile) || gi.includes(".mcp.json") || gi.includes(".codex/") || gi.includes(".cursor/")) {
-        needsWarning = false;
-      }
+      // Only check patterns relevant to this agent's config file
+      const patterns = [configFile];
+      if (isCodex) patterns.push(".codex/");
+      else if (isCursor) patterns.push(".cursor/");
+      else if (isVSCode) patterns.push(".vscode/");
+      if (patterns.some(p => gi.includes(p))) needsWarning = false;
     }
     if (needsWarning) {
       console.log(`\n  ${yellow}⚠ Add ${configFile} to .gitignore — it contains your token${r}`);
     }
   }
 
-  const toolName = isAntigravity ? "Antigravity" : isOpenClaw ? "OpenClaw" : isOpenCode ? "OpenCode" : isZed ? "Zed" : isVSCode ? "VS Code" : isGemini ? "Gemini CLI" : isWindsurf ? "Windsurf" : isCursor ? "Cursor" : isCodex ? "Codex" : "Claude Code";
+  const toolName = isAntigravity ? "Antigravity" : isCline ? "Cline" : isOpenClaw ? "OpenClaw" : isOpenCode ? "OpenCode" : isZed ? "Zed" : isVSCode ? "VS Code" : isGemini ? "Gemini CLI" : isWindsurf ? "Windsurf" : isCursor ? "Cursor" : isCodex ? "Codex" : "Claude Code";
 
-  if (!isWindsurf && !isGemini && !isZed && !isOpenClaw && !isAntigravity) {
+  if (!isWindsurf && !isGemini && !isZed && !isOpenClaw && !isAntigravity && !isCline) {
     console.log(`\n  ${dim}To connect a second agent:${r}`);
     console.log(`  ${dim}cd into another project and run${r} ${bold}npx patchcord@latest${r} ${dim}there.${r}`);
   }

package/package.json

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

package/per-project-skills/codex/SKILL.md

@@ -15,12 +15,12 @@ project's MCP config.
 
 ## Tools available
 
-- `inbox(all_agents?)` - read pending messages, current identity, and recently active agents. `all_agents=true` includes inactive agents. Presence tells you whether to wait for a reply after sending, not whether to send.
-- `send_message(to_agent, content)` - send a message. Comma-separated for multiple: `send_message("backend, frontend", "hello")`. Use `@username` for cross-user Gate messaging. Messages support up to 50,000 characters - send full content, specs, and code as-is. Never summarize or truncate.
-- `reply(message_id, content?, defer?, resolve?)` - reply to a received message. `defer=true` keeps the original visible in inbox for later (survives context compaction). `resolve=true` marks the message as handled — content is optional, use `reply(message_id, resolve=true)` to silently close a thread without sending anything.
+- `inbox(all_agents?)` - read pending messages, current identity, and recently active agents. `all_agents=true` includes inactive agents. Returns a `groups` list (messages grouped by thread) alongside the legacy `pending` flat list. Presence tells you whether to wait for a reply after sending, not whether to send.
+- `send_message(to_agent, content, thread?)` - send a message. Comma-separated for multiple: `send_message("backend, frontend", "hello")`. Use `@username` for cross-user Gate messaging. `thread` is an optional slug to start or join a named thread: `send_message("backend", "...", thread="auth-migration")`. Messages support up to 50,000 characters - send full content, specs, and code as-is. Never summarize or truncate.
+- `reply(message_id, content?, defer?, resolve?)` - reply to a received message. Auto-inherits the thread of the original. `defer=true` keeps the original visible in inbox for later (survives context compaction). `resolve=true` closes the thread — stamps `thread_resolved_at` and notifies sender. Content is optional: use `reply(message_id, resolve=true)` to silently close without sending.
 - `wait_for_message(timeout_seconds?)` - block until incoming message arrives. Default 5 minutes. Known to error intermittently - if it fails, poll inbox() every 10-15 seconds as fallback.
 - `attachment(...)` - upload, download, or relay files between agents (see File sharing below)
-- `recall(limit?, from_agent?)` - view recent message history including already-read messages. `from_agent` filters by sender. For debugging only, not routine use.
+- `recall(limit?, 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
 
 ## Do the work, never just acknowledge
@@ -49,10 +49,21 @@ If there are pending actionable messages:
 
 Do not ask the user for permission to reply unless the requested action is destructive or requires secrets you do not have.
 
+## Threads
+
+Named threads group related messages between a pair of agents. Use them for multi-turn tasks that need their own context.
+
+- **Start**: `send_message("backend", "track this here", thread="deploy-review")`
+- **Reply stays in thread automatically** — `reply()` inherits `thread_id` from the message you're replying to.
+- **Close**: `reply(message_id, "done", resolve=true)` — closes the thread and notifies sender.
+- **Filter history**: `recall(thread_id="<uuid>")` — only messages in that thread.
+
+`inbox()` `groups` field clusters pending messages by thread. Each group: `{ thread_id, thread_title, messages }`. `thread_id: null` = pair-level.
+
 ## Sending workflow
 
 1. `inbox()` - clear pending messages that block outbound sends. Note who's online (determines whether to wait after sending).
-2. `send_message("agent", "specific question with paths and context")` - or `"agent1, agent2"` for multiple, or `"@username"` for cross-user Gate messaging.
+2. `send_message("agent", "specific question with paths and context")` - or `"agent1, agent2"` for multiple, or `"@username"` for cross-user Gate messaging. Add `thread="slug"` to group messages in a named thread.
 3. If recipient is online: `wait_for_message()` - stay responsive for the response. If offline: skip the wait, tell the human the message is queued.
 
 Always send regardless of online/offline status. Messages are stored and delivered when the recipient checks inbox. Never refuse to send because an agent appears offline.
@@ -63,11 +74,12 @@ If send_message fails with a send gate error: call inbox(), reply to or resolve
 
 ## Receiving workflow
 
-1. Read the message from `inbox()` or `wait_for_message()`
+1. Read the message from `inbox()` or `wait_for_message()`. Check `message.thread` / `message.thread_id` if present.
 2. Do the work - use real code, real files, real results from your project
 3. Reply with the right flag:
-   - `reply(message_id, "done: [details]")` — work done, sender might follow up
-   - `reply(message_id, "done: [details]", resolve=true)` — work done, conversation finished
+   - `reply(message_id, "done: [details]")` — work done, sender might follow up. Thread auto-inherited.
+   - `reply(message_id, "done: [details]", resolve=true)` — work done, thread closed.
+   - `reply(message_id, resolve=true)` — silently close without sending anything.
    - `reply(message_id, "ack, prioritizing [other task] first", defer=true)` — acknowledged but work not done yet. Message stays in your inbox as a reminder.
 4. If sender is online: `wait_for_message()` for follow-ups
 

package/per-project-skills/web/SKILL.md

@@ -11,12 +11,12 @@ You are connected to Patchcord, a message bus that lets you talk to AI agents on
 
 ## Tools
 
-- **inbox(all_agents?)** - read pending messages + recent activity. `all_agents=true` includes inactive agents. Presence tells you whether to wait for a reply, not whether to send. Online = set up wait_for_message after sending. Offline = send and move on, don't wait.
-- **send_message(to_agent, content)** - send a message. Comma-separated for multiple: `send_message("backend, frontend", "hello")`. Supports `@username` for cross-user Gate messaging. Up to 50,000 characters - send full content, never summarize.
-- **reply(message_id, content?, defer?, resolve?)** - reply to a received message. `defer=true` keeps message visible in inbox (survives context compaction). `resolve=true` marks as handled — content is optional, use `reply(message_id, resolve=true)` to silently close a thread.
+- **inbox(all_agents?)** - read pending messages + recent activity. Returns a `groups` list (messages grouped by thread) alongside the legacy `pending` flat list. `all_agents=true` includes inactive agents. Presence tells you whether to wait for a reply, not whether to send.
+- **send_message(to_agent, content, thread?)** - send a message. Comma-separated for multiple: `send_message("backend, frontend", "hello")`. Supports `@username` for cross-user Gate messaging. `thread` slug starts or joins a named thread: `send_message("backend", "...", thread="deploy-review")`. Up to 50,000 characters — never summarize.
+- **reply(message_id, content?, defer?, resolve?)** - reply to a received message. Auto-inherits thread from the original. `defer=true` keeps message visible in inbox (survives context compaction). `resolve=true` closes the thread — stamps `thread_resolved_at` and notifies sender. Content optional: `reply(message_id, resolve=true)` to silently close.
 - **wait_for_message(timeout_seconds?)** - block until incoming message arrives. Default 300s. Known to error intermittently - if it fails, poll inbox() in a loop as fallback.
 - **attachment(...)** - file operations (see File sharing section below)
-- **recall(limit?, from_agent?)** - view recent message history including already-read messages. Debugging only, not routine use. `from_agent` filters by sender.
+- **recall(limit?, from_agent?, thread_id?)** - view recent message history including already-read messages. `from_agent` filters by sender. `thread_id` filters to a specific thread. Debugging only.
 - **unsend(message_id)** - take back a message before recipient reads it.
 
 ## Chat identification
@@ -61,10 +61,21 @@ Use the dominant topic of your current conversation as the tag. Keep it short (1
 
 10. **MCP tools are cached at session start.** New tools deployed after your session began are invisible until you open a new chat. If a tool you expect is missing, this is why.
 
+## Threads
+
+Named threads group related messages. Use them for multi-turn tasks that need their own context.
+
+- **Start**: `send_message("backend", "...", thread="auth-migration")`
+- **Reply stays in thread automatically** — `reply()` inherits the thread from the original.
+- **Close**: `reply(message_id, "done", resolve=true)` — closes thread, notifies sender.
+- **Filter history**: `recall(thread_id="<uuid>")` — only that thread's messages.
+
+`inbox()` `groups` field clusters pending messages by thread: `{ thread_id, thread_title, messages }`. `thread_id: null` = pair-level (no thread).
+
 ## Sending workflow
 
 1. inbox() - clear pending messages that block outbound sends. Note who's online (determines whether to wait after sending).
-2. send_message("agent_name", "[your-chat-tag] your question with context") - or "agent1, agent2" for multiple, or "@username" for cross-user
+2. send_message("agent_name", "[your-chat-tag] your question with context") - or "agent1, agent2" for multiple, or "@username" for cross-user. Add `thread="slug"` to group in a named thread.
 3. If recipient is online: wait_for_message() - block until response arrives. If offline: skip wait, tell the human the message is queued.
 
 ALWAYS send regardless of online/offline status. Messages are stored and delivered when the recipient checks inbox. Never refuse to send because an agent appears offline.
@@ -73,11 +84,11 @@ After sending to an offline agent, tell the human: "Message sent. [agent] is not
 
 ## Receiving workflow
 
-1. Read messages from inbox()
+1. Read messages from inbox(). Check `message.thread` / `message.thread_id` if present.
 2. Check the context tag - is this for your chat?
 3. If yes: do the work, then reply with the right flag:
-   - `reply(message_id, "[tag] done: [details]")` — work done, sender might follow up
-   - `reply(message_id, "[tag] done", resolve=true)` — work done, conversation finished
+   - `reply(message_id, "[tag] done: [details]")` — work done, thread auto-inherited
+   - `reply(message_id, "[tag] done", resolve=true)` — work done, thread closed
    - `reply(message_id, "[tag] ack, will do after [other task]", defer=true)` — acknowledged but work not done yet. Message stays in inbox.
 4. If no: reply(message_id, "For [other-tag] chat", defer=true)
 5. wait_for_message() - stay responsive for follow-ups

package/skills/{inbox → patchcord}/SKILL.md

@@ -39,7 +39,7 @@ If there are pending messages, reply to all of them immediately. Do not ask the
 ## Sending
 
 1. inbox() - clear any pending messages that block outbound sends. Note who's online (determines whether to wait after sending, not whether to send).
-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.
+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. If recipient is online: wait_for_message() - block until response arrives. Use the default timeout (300s) - you get the message instantly when it arrives, not after the timeout. The other agent needs time to do the work and reply. Never shorten the timeout. If offline: skip the wait, tell the human the message is queued.
 
 Always send regardless of whether the recipient appears online or offline. Messages are stored and delivered when the recipient checks inbox. "Offline" means not recently active - not that they can't receive messages.
@@ -50,11 +50,11 @@ If send_message fails with a send gate error: call inbox(), reply to or resolve
 
 ## Receiving (inbox has messages)
 
-1. Read the message
+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
-   - `reply(message_id, "done: [details]", resolve=true)` — work done, conversation finished
+   - `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. wait_for_message() if the sender is online - stay responsive for follow-ups
@@ -97,9 +97,20 @@ Use the path from the sender's message.
 
 Send the returned `path` to the other agent in your message so they can download it.
 
+## 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="") - view recent message history including already-read messages. Use `from_agent` to filter by sender. For debugging only, not routine use.
+- 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

package/skills/{wait → patchcord-wait}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: "patchcord:wait"
+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
@@ -11,9 +11,9 @@ Enter listening mode. Call `wait_for_message()` to block until a message arrives
 
 When a message arrives:
 
-1. Read it - the tool returns from, content, and message_id
+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]")` - use `resolve=true` if the thread is complete.
+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