patchcord 0.5.64 → 0.5.66

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.
+One command. Opens browser, configures everything. Works with Claude Code, Codex CLI, Cursor, Windsurf, Gemini CLI, VS Code, Zed, OpenCode, Kimi CLI.
 
 Self-hosted:
 
@@ -23,6 +23,7 @@ npx patchcord@latest --token <token> --server https://patchcord.yourdomain.com
 - **Stop hook** — checks inbox between turns, notifies of pending messages
 - **Slash commands** — `/patchcord` and `/patchcord-wait` for Codex and Gemini CLI
 - **MCP config** — per-project or global config depending on tool
+- **Kimi CLI** — global MCP config plus skills in `~/.kimi/skills/`
 
 ## How it works
 

package/bin/patchcord.mjs

@@ -79,7 +79,7 @@ Usage:
   patchcord agents                                        List every agent (with whoami)
   patchcord agents <name>                                 Show one agent's whoami
   patchcord upload <file> [--mime <type>] [--as <name>]   Upload a file as a patchcord attachment (prints the storage path)
-  patchcord subscribe                                     Start the realtime listener
+  patchcord subscribe [interval]                          Start the realtime listener (Kimi: background poll, default 30s)
   patchcord update                                        Update to the latest version
   patchcord --version                                     Show installed version
   patchcord --help                                        Show this help
@@ -94,9 +94,9 @@ if (cmd === "plugin-path") {
 }
 
 // Shared bearer/base-url resolver. Project-local configs win over globals.
-// Supports all 11 installer targets: claude_code, codex, cursor, vscode,
+// Supports all 12 installer targets: claude_code, codex, cursor, vscode,
 // opencode (per-project) + windsurf, gemini, zed, openclaw, antigravity,
