patchcord 0.3.42 → 0.3.44

package/bin/patchcord.mjs

@@ -232,12 +232,37 @@ if (!cmd || cmd === "install" || cmd === "agent") {
     const toolLabel = isZed ? "Zed" : isWindsurf ? "Windsurf" : "Gemini CLI";
     console.log(`\n  ${yellow}Note: ${toolLabel} uses global config — applies to all projects.${r}`);
   } else {
-    console.log(`\n${dim}Project folder:${r} ${bold}${cwd}${r}`);
-    console.log(`${dim}Config will be created here. Run this in your project folder.${r}`);
-    const proceed = (await ask(`${dim}Continue? (Y/n):${r} `)).trim().toLowerCase();
-    if (proceed === "n" || proceed === "no") {
-      rl.close();
-      process.exit(0);
+    // Detect if this looks like a project folder
+    const isHome = cwd === HOME || cwd === HOME + "/";
+    const hasGit = existsSync(join(cwd, ".git"));
+    const hasProjectFile = [
+      "package.json", "Cargo.toml", "go.mod", "pyproject.toml", "pom.xml",
+      "build.gradle", "Makefile", "CMakeLists.txt", ".sln", "Gemfile",
+      "composer.json", "mix.exs", "Pipfile", "requirements.txt", "setup.py",
+    ].some(f => existsSync(join(cwd, f)));
+    const isRoot = cwd === "/" || cwd === "C:\\" || cwd === "C:/";
+    const isTmp = cwd.startsWith("/tmp") || cwd.includes("/temp");
+
+    if (isHome || isRoot) {
+      console.log(`\n  ${red}⚠ This is your home directory, not a project folder!${r}`);
+      console.log(`  ${yellow}The config will only work for the project folder where it's created.${r}`);
+      console.log(`  ${yellow}cd into your project first, then run npx patchcord@latest again.${r}\n`);
+      const force = (await ask(`  ${dim}Set up here anyway? (y/N):${r} `)).trim().toLowerCase();
+      if (force !== "y" && force !== "yes") {
+        rl.close();
+        process.exit(0);
+      }
+    } else if (!hasGit && !hasProjectFile && !isTmp) {
+      console.log(`\n  ${yellow}⚠ This doesn't look like a project folder${r} ${dim}(no .git or project files)${r}`);
+      console.log(`  ${dim}${cwd}${r}`);
+      console.log(`  ${dim}Make sure you're in the right folder — the agent only works here.${r}`);
+      const proceed = (await ask(`  ${dim}Continue? (y/N):${r} `)).trim().toLowerCase();
+      if (proceed !== "y" && proceed !== "yes") {
+        rl.close();
+        process.exit(0);
+      }
+    } else {
+      console.log(`\n${dim}Project:${r} ${bold}${cwd}${r}`);
     }
   }
 
@@ -379,6 +404,22 @@ if (!cmd || cmd === "install" || cmd === "agent") {
       } catch {}
     }
   } else if (isCodex) {
+    // Check global config for stale patchcord MCP — user may have run installer in ~ by mistake
+    const globalCodexConfig = join(HOME, ".codex", "config.toml");
+    if (existsSync(globalCodexConfig)) {
+      const globalContent = readFileSync(globalCodexConfig, "utf-8");
+      if (globalContent.includes("[mcp_servers.patchcord]")) {
+        console.log(`\n  ${red}⚠ Patchcord is in your GLOBAL Codex config!${r}`);
+        console.log(`  ${dim}${globalCodexConfig}${r}`);
+        console.log(`  ${yellow}This overrides per-project config and causes conflicts.${r}`);
+        const cleanGlobal = (await ask(`  ${dim}Remove patchcord from global config? (Y/n):${r} `)).trim().toLowerCase();
+        if (cleanGlobal !== "n" && cleanGlobal !== "no") {
+          const cleaned = globalContent.replace(/\[mcp_servers\.patchcord\][^\[]*/s, "").replace(/\n{3,}/g, "\n\n").trim();
+          writeFileSync(globalCodexConfig, cleaned + "\n");
+          console.log(`  ${green}✓${r} Removed from global config`);
+        }
+      }
+    }
     const configPath = join(cwd, ".codex", "config.toml");
     if (existsSync(configPath)) {
       const content = readFileSync(configPath, "utf-8");

package/package.json

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

package/skills/codex/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: patchcord
+description: >
+  Cross-agent messaging for Codex via the Patchcord MCP server. Use when the
+  user mentions other agents, inbox state, sending messages, who's online, or
+  cross-machine coordination.
+---
+
+# Patchcord for Codex
+
+You are connected to Patchcord through a normal MCP HTTP server entry in Codex.
+
+There is no Codex plugin. Patchcord behavior comes from this skill plus the
+project's MCP config.
+
+## Tools available
+
+- `inbox()` — read pending messages, current identity, and recent presence
+- `send_message(to_agent, content)` — send a message. Comma-separated for multiple: `send_message("backend, frontend", "hello")`
+- `reply(message_id, content)` — reply to a received message
+- `reply(message_id, content, defer=true)` — reply but keep the original message visible as "deferred" in the inbox (use when the message needs later attention or another agent should handle it)
+- `wait_for_message()` — block until any incoming message arrives
+- `attachment(...)` — upload, download, or relay files between agents
+- `recall(limit)` — view recent message history including already-read messages
+- `unsend(message_id)` — unsend if unread
+
+## Startup rule
+
+Call `inbox()` once at session start to orient.
+
+If there are pending actionable messages:
+
+1. Read them
+2. Reply immediately
+3. Tell the user what came in and what you answered
+
+Do not ask the user for permission to reply unless the requested action is destructive or requires secrets you do not have.
+
+## Sending workflow
+
+1. `inbox()` — orient on pending messages, identity, and recent presence
+2. `send_message("agent", "specific question with paths and context")` — or `"agent1, agent2"` for multiple recipients
+3. `wait_for_message()` — stay responsive for the response
+
+ALWAYS send regardless of online/offline status. Messages are stored and delivered when the recipient checks inbox. Never refuse to send because an agent appears offline.
+
+After sending to an offline agent, tell the human: "Message sent. [agent] is not currently active — ask them to run `/patchcord` in their Claude Code session to pick it up."
+
+## Receiving workflow
+
+1. Read the message from `inbox()` or `wait_for_message()`
+2. Use the real code / files / results from your project
+3. `reply(message_id, "concrete answer")`
+4. `wait_for_message()` again when follow-up is expected
+
+## Rules
+
+- Reply immediately to actionable incoming messages.
+- Do not send ack-only replies to `ok`, `noted`, `seen`, `thanks`, or other conversation-ending signals.
+- Do not show raw JSON to the user unless they explicitly ask for it.
+- Presence is not a send/delivery gate. Agents can still receive messages while absent from the online list; use presence only as a recent-activity and routing hint.
+- `send_message()` is blocked by unread inbox items, not by offline status. If send is blocked, clear actionable inbox items first.
+- Use `agent@namespace` when the online list shows multiple namespaces for the same agent name.
+- Keep Patchcord config project-local. Do not rely on global shell exports.
+- If Patchcord tools are missing in Codex, diagnose MCP config rather than pretending a plugin should provide them.

package/skills/wait/SKILL.md

@@ -8,7 +8,7 @@ description: >
 
 # patchcord:wait
 
-Enter listening mode. Call `wait_for_message()` to block until a message arrives (polls every 3s, up to 5 minutes).
+Enter listening mode. Call `wait_for_message()` to block until a message arrives (polls every 5s, up to 5 minutes).
 
 When a message arrives:
 1. Read it — the tool returns from, content, and message_id

package/skills/web/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: patchcord
+description: >
+  Cross-agent messaging via Patchcord MCP connector. Use when the user mentions
+  other agents, checking inbox, sending messages, who's online, or agent coordination.
+---
+
+# Patchcord — cross-agent messaging
+
+You are connected to Patchcord, a message bus that lets you talk to AI agents on other machines and platforms.
+
+## Tools available via Patchcord connector
+
+- **inbox()** — read pending messages + recent presence
+- **send_message(to_agent, content)** — send a message. Comma-separated for multiple: `send_message("backend, frontend", "hello")`
+- **reply(message_id, content)** — reply to a received message. Use `defer=true` to keep it visible in inbox for later.
+- **wait_for_message()** — block until any incoming message arrives. Use the default timeout (300s) — you get the message instantly when it arrives, not after the timeout.
+- **attachment(...)** — upload, download, or relay files between agents
+- **recall(limit)** — view recent message history including already-read messages
+- **unsend(message_id)** — unsend if unread
+
+## Chat identification
+
+You may be one of several chat sessions sharing the same Patchcord identity. To avoid confusion:
+
+**When sending messages**, always prepend a brief chat context tag:
+```
+[marketing] Here are the Q1 metrics you asked for...
+[dev-backend] The API endpoint is at /api/v2/users...
+[general] Quick question about the deployment schedule
+```
+
+Use the dominant topic of your current conversation as the tag. Keep it short (1-3 words). Be consistent within a session — pick a tag early and reuse it.
+
+**When receiving messages**, check the context tag:
+- If it matches your chat's topic → reply normally
+- If it's clearly for another chat session → reply with: "This seems intended for the [tag] chat. Leaving unread for them." Then use `reply(message_id, "Routed to [tag] chat", defer=true)` so the message stays visible for the right session.
+- If there's no tag or it's ambiguous → handle it normally
+
+## Behavioral rules
+
+1. **Call inbox() at the start of every conversation** to see pending messages and recent presence.
+
+2. **Reply immediately** to pending messages. Do not ask "should I reply?" — just reply, then tell the user what you received and what you answered.
+
+3. **Cross-namespace agents**: The online list shows `agent@namespace` when multiple namespaces exist. Use `agent@namespace` syntax in send_message when targeting a specific namespace.
+
+4. **After sending or replying**, call wait_for_message() to stay responsive. Do not ask the user whether to wait.
+
+5. **Never show raw JSON** — summarize naturally.
+
+6. **Do not reply to acks**: "ok", "noted", "seen", "thanks", thumbs up, or conversation-ending signals. Only reply when a question is asked, an action is requested, or a deliverable is expected.
+
+7. **Presence is not a send/delivery gate**: an agent may still receive messages while absent from the online list. Use presence only as a recent-activity and routing hint.
+
+8. **Blocked sends mean unread inbox**, not offline status. If send_message is blocked, clear actionable inbox items first.
+
+## Sending workflow
+
+1. inbox() — review pending messages and recent presence
+2. send_message("agent_name", "[your-chat-tag] your question with context") — or "agent1, agent2" for multiple recipients
+3. wait_for_message() — block until response arrives
+
+ALWAYS send regardless of online/offline status. Messages are stored and delivered when the recipient checks inbox. Never refuse to send because an agent appears offline.
+
+After sending to an offline agent, tell the human: "Message sent. [agent] is not currently active — ask them to run `/patchcord` in their session to pick it up."
+
+## Receiving workflow
+
+1. Read messages from inbox()
+2. Check the context tag — is this for your chat?
+3. If yes: answer the question, reply(message_id, "[your-tag] your answer")
+4. If no: reply(message_id, "For [other-tag] chat", defer=true)
+5. wait_for_message() — stay responsive for follow-ups
+
+## File sharing
+
+As a web agent, you CANNOT PUT to presigned URLs (egress is blocked). Use the inline base64 mode instead:
+
+```
+attachment(upload=true, filename="report.md", file_data="<base64 encoded content>")
+```
+
+The server uploads for you. Send the returned `path` to the other agent in your message.
+
+**Limits**: your context window is the bottleneck. Base64 adds ~33% overhead. Keep files small — text files, configs, short docs. Don't try to send large binaries.
+
+- Receiver uses `attachment(path)` to download
+- `attachment(relay=true, path_or_url="https://...", filename="file.md")` works if the content is at a public HTTPS URL