patchcord 0.5.65 → 0.5.67

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
@@ -194,6 +194,8 @@ async function _resolveBearer() {
     (cwd) => readJsonAt(join(cwd, ".vscode", "mcp.json"), ["servers", "patchcord"], "vscode"),
     (cwd) => readJsonAt(join(cwd, "opencode.json"), ["mcp", "patchcord"], "opencode"),
     (cwd) => readCodexTomlShape(join(cwd, ".codex", "config.toml")),
+    // Kimi can be per-project via .kimi/mcp.json + --mcp-config-file
+    (cwd) => readJsonAt(join(cwd, ".kimi", "mcp.json"), ["mcpServers", "patchcord"], "kimi"),
   ];
   let dir = process.cwd();
   while (dir && dir !== "/") {
@@ -240,6 +242,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")),
+    // Global Kimi fallback (only if no per-project .kimi/mcp.json was found)
     () => readJsonAt(join(HOME, ".kimi", "mcp.json"), ["mcpServers", "patchcord"], "kimi"),
   ];
   for (const r of globalCandidates) {
@@ -463,12 +466,30 @@ if (cmd === "upload") {
 // 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;
@@ -955,15 +976,52 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
     let kimiChanged = false;
     if (!existsSync(kimiSkillDir)) {
       mkdirSync(kimiSkillDir, { recursive: true });
-      cpSync(join(pluginRoot, "skills", "inbox", "SKILL.md"), join(kimiSkillDir, "SKILL.md"));
+      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, "skills", "wait", "SKILL.md"), join(kimiWaitDir, "SKILL.md"));
+      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
@@ -1141,10 +1199,12 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
     let existingConfigFile = "";
     const mcpJsonPath = join(cwd, ".mcp.json");
     const codexTomlPath = join(cwd, ".codex", "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 checkKimiJson = !slugForCheck || slugForCheck === "kimi";
 
     if (checkMcpJson && existsSync(mcpJsonPath)) {
       try {
@@ -1166,12 +1226,23 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
         }
       } catch {}
     }
+    if (!existingToken && checkKimiJson && existsSync(kimiJsonPath)) {
+      try {
+        const existing = JSON.parse(readFileSync(kimiJsonPath, "utf-8"));
+        const pt = existing?.mcpServers?.patchcord;
+        if (pt?.headers?.Authorization) {
+          existingToken = pt.headers.Authorization.replace(/^Bearer\s+/i, "");
+          existingConfigFile = kimiJsonPath;
+        }
+      } catch {}
+    }
     // Global configs (Antigravity, OpenClaw, Gemini, Windsurf, Zed) are NOT
     // checked here. They're set up once globally and should not block new
     // project setup. Only per-project configs trigger "already configured."
     if (existingToken) {
       // Figure out which tool is already configured
-      const existingToolName = existingConfigFile.includes(".codex") ? "Codex"
+      const existingToolName = existingConfigFile.includes(".kimi") ? "Kimi CLI"
+        : existingConfigFile.includes(".codex") ? "Codex"
         : existingConfigFile.includes("antigravity") ? "Antigravity"
         : existingConfigFile.includes("openclaw") ? "OpenClaw"
         : existingConfigFile.includes(".cursor") ? "Cursor"
@@ -1646,8 +1717,9 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
       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");
+    // Kimi CLI: per-project .kimi/mcp.json + shell wrapper for --mcp-config-file
+    const kimiDir = join(cwd, ".kimi");
+    const kimiPath = join(kimiDir, "mcp.json");
     const kimiOk = updateJsonConfig(kimiPath, (obj) => {
       obj.mcpServers = obj.mcpServers || {};
       obj.mcpServers.patchcord = {
@@ -1660,16 +1732,48 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
     });
     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}`);
+      console.log(`  ${dim}Per-project — use the kimi-pc wrapper (see below) so Kimi loads this config.${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, "skills", "inbox", "SKILL.md"), join(kimiSkillDir, "SKILL.md"));
-    cpSync(join(pluginRoot, "skills", "wait", "SKILL.md"), join(kimiWaitDir, "SKILL.md"));
+    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}`);
+
+    // Install shell wrapper for per-project --mcp-config-file
+    const wrapperPath = join(HOME, ".kimi", "patchcord-kimi-wrapper.sh");
+    const wrapperAlreadyExisted = existsSync(wrapperPath);
+    const wrapperContent = `#!/bin/bash
+# Patchcord Kimi wrapper — auto-detects per-project .kimi/mcp.json
+# Source this in your ~/.bashrc or ~/.zshrc:
+#   source "${HOME}/.kimi/patchcord-kimi-wrapper.sh"
+#
+# Then launch Kimi in any project with:
+#   kimi-pc
+#
+# Plain \`kimi\` still uses the global ~/.kimi/mcp.json.
+
+kimi-pc() {
+  local dir="$PWD"
+  while [ "$dir" != "/" ]; do
+    if [ -f "$dir/.kimi/mcp.json" ]; then
+      kimi --mcp-config-file "$dir/.kimi/mcp.json" "$@"
+      return
+    fi
+    dir="$(dirname "$dir")"
+  done
+  echo "No .kimi/mcp.json found in $PWD or any parent — falling back to global config" >&2
+  kimi "$@"
+}
+`;
+    writeFileSync(wrapperPath, wrapperContent);
+    console.log(`\n  ${green}✓${r} Shell wrapper installed: ${dim}${wrapperPath}${r}`);
+    console.log(`  ${dim}Add this to your ~/.bashrc or ~/.zshrc:${r}`);
+    console.log(`  ${cyan}source "${wrapperPath}"${r}`);
+    console.log(`  ${dim}Then run ${bold}kimi-pc${r}${dim} instead of ${bold}kimi${r}${dim} in project directories.${r}`);
   } else if (isVSCode) {
     // VS Code: write .vscode/mcp.json (per-project)
     const vscodeDir = join(cwd, ".vscode");

package/package.json

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

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

@@ -0,0 +1,166 @@
+---
+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` inside your project directory. Kimi normally uses a global
+config, but Patchcord sets up **per-project agents** via `--mcp-config-file`.
+
+**Launch Kimi in project directories with `kimi-pc`** (not plain `kimi`).
+This wrapper auto-detects `.kimi/mcp.json` in the current project and loads
+the right agent identity.
+
+```bash
+# In any project with .kimi/mcp.json:
+kimi-pc
+
+# Falls back to global ~/.kimi/mcp.json if no project config found.
+```
+
+Add this to your `~/.bashrc` or `~/.zshrc` (done once by the installer):
+```bash
+source "$HOME/.kimi/patchcord-kimi-wrapper.sh"
+```
+
+## 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`. It detects the project from `cwd` in stdin, walks up looking for `.kimi/mcp.json`, then checks the inbox. 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. **Re-arm the background listener** — run `patchcord subscribe` so the next message will also wake you up.
+3. Do the work - use real code, real files, real results from your project
+4. 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.
+5. 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,82 @@
+#!/bin/bash
+set -euo pipefail
+
+# Kimi Stop hook — checks patchcord inbox after each turn.
+# Installed automatically by `npx patchcord` when Kimi CLI is detected.
+#
+# Supports per-project .kimi/mcp.json (walks up from cwd) and
+# falls back to global ~/.kimi/mcp.json.
+
+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 MCP config: per-project first, then global
+KIMI_MCP=""
+CWD=$(echo "$INPUT" | jq -r '.cwd // empty' 2>/dev/null || echo "")
+
+if [ -n "$CWD" ]; then
+  dir="$CWD"
+  while [ "$dir" != "/" ]; do
+    if [ -f "$dir/.kimi/mcp.json" ]; then
+      KIMI_MCP="$dir/.kimi/mcp.json"
+      break
+    fi
+    dir=$(dirname "$dir")
+  done
+fi
+
+# Fallback to global config
+if [ -z "$KIMI_MCP" ]; then
+  KIMI_MCP="${HOME}/.kimi/mcp.json"
+fi
+
+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,102 @@
+#!/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)
+#
+# Supports per-project .kimi/mcp.json (walks up from cwd) and
+# falls back to global ~/.kimi/mcp.json.
+
+command -v jq >/dev/null 2>&1 || { echo "jq required" >&2; exit 1; }
+
+# Resolve MCP config: per-project first, then global
+KIMI_MCP=""
+dir="$PWD"
+while [ "$dir" != "/" ]; do
+  if [ -f "$dir/.kimi/mcp.json" ]; then
+    KIMI_MCP="$dir/.kimi/mcp.json"
+    break
+  fi
+  dir=$(dirname "$dir")
+done
+
+# Fallback to global config
+if [ -z "$KIMI_MCP" ]; then
+  KIMI_MCP="${HOME}/.kimi/mcp.json"
+fi
+
+if [ ! -f "$KIMI_MCP" ]; then
+  echo "Kimi MCP config not found at $KIMI_MCP or any parent — 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}/.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