opencode-cmux 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matteo Casonato
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,52 @@
+# opencode-cmux
+
+OpenCode plugin that bridges OpenCode events to cmux notifications and sidebar metadata.
+
+## Requirements
+
+- OpenCode ≥ 1.0
+- [cmux](https://cmux.app) (macOS app) installed with CLI accessible at `/usr/local/bin/cmux`
+- The plugin is a no-op when not running inside a cmux workspace
+
+## Installation
+
+### npm (recommended)
+
+Install the package and add it to `~/.config/opencode/opencode.json`:
+
+```bash
+npm install -g opencode-cmux
+```
+
+```json
+{
+  "plugin": ["opencode-cmux"]
+}
+```
+
+### Local / development
+
+Build the package, then symlink the output directly into OpenCode's plugin directory:
+
+```bash
+ln -sf ~/path/to/opencode-cmux/dist/index.js ~/.config/opencode/plugins/cmux.js
+```
+
+## What it does
+
+| Event | cmux action |
+|---|---|
+| Session starts working | Sidebar status: "working" (amber, terminal icon) |
+| Session completes (primary) | Desktop notification + log + clear status |
+| Session completes (subagent) | Log only (no notification spam) |
+| Session error | Desktop notification + log + clear status |
+| Permission requested | Desktop notification + sidebar status: "waiting" (red, lock icon) |
+| AI has a question (`ask` tool) | Desktop notification + sidebar status: "question" (purple) |
+
+## How it works
+
+The plugin responds to OpenCode lifecycle events by firing cmux CLI commands (`cmux notify`, `cmux set-status`, etc.). Each action targets the current cmux workspace, providing ambient awareness of what OpenCode is doing without requiring you to switch context. All commands are no-ops when cmux is not running.
+
+## License
+
+MIT

package/dist/cmux.d.ts

@@ -0,0 +1,19 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+type Shell = PluginInput["$"];
+export declare function isInCmux(): boolean;
+export declare function notify($: Shell, opts: {
+    title: string;
+    subtitle?: string;
+    body?: string;
+}): Promise<void>;
+export declare function setStatus($: Shell, key: string, text: string, opts?: {
+    icon?: string;
+    color?: string;
+}): Promise<void>;
+export declare function clearStatus($: Shell, key: string): Promise<void>;
+export declare function log($: Shell, message: string, opts?: {
+    level?: "info" | "success" | "error" | "warn";
+    source?: string;
+}): Promise<void>;
+export {};
+//# sourceMappingURL=cmux.d.ts.map

package/dist/cmux.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cmux.d.ts","sourceRoot":"","sources":["../src/cmux.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAEtD,KAAK,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAA;AAE7B,wBAAgB,QAAQ,IAAI,OAAO,CAKlC;AAED,wBAAsB,MAAM,CAC1B,CAAC,EAAE,KAAK,EACR,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACxD,OAAO,CAAC,IAAI,CAAC,CAUf;AAED,wBAAsB,SAAS,CAC7B,CAAC,EAAE,KAAK,EACR,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACvC,OAAO,CAAC,IAAI,CAAC,CAUf;AAED,wBAAsB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOtE;AAED,wBAAsB,GAAG,CACvB,CAAC,EAAE,KAAK,EACR,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACxE,OAAO,CAAC,IAAI,CAAC,CAef"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import type { Plugin } from "@opencode-ai/plugin";
+declare const plugin: Plugin;
+export default plugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAGjD,QAAA,MAAM,MAAM,EAAE,MAqFb,CAAA;AAED,eAAe,MAAM,CAAA"}

package/dist/index.js

@@ -0,0 +1,125 @@
+// src/cmux.ts
+import { existsSync } from "node:fs";
+function isInCmux() {
+  return existsSync(process.env.CMUX_SOCKET_PATH ?? "/tmp/cmux.sock") || !!process.env.CMUX_WORKSPACE_ID;
+}
+async function notify($, opts) {
+  if (!isInCmux())
+    return;
+  try {
+    const args = ["--title", opts.title];
+    if (opts.subtitle !== undefined)
+      args.push("--subtitle", opts.subtitle);
+    if (opts.body !== undefined)
+      args.push("--body", opts.body);
+    await $`cmux notify ${args}`.quiet().nothrow();
+  } catch {}
+}
+async function setStatus($, key, text, opts) {
+  if (!isInCmux())
+    return;
+  try {
+    const args = [key, text];
+    if (opts?.icon !== undefined)
+      args.push("--icon", opts.icon);
+    if (opts?.color !== undefined)
+      args.push("--color", opts.color);
+    await $`cmux set-status ${args}`.quiet().nothrow();
+  } catch {}
+}
+async function clearStatus($, key) {
+  if (!isInCmux())
+    return;
+  try {
+    await $`cmux clear-status ${key}`.quiet().nothrow();
+  } catch {}
+}
+async function log($, message, opts) {
+  if (!isInCmux())
+    return;
+  try {
+    const args = [];
+    if (opts?.level !== undefined) {
+      const level = opts.level === "warn" ? "warning" : opts.level;
+      args.push("--level", level);
+    }
+    if (opts?.source !== undefined)
+      args.push("--source", opts.source);
+    args.push("--", message);
+    await $`cmux log ${args}`.quiet().nothrow();
+  } catch {}
+}
+
+// src/index.ts
+var plugin = async ({ client, $ }) => {
+  async function fetchSession(sessionID) {
+    try {
+      const result = await client.session.get({ path: { id: sessionID } });
+      if (result.data) {
+        return { title: result.data.title, parentID: result.data.parentID };
+      }
+      return null;
+    } catch {
+      return null;
+    }
+  }
+  return {
+    async event({ event }) {
+      if (event.type === "session.status") {
+        const { sessionID, status } = event.properties;
+        if (status.type === "busy") {
+          await setStatus($, "opencode", "working", {
+            icon: "terminal",
+            color: "#f59e0b"
+          });
+          return;
+        }
+        if (status.type === "idle") {
+          const session = await fetchSession(sessionID);
+          const title = session?.title ?? sessionID;
+          if (!session?.parentID) {
+            await notify($, { title: `Done: ${title}` });
+            await log($, `Done: ${title}`, { level: "success", source: "opencode" });
+            await clearStatus($, "opencode");
+          } else {
+            await log($, `Subagent finished: ${title}`, {
+              level: "info",
+              source: "opencode"
+            });
+          }
+          return;
+        }
+      }
+      if (event.type === "session.error") {
+        const sessionID = event.properties.sessionID;
+        const title = sessionID ? (await fetchSession(sessionID))?.title ?? sessionID : "unknown session";
+        await notify($, { title: `Error: ${title}` });
+        await log($, `Error in session: ${title}`, {
+          level: "error",
+          source: "opencode"
+        });
+        await clearStatus($, "opencode");
+      }
+    },
+    async "permission.ask"(input) {
+      await notify($, { title: "Needs your permission", subtitle: input.title });
+      await setStatus($, "opencode", "waiting", {
+        icon: "lock",
+        color: "#ef4444"
+      });
+    },
+    async "tool.execute.before"(input) {
+      if (input.tool === "ask") {
+        await notify($, { title: "Has a question" });
+        await setStatus($, "opencode", "question", {
+          icon: "help-circle",
+          color: "#a855f7"
+        });
+      }
+    }
+  };
+};
+var src_default = plugin;
+export {
+  src_default as default
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "opencode-cmux",
+  "version": "0.1.0",
+  "description": "OpenCode plugin that bridges OpenCode events to cmux notifications and sidebar metadata",
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc --emitDeclarationOnly && bun build src/index.ts --outdir dist --target node",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run typecheck && bun run build"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "cmux"
+  ],
+  "author": "Matteo Casonato",
+  "license": "MIT",
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.0.0"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.2.15",
+    "@types/node": "^25.3.1",
+    "typescript": "^5.9.3"
+  }
+}