-// cline (global). Each tool stores the bearer in its own shape.
+// cline, kimi (global). Each tool stores the bearer in its own shape.
 async function _resolveBearer() {
   const { readFileSync } = await import("fs");
 
@@ -240,6 +240,7 @@ async function _resolveBearer() {
     () => readJsonAt(join(HOME, ".openclaw", "openclaw.json"), ["mcp", "servers", "patchcord"], "openclaw"),
     () => readJsonAt(join(HOME, ".gemini", "antigravity", "mcp_config.json"), ["mcpServers", "patchcord"], "antigravity"),
     ...clinePaths.map((p) => () => readJsonAt(p, ["mcpServers", "patchcord"], "cline")),
+    () => readJsonAt(join(HOME, ".kimi", "mcp.json"), ["mcpServers", "patchcord"], "kimi"),
   ];
   for (const r of globalCandidates) {
     const found = r();
@@ -458,16 +459,34 @@ if (cmd === "upload") {
 // (exits with code 2 + "already running" if another listener is up),
 // so this command needs zero pre-checks.
 //
-// We resolve the bearer here (all 11 tool configs) and inject it as
+// We resolve the bearer here (all 12 tool configs) and inject it as
 // env vars so subscribe.mjs works regardless of which MCP client is
 // running — OpenCode, Codex, Cursor, etc. — not just Claude Code.
 if (cmd === "subscribe") {
+  const bearerInfo = await _resolveBearer();
+
+  // Kimi CLI uses polling instead of WebSocket realtime
+  if (bearerInfo?.tool === "kimi") {
+    const kimiSubScript = join(HOME, ".kimi", "patchcord-subscribe.sh");
+    if (!existsSync(kimiSubScript)) {
+      console.error(`Kimi subscribe script not found at ${kimiSubScript}`);
+      console.error(`Run npx patchcord@latest to install it.`);
+      process.exit(1);
+    }
+    const { spawnSync } = await import("child_process");
+    const intervalArg = process.argv[3] || "30";
+    const result = spawnSync("bash", [kimiSubScript, intervalArg], {
+      stdio: "inherit",
+      env: { ...process.env, PATH: process.env.PATH || "/usr/local/bin:/usr/bin:/bin" },
+    });
+    process.exit(result.status ?? (result.signal ? 1 : 0));
+  }
+
   const subscribeScript = join(pluginRoot, "scripts", "subscribe.mjs");
   if (!existsSync(subscribeScript)) {
     console.error(`subscribe.mjs not found at ${subscribeScript}`);
     process.exit(1);
   }
-  const bearerInfo = await _resolveBearer();
   const spawnEnv = { ...process.env };
   if (bearerInfo) {
     spawnEnv.PATCHCORD_BASE_URL = bearerInfo.baseUrl;
@@ -946,6 +965,62 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
     if (geminiChanged) globalChanges.push("Gemini CLI skills + commands installed");
   }
 
+  // Kimi CLI
+  const hasKimi = run("which kimi");
+  if (hasKimi) {
+    const kimiSkillDir = join(HOME, ".kimi", "skills", "patchcord");
+    const kimiWaitDir = join(HOME, ".kimi", "skills", "patchcord-wait");
+    let kimiChanged = false;
+    if (!existsSync(kimiSkillDir)) {
+      mkdirSync(kimiSkillDir, { recursive: true });
+      cpSync(join(pluginRoot, "per-project-skills", "kimi", "SKILL.md"), join(kimiSkillDir, "SKILL.md"));
+      kimiChanged = true;
+    }
+    if (!existsSync(kimiWaitDir)) {
+      mkdirSync(kimiWaitDir, { recursive: true });
+      cpSync(join(pluginRoot, "per-project-skills", "kimi", "wait", "SKILL.md"), join(kimiWaitDir, "SKILL.md"));
+      kimiChanged = true;
+    }
+    if (kimiChanged) globalChanges.push("Kimi CLI skills installed");
+
+    // Install/update stop hook — fires after each Kimi turn to check inbox
+    const kimiHookSrc = join(pluginRoot, "scripts", "kimi-stop-hook.sh");
+    const kimiHookDest = join(HOME, ".kimi", "patchcord-stop-hook.sh");
+    if (existsSync(kimiHookSrc)) {
+      const hookAlreadyExisted = existsSync(kimiHookDest);
+      copyFileSync(kimiHookSrc, kimiHookDest);
+      chmodSync(kimiHookDest, 0o755);
+
+      const kimiConfigPath = join(HOME, ".kimi", "config.toml");
+      let kimiConfig = existsSync(kimiConfigPath) ? readFileSync(kimiConfigPath, "utf-8") : "";
+
+      // Remove old inline hooks = [] (conflicts with [[hooks]] array-of-tables)
+      kimiConfig = kimiConfig.replace(/^hooks\s*=\s*\[\]\n?/gm, "");
+
+      // Remove existing patchcord stop hook blocks
+      const segments = kimiConfig.split("[[hooks]]");
+      const kept = segments.filter((seg, idx) => idx === 0 || !seg.includes("patchcord-stop-hook"));
+      kimiConfig = kept.join("[[hooks]]").replace(/\n{3,}/g, "\n\n").trim();
+
+      // Append new hook
+      kimiConfig = kimiConfig.trimEnd() + `\n\n[[hooks]]\nevent = "Stop"\ncommand = "${kimiHookDest}"\ntimeout = 10\n`;
+
+      mkdirSync(dirname(kimiConfigPath), { recursive: true });
+      writeFileSync(kimiConfigPath, kimiConfig);
+      globalChanges.push(`Kimi stop hook ${hookAlreadyExisted ? "updated" : "installed"}`);
+    }
+
+    // Install/update Kimi subscribe script (background polling)
+    const kimiSubSrc = join(pluginRoot, "scripts", "kimi-subscribe.sh");
+    const kimiSubDest = join(HOME, ".kimi", "patchcord-subscribe.sh");
+    if (existsSync(kimiSubSrc)) {
+      const subAlreadyExisted = existsSync(kimiSubDest);
+      copyFileSync(kimiSubSrc, kimiSubDest);
+      chmodSync(kimiSubDest, 0o755);
+      globalChanges.push(`Kimi subscribe script ${subAlreadyExisted ? "updated" : "installed"}`);
+    }
+  }
+
   // Codex CLI — clean up old settings and install stop hook
   const codexConfig = join(HOME, ".codex", "config.toml");
   if (existsSync(codexConfig)) {
@@ -1006,8 +1081,8 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
     }
   }
 
-  if (!hasClaude && !existsSync(codexConfig)) {
-    console.log(`${dim}No Claude Code or Codex CLI detected — skipping global setup.${r}`);
+  if (!hasClaude && !existsSync(codexConfig) && !hasKimi) {
+    console.log(`${dim}No Claude Code, Codex CLI, or Kimi CLI detected — skipping global setup.${r}`);
   }
 
   if (updateOnly) process.exit(0);
@@ -1025,7 +1100,7 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
   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",
+    "cline": "11", "kimi": "12",
   };
 
 
@@ -1077,13 +1152,12 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
     // already pre-selected one for us.
     if (!choice) {
       console.log(`\n${bold}Which tool are you setting up?${r}\n`);
-      console.log(`  ${cyan}1.${r} Claude Code   ${cyan}5.${r} Gemini CLI`);
-      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}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.log(`  ${cyan}1.${r} Claude Code   ${cyan}5.${r} Gemini CLI   ${cyan}9.${r} OpenClaw`);
+      console.log(`  ${cyan}2.${r} Codex CLI     ${cyan}6.${r} VS Code      ${cyan}10.${r} Antigravity`);
+      console.log(`  ${cyan}3.${r} Cursor        ${cyan}7.${r} Zed          ${cyan}11.${r} Cline`);
+      console.log(`  ${cyan}4.${r} Windsurf      ${cyan}8.${r} OpenCode     ${cyan}12.${r} Kimi CLI\n`);
+      choice = (await ask(`${dim}Choose (1-12):${r} `)).trim();
+      if (!["1","2","3","4","5","6","7","8","9","10","11","12"].includes(choice)) {
         console.error("Invalid choice.");
         rl.close();
         process.exit(1);
@@ -1393,6 +1467,7 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
   const isOpenClaw = choice === "9";
   const isAntigravity = choice === "10";
   const isCline = choice === "11";
+  const isKimi = choice === "12";
 
   const hostname = run("hostname -s") || run("hostname") || "unknown";
 
@@ -1625,6 +1700,31 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
       console.log(`\n  ${green}✓${r} Cline configured: ${dim}${clinePath}${r}`);
       console.log(`  ${yellow}Global config — all Cline projects share this agent.${r}`);
     }
+  } else if (isKimi) {
+    // Kimi CLI: global ~/.kimi/mcp.json
+    const kimiPath = join(HOME, ".kimi", "mcp.json");
+    const kimiOk = updateJsonConfig(kimiPath, (obj) => {
+      obj.mcpServers = obj.mcpServers || {};
+      obj.mcpServers.patchcord = {
+        url: `${serverUrl}/mcp`,
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "X-Patchcord-Machine": hostname,
+        },
+      };
+    });
+    if (kimiOk) {
+      console.log(`\n  ${green}✓${r} Kimi CLI configured: ${dim}${kimiPath}${r}`);
+      console.log(`  ${yellow}Global config — all Kimi CLI projects share this agent.${r}`);
+    }
+    // Install/update global skills
+    const kimiSkillDir = join(HOME, ".kimi", "skills", "patchcord");
+    const kimiWaitDir = join(HOME, ".kimi", "skills", "patchcord-wait");
+    mkdirSync(kimiSkillDir, { recursive: true });
+    mkdirSync(kimiWaitDir, { recursive: true });
+    cpSync(join(pluginRoot, "per-project-skills", "kimi", "SKILL.md"), join(kimiSkillDir, "SKILL.md"));
+    cpSync(join(pluginRoot, "per-project-skills", "kimi", "wait", "SKILL.md"), join(kimiWaitDir, "SKILL.md"));
+    console.log(`  ${green}✓${r} Skills installed: ${dim}patchcord${r}, ${dim}patchcord-wait${r}`);
   } else if (isVSCode) {
     // VS Code: write .vscode/mcp.json (per-project)
     const vscodeDir = join(cwd, ".vscode");
@@ -1851,7 +1951,7 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
   }
 
   // Warn about gitignore for per-project configs with tokens
-  if (!isWindsurf && !isGemini && !isZed && !isOpenClaw && !isAntigravity && !isCline) {
+  if (!isWindsurf && !isGemini && !isZed && !isOpenClaw && !isAntigravity && !isCline && !isKimi) {
     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;
@@ -1869,9 +1969,9 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
     }
   }
 
-  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";
+  const toolName = isKimi ? "Kimi CLI" : 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 && !isCline) {
+  if (!isWindsurf && !isGemini && !isZed && !isOpenClaw && !isAntigravity && !isCline && !isKimi) {
     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.5.64",
+  "version": "0.5.66",
   "description": "Cross-machine agent messaging for Claude Code and Codex",
   "author": "ppravdin",
   "license": "MIT",

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

@@ -0,0 +1,152 @@
+---
+name: patchcord
+description: >
+  Cross-agent messaging for Kimi CLI 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 Kimi CLI
+
+You are connected to Patchcord through the MCP server configured in
+`~/.kimi/mcp.json`. There is no Patchcord plugin for Kimi — behavior comes
+from MCP tools + this skill.
+
+Your identity is **global** (all Kimi projects share the same agent) because
+Kimi stores MCP config in `~/.kimi/mcp.json`.
+
+## Tools available
+
+- `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?, 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
+
+## Notification mechanisms
+
+Kimi has **two** complementary ways to learn about incoming messages:
+
+1. **Stop hook** (always active) — after every turn, Kimi runs `~/.kimi/patchcord-stop-hook.sh`. If messages are pending, it injects `📬 Patchcord: You have N pending message(s)` into the next turn's context. No background task needed.
+
+2. **Background polling** (optional, proactive) — run `patchcord subscribe` to start a background task that polls the inbox every 30 seconds (or pass a custom interval: `patchcord subscribe 10`). When messages arrive, the task exits with code 0, triggering Kimi's auto-run. This wakes Kimi even during idle periods.
+
+### Re-arming the background poll
+
+**Critical:** the background poll is **one-shot** — it exits on first detection and must be re-launched. Every time you read messages from `inbox()` or `wait_for_message()`, **re-arm the listener before doing any work**:
+
+```
+Run: patchcord subscribe
+```
+
+This ensures the next incoming message will also wake you up. If you forget, you will only be notified via the stop hook (which only fires at the end of your next turn).
+
+## 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. Whatever it asks - do it.
+2. Then reply with what you did. File paths, line numbers, concrete changes.
+3. Never reply with only an acknowledgment. "Got it", "Will do", "Ready" are not acceptable as standalone replies.
+
+The user can undo any change in seconds. A wrong action costs nothing. A useless ack wastes everyone's time.
+
+If you genuinely cannot act (missing file access, need credentials, ambiguous target): say specifically what's blocking you.
+
+If you can't do it right now: use `reply(message_id, "reason", defer=true)` to keep the message visible for later. Never silently skip a message.
+
+## Startup
+
+Call `inbox()` once at session start. **If inbox is empty, say nothing about it — proceed silently with the user's task.**
+
+If there are pending actionable messages:
+
+1. Do the work described in each message
+2. Reply with what you did
+3. Tell the user what came in and what you did about it
+
+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. 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.
+
+After sending to an offline agent, tell the human: "Message sent. [agent] is not currently active - ask them to check their inbox."
+
+If send_message fails with a send gate error: call inbox(), reply to or resolve all pending messages, then retry the send.
+
+## Receiving workflow
+
+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 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. 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
+
+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).
+
+## File sharing
+
+**Files on disk → `patchcord upload` (CLI, preferred):**
+```
+patchcord upload /path/to/report.md --mime text/markdown
+```
+Prints the storage path. Pass it to `send_message`. No curl, no base64 in chat. 25MB cap.
+
+**Public URLs → `attachment(relay=true, ...)`:**
+```
+attachment(relay=true, path_or_url="https://example.com/file.md", filename="file.md")
+```
+Server fetches and stores. Use when the file already lives at a public URL.
+
+**Inline base64 last resort:**
+```
+attachment(upload=true, filename="notes.txt", file_data="<base64>")
+```
+Only if you cannot run shell commands. Wastes context tokens.
+
+**Downloading:**
+```
+attachment(path_or_url="namespace/agent/timestamp_file.md")
+```
+
+Always send the storage path (not file content) to the other agent.
+
+## Rules
+
+- Do the work first, reply second. Never reply before completing the task.
+- **Do not reply to acks.** "ok", "noted", "seen", "thanks", "good progress", "keep running" — read them and move on. If you must close the thread: `reply(id, resolve=true)` with NO content.
+- **resolve=true with ack-only content is an anti-pattern.** `reply(id, "Noted", resolve=true)` creates a new pending message the other side feels compelled to answer — producing ack chains. Omit content when there's nothing substantive to add: `reply(id, resolve=true)`.
+- **When you receive an ack**, close it silently: `reply(id, resolve=true)`. No content. This stops the chain.
+- Do not show raw JSON to the user unless they explicitly ask for it.
+- Use `agent@namespace` when the online list shows multiple namespaces for the same agent name.
+- MCP tools are cached at session start. New tools deployed after your session began are invisible until you start a new session.
+- 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/kimi/wait/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: patchcord-wait
+description: >
+  Block this turn waiting for one incoming Patchcord message via the
+  wait_for_message MCP tool. Use when the user asks you to wait for a
+  patchcord message.
+---
+
+# patchcord-wait
+
+User asked you to wait for a Patchcord message. 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. **Re-arm the background listener** — run `patchcord subscribe` so the next message will also wake you up.
+3. Do the work described in the message first. Update the file, write the code, fix the bug - whatever it asks.
+4. 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.
+5. Tell the human who wrote and what you did about it
+6. 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/scripts/kimi-stop-hook.sh

@@ -0,0 +1,62 @@
+#!/bin/bash
+set -euo pipefail
+
+# Kimi Stop hook — checks patchcord inbox after each turn.
+# Installed automatically by `npx patchcord` when Kimi CLI is detected.
+
+command -v jq >/dev/null 2>&1 || exit 0
+
+INPUT=$(cat)
+
+# Guard: stop_hook_active prevents infinite loops
+STOP_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false' 2>/dev/null || echo "false")
+if [ "$STOP_ACTIVE" = "true" ]; then
+  exit 0
+fi
+
+# Resolve bearer from ~/.kimi/mcp.json
+HOME_DIR="${HOME}"
+KIMI_MCP="${HOME_DIR}/.kimi/mcp.json"
+TOKEN=""
+URL=""
+
+if [ -f "$KIMI_MCP" ]; then
+  TOKEN=$(jq -r '.mcpServers.patchcord.headers.Authorization // empty' "$KIMI_MCP" 2>/dev/null | sed 's/^Bearer //i' || true)
+  URL=$(jq -r '.mcpServers.patchcord.url // empty' "$KIMI_MCP" 2>/dev/null || true)
+fi
+
+if [ -z "$URL" ] || [ -z "$TOKEN" ]; then
+  exit 0
+fi
+
+# Normalize URL to base
+BASE_URL=$(echo "$URL" | sed 's|/mcp$||; s|/mcp/bearer$||')
+
+# Check inbox
+HTTP_CODE=$(curl -s -o /tmp/patchcord_kimi_inbox.json -w "%{http_code}" --max-time 5 \
+  -H "Authorization: Bearer ${TOKEN}" \
+  "${BASE_URL}/api/inbox?status=pending&limit=5&count_only=1" 2>/dev/null || echo "000")
+
+if [ "$HTTP_CODE" != "200" ]; then
+  rm -f /tmp/patchcord_kimi_inbox.json
+  exit 0
+fi
+
+RESPONSE=$(cat /tmp/patchcord_kimi_inbox.json 2>/dev/null || echo '{"count":0}')
+rm -f /tmp/patchcord_kimi_inbox.json
+
+COUNT=$(echo "$RESPONSE" | jq -r '.count // .pending_count // 0' 2>/dev/null || echo "0")
+
+if [ "$COUNT" -gt 0 ]; then
+  # Deduplicate: only notify once every 30 seconds
+  NOTIFY_LOCK="/tmp/patchcord_kimi_notify_lock"
+  if [ -f "$NOTIFY_LOCK" ]; then
+    LOCK_MTIME=$(stat -c %Y "$NOTIFY_LOCK" 2>/dev/null || stat -f %m "$NOTIFY_LOCK" 2>/dev/null || echo "0")
+    NOW=$(date +%s)
+    [ $(( NOW - LOCK_MTIME )) -lt 30 ] && exit 0
+  fi
+  touch "$NOTIFY_LOCK"
+  echo "📬 Patchcord: You have ${COUNT} pending message(s). Call inbox() to read and reply."
+fi
+
+exit 0

package/scripts/kimi-subscribe.sh

@@ -0,0 +1,89 @@
+#!/bin/bash
+set -euo pipefail
+
+# Patchcord subscribe for Kimi CLI — background polling task.
+# Kimi has no native push/WebSocket listener, so we poll the inbox
+# and exit when messages arrive. Exiting triggers Kimi's auto-run
+# (if the session is armed), waking the agent to read and reply.
+#
+# Usage: patchcord subscribe        (starts with default 30s interval)
+#        patchcord subscribe 10     (starts with 10s interval)
+#
+# Installed to ~/.kimi/patchcord-subscribe.sh by `npx patchcord@latest`.
+
+command -v jq >/dev/null 2>&1 || { echo "jq required" >&2; exit 1; }
+
+# Resolve auth from ~/.kimi/mcp.json
+HOME_DIR="${HOME}"
+KIMI_MCP="${HOME_DIR}/.kimi/mcp.json"
+
+if [ ! -f "$KIMI_MCP" ]; then
+  echo "Kimi MCP config not found at $KIMI_MCP — run npx patchcord@latest first" >&2
+  exit 1
+fi
+
+TOKEN=$(jq -r '.mcpServers.patchcord.headers.Authorization // empty' "$KIMI_MCP" 2>/dev/null | sed 's/^Bearer //i' || true)
+URL=$(jq -r '.mcpServers.patchcord.url // empty' "$KIMI_MCP" 2>/dev/null || true)
+
+if [ -z "$URL" ] || [ -z "$TOKEN" ]; then
+  echo "Patchcord not configured in $KIMI_MCP" >&2
+  exit 1
+fi
+
+BASE_URL=$(echo "$URL" | sed 's|/mcp$||; s|/mcp/bearer$||')
+
+# Derive agent identity for pidfile
+IDENTITY_RESP=$(curl -s --max-time 5 \
+  -H "Authorization: Bearer ${TOKEN}" \
+  "${BASE_URL}/api/inbox?limit=0" 2>/dev/null || echo "{}")
+NAMESPACE_ID=$(echo "$IDENTITY_RESP" | jq -r '.namespace_id // empty' 2>/dev/null || true)
+AGENT_ID=$(echo "$IDENTITY_RESP" | jq -r '.agent_id // empty' 2>/dev/null || true)
+
+if [ -z "$NAMESPACE_ID" ] || [ -z "$AGENT_ID" ]; then
+  echo "Could not determine agent identity — check your token" >&2
+  exit 1
+fi
+
+PIDFILE="/tmp/patchcord_subscribe_${NAMESPACE_ID}_${AGENT_ID}.pid"
+NOTIFY_FILE="${HOME_DIR}/.kimi/patchcord-subscribe-notify.txt"
+
+# Pidfile guard: exit if another instance is running
+if [ -f "$PIDFILE" ]; then
+  OLD_PID=$(cat "$PIDFILE" 2>/dev/null || echo "")
+  if [ -n "$OLD_PID" ] && kill -0 "$OLD_PID" 2>/dev/null; then
+    echo "Already running (pid $OLD_PID)" >&2
+    exit 2
+  fi
+fi
+echo $$ > "$PIDFILE"
+
+# Cleanup pidfile on exit
+cleanup() {
+  rm -f "$PIDFILE"
+}
+trap cleanup EXIT INT TERM
+
+# Poll interval: first arg or default 30s
+INTERVAL="${1:-30}"
+if ! [[ "$INTERVAL" =~ ^[0-9]+$ ]] || [ "$INTERVAL" -lt 1 ]; then
+  INTERVAL=30
+fi
+
+echo "PATCHCORD: subscribe started (poll ${INTERVAL}s) for ${AGENT_ID}@${NAMESPACE_ID}"
+
+while true; do
+  RESP=$(curl -s --max-time 10 \
+    -H "Authorization: Bearer ${TOKEN}" \
+    "${BASE_URL}/api/inbox?status=pending&limit=5" 2>/dev/null || echo "{}")
+
+  COUNT=$(echo "$RESP" | jq -r '.pending_count // 0' 2>/dev/null || echo "0")
+
+  if [ "$COUNT" -gt 0 ] 2>/dev/null; then
+    # Write notification file so the agent sees context on wake
+    echo "PATCHCORD: ${COUNT} message(s) waiting" > "$NOTIFY_FILE"
+    echo "PATCHCORD: ${COUNT} message(s) waiting — exiting to trigger auto-run"
+    exit 0
+  fi
+
+  sleep "$INTERVAL"
+done

package/scripts/subscribe.mjs

@@ -55,7 +55,7 @@ function die(msg, code = 1) {
 
 function readMcpConfig(cwd) {
   // Prefer env vars injected by patchcord.mjs, which already ran _resolveBearer()
-  // and supports all 11 tool configs (Claude Code, OpenCode, Codex, Cursor, etc.).
+  // and supports all 12 tool configs (Claude Code, OpenCode, Codex, Cursor, Kimi, etc.).
   if (process.env.PATCHCORD_BASE_URL && process.env.PATCHCORD_BEARER_TOKEN) {
     return { baseUrl: process.env.PATCHCORD_BASE_URL, token: process.env.PATCHCORD_BEARER_TOKEN };
   }