opencode-mux 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 opencode-mux contributors
+
+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,173 @@
+# opencode-mux
+
+A drop-in wrapper for [opencode](https://opencode.ai) that opens tmux panes for
+subagent sessions automatically — and makes the whole layout look coherent no
+matter what your tmux is configured to look like.
+
+When a session running inside opencode-mux spawns a subagent, a new tmux pane
+opens showing that session live. When the subagent finishes, the pane closes
+itself. The subagent panes run opencode's minimal `mini` frontend, so they show
+nothing but the conversation — no tab bar, no agent switcher.
+
+```
+┌──────────────────────────────────────────┬──────────────┐
+│                                          │ subagent     │
+│   main opencode session                  │ (mini UI)   │
+│   (full TUI)                             ├──────────────┤
+│                                          │ subagent     │
+│                                          │ (mini UI)    │
+└──────────────────────────────────────────┴──────────────┘
+```
+
+- **Drop-in** — run it exactly like `opencode`; every other argument is passed
+  through unchanged.
+- **Zero config intrusion** — never writes tmux `-g` options and never touches
+  your `~/.tmux.conf`, `~/.config/opencode/cli.json`, or `tui.json`.
+- **Coherent look** — pane borders are styled to match your active opencode
+  theme, and the session opts are scoped to the mux session only.
+
+## Requirements
+
+| Tool | Version |
+| ---- | ------- |
+| Node.js | >= 20 |
+| tmux | 3.x (tested on 3.7) |
+| opencode | v2 (2.0.0–2.0.5 and 2.0.6+ both supported) |
+
+## Install
+
+```sh
+npm install -g opencode-mux
+```
+
+To use it as your default `opencode`:
+
+```sh
+alias opencode="opencode-mux"
+```
+
+(binaries are `opencode-mux`, version `0.1.0`)
+
+## Usage
+
+```sh
+opencode-mux [mux options] [opencode arguments...]
+```
+
+### Examples
+
+```sh
+# Just work in the current directory
+opencode-mux
+
+# Continue an existing session
+opencode-mux -s ses_abc123
+
+# Pass opencode's own flags through, with a tiled pane layout
+opencode-mux --layout tiled --model fast
+
+# Running inside an existing tmux session also works — subagent panes are
+# opened in the session you're already in, and already-running subagents are
+# adopted without a startup flash.
+```
+
+### Mux options
+
+| Option | Description | Default |
+| ------ | ----------- | ------- |
+| `--config <path>` | Config file to use | `~/.config/opencode-mux.conf` |
+| `--layout <name>` | Pane layout: `main-vertical`, `main-horizontal`, `tiled`, `even-horizontal`, `even-vertical` | `main-vertical` |
+| `--main-pane-size <pct>` | Main pane size for `main-*` layouts, percent of the window | `60` |
+| `--close <mode>` | Pane lifecycle: `auto` (close when the subagent finishes) or `keep` | `auto` |
+| `--grace <seconds>` | Delay before a finished subagent's pane closes | `1` |
+| `--parent <id>` | Only spawn panes for children of this session | inferred from `-s`/`--session` |
+| `--session-name <name>` | Owned tmux session name (when starting outside tmux) | `mux` |
+| `-h`, `--help` | Show help | |
+| `--version` | Print the version | |
+
+Everything else (e.g. `--model`, `--agent`, `-i` prompts, a directory) is passed
+through to opencode unchanged.
+
+## Config file
+
+`~/.config/opencode-mux.conf` (honors `XDG_CONFIG_HOME`) is optional and is
+auto-created with defaults on first run. Keys are `key=value`, lines starting
+with `#` are comments, and unknown keys are ignored for forward compatibility.
+
+```ini
+# opencode-mux configuration
+session_name=mux
+layout=main-vertical
+main_pane_size=60
+close_panes=auto
+grace=1
+parent=
+```
+
+Precedence: **CLI flags > config file > defaults**.
+
+## How it works
+
+- **Outside tmux**: opencode-mux creates a detached tmux session named
+  `mux` (or `--session-name`), applies session-scoped `status off` and
+  `mouse on`, re-executes itself inside, and attaches. When the main TUI
+  exits, the owned session is cleaned up.
+- **Inside tmux**: the wrapper runs as a watcher. It connects to the opencode
+  server (same background service you're already using), listens for
+  subagent-session events, opens a pane per child session via
+  `opencode mini -s <id>`, styles the pane borders to match the active
+  opencode theme, and closes panes once their session finishes (after the
+  grace period).
+
+## Features
+
+### Subagent panes without the chrome
+
+Subagent panes attach with `opencode mini`, the minimal frontend: no top tab
+strip, no agent switcher or model panel — just the conversation and a one-line
+footer. It streams live updates while the subagent works, accepts input, and
+stays attached until the watcher closes the pane.
+
+### Theme-matched borders
+
+Pane borders follow your active opencode theme (`border.default`, falling back
+to the border color). Paraphrased, it looks good no matter what anyone has
+configured their setup to look like:
+
+- Theme is resolved from your opencode config: project
+  `.opencode/cli.json` → project `.opencode/tui.json` → global `cli.json` →
+  global `tui.json` (first match wins; v2 object and legacy string forms both
+  supported).
+- Built-in themes come from a vendored table of all opencode v2.0.5 built-in
+  themes; custom theme files are resolved from your config/theme dirs.
+- A `system` theme or an unknown/unresolvable theme results in **no border
+  styling** — never wrong colors.
+- Config changes are re-applied live (checked on the watcher tick), and
+  borders are cleared when the theme becomes unresolvable. Zero tmux calls
+  while nothing changed.
+
+### Never touches your setup
+
+All tmux writes are runtime-scoped: window options are applied with `-w`
+(pane-border colors) and session options with `-t <session>` (status/mouse).
+No `-g`, no writes to `~/.tmux.conf`, no changes to your opencode configs.
+
+## Requirements & compatibility
+
+- Handles opencode's two v2 server generations transparently: 2.0.0–2.0.5
+  (`/api/status`) and 2.0.6+ (`/api/info`).
+- Depends on tmux; fails with a clear error if tmux or opencode v2 is missing.
+
+## Development
+
+```sh
+npm install
+npm run check   # typecheck (tsc --noEmit)
+npm test        # vitest suite
+npm run build   # tsc -p tsconfig.build.json → dist/
+npm run smoke   # e2e smoke (needs a staging environment; blocked locally)
+```
+
+## License
+
+MIT

package/dist/args.d.ts

@@ -0,0 +1,12 @@
+import type { CliFlags } from "./config.js";
+export interface ParsedArgs {
+    flags: CliFlags;
+    configPath?: string;
+    help: boolean;
+    version: boolean;
+    watch: boolean;
+    passThrough: string[];
+}
+export declare function parseArgs(argv: string[]): ParsedArgs;
+/** Returns the parent session id from pass-through `-s`/`--session` opencode args, else null. */
+export declare function parentFromPassThrough(passThrough: string[]): string | null;

package/dist/args.js

@@ -0,0 +1,114 @@
+const LAYOUTS = new Set(["main-vertical", "main-horizontal", "tiled", "even-horizontal", "even-vertical"]);
+const CLOSE_MODES = new Set(["auto", "keep"]);
+export function parseArgs(argv) {
+    const out = { flags: {}, help: false, version: false, watch: false, passThrough: [] };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--mux-watch") {
+            out.watch = true;
+            continue;
+        }
+        if (arg === "-h" || arg === "--help") {
+            out.help = true;
+            continue;
+        }
+        if (arg === "--version") {
+            out.version = true;
+            continue;
+        }
+        const eq = arg.indexOf("=");
+        const name = eq >= 0 ? arg.slice(0, eq) : arg;
+        const inline = eq >= 0 ? arg.slice(eq + 1) : null;
+        const value = () => {
+            if (inline !== null)
+                return inline;
+            const next = argv[i + 1];
+            if (next !== undefined && !next.startsWith("-")) {
+                i++;
+                return next;
+            }
+            return null;
+        };
+        switch (name) {
+            case "--config": {
+                const v = value();
+                if (v === null)
+                    throw new Error("opencode-mux: --config requires a path");
+                out.configPath = v;
+                break;
+            }
+            case "--layout": {
+                const v = value();
+                if (v === null || !LAYOUTS.has(v)) {
+                    throw new Error("opencode-mux: --layout requires main-vertical | main-horizontal | tiled | even-horizontal | even-vertical");
+                }
+                out.flags.layout = v;
+                break;
+            }
+            case "--main-pane-size": {
+                const v = value();
+                const n = v === null ? Number.NaN : Number(v);
+                if (!Number.isFinite(n) || n < 20 || n > 80) {
+                    throw new Error("opencode-mux: --main-pane-size requires a number between 20 and 80");
+                }
+                out.flags.mainPaneSize = Math.floor(n);
+                break;
+            }
+            case "--close": {
+                const v = value();
+                if (v === null || !CLOSE_MODES.has(v)) {
+                    throw new Error("opencode-mux: --close requires auto | keep");
+                }
+                out.flags.closePanes = v;
+                break;
+            }
+            case "--grace": {
+                const v = value();
+                const n = v === null ? Number.NaN : Number(v);
+                if (!Number.isFinite(n) || n < 0) {
+                    throw new Error("opencode-mux: --grace requires a non-negative number of seconds");
+                }
+                out.flags.graceSeconds = Math.floor(n);
+                break;
+            }
+            case "--parent": {
+                const v = value();
+                if (v === null)
+                    throw new Error("opencode-mux: --parent requires a session id");
+                out.flags.parent = v === "" ? null : v;
+                break;
+            }
+            case "--session-name": {
+                const v = value();
+                if (v === null || v === "")
+                    throw new Error("opencode-mux: --session-name requires a name");
+                out.flags.sessionName = v;
+                break;
+            }
+            default:
+                if (name.startsWith("--mux-")) {
+                    throw new Error(`opencode-mux: unknown flag ${name}`);
+                }
+                out.passThrough.push(arg);
+        }
+    }
+    return out;
+}
+/** Returns the parent session id from pass-through `-s`/`--session` opencode args, else null. */
+export function parentFromPassThrough(passThrough) {
+    for (let i = 0; i < passThrough.length; i++) {
+        const arg = passThrough[i];
+        if (arg === "-s" || arg === "--session") {
+            const next = passThrough[i + 1];
+            if (next !== undefined && next.startsWith("ses_"))
+                return next;
+        }
+        if (arg.startsWith("--session=")) {
+            const id = arg.slice("--session=".length);
+            if (id.startsWith("ses_"))
+                return id;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=args.js.map

package/dist/args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"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"}

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { fileURLToPath } from "node:url";
+import { main, nodeSpawn } from "./cli.js";
+try {
+    process.exitCode = await main(process.argv.slice(2), {
+        env: process.env,
+        spawn: nodeSpawn,
+        entryPath: fileURLToPath(new URL("./bin.js", import.meta.url)),
+    });
+}
+catch (error) {
+    console.error(String(error));
+    process.exitCode = 1;
+}
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE3C,IAAI,CAAC;IACH,OAAO,CAAC,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;QACnD,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,KAAK,EAAE,SAAS;QAChB,SAAS,EAAE,aAAa,CAAC,IAAI,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;KAC/D,CAAC,CAAC;AACL,CAAC;AAAC,OAAO,KAAK,EAAE,CAAC;IACf,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAC7B,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,62 @@
+import type { CliFlags } from "./config.js";
+import type { ConnectServerDeps, ServerConnection, ServiceGeneration } from "./server.js";
+export interface SpawnResult {
+    ok: boolean;
+    code: number | null;
+    error: string | null;
+    stdout: string;
+    stderr: string;
+}
+export interface SpawnOpts {
+    stdoutFile?: string;
+    stderrFile?: string;
+    inherit?: boolean;
+}
+export interface SpawnHandle {
+    pid: number | null;
+    done: Promise<SpawnResult>;
+    kill(): void;
+}
+export type SpawnFn = (command: string, args: string[], opts?: SpawnOpts) => SpawnHandle;
+/** Real subprocess launcher with optional file redirects (never throws). */
+export declare function nodeSpawn(command: string, args: string[], opts?: SpawnOpts): SpawnHandle;
+export interface CliDeps {
+    env: NodeJS.ProcessEnv;
+    spawn: SpawnFn;
+    entryPath: string;
+    opencodeCommand?: string;
+    nodeCommand?: string;
+    tmuxCommand?: string;
+    cwd?: string;
+    /** Injectable so the watcher path is unit-testable; defaults to the real server connection. */
+    connectServer?: (deps?: ConnectServerDeps) => Promise<ServerConnection>;
+}
+export declare function usageText(): string;
+export declare function watchLogPath(env: NodeJS.ProcessEnv): string;
+/** Parses "2.0.5" or "opencode v2.0.5" into the major version; junk → null. */
+export declare function parseMajorVersion(version: string): number | null;
+/**
+ * Maps an opencode version to the client protocol generation it speaks: 2.0.0–2.0.5
+ * serve GET /api/status (legacy), 2.0.6+ serve GET /api/info (new). Each client
+ * generation's Service.ensure() probes only its own endpoint and stops a mismatched
+ * registered server, so the binary's generation must select the matching client.
+ * Returns null for unsupported or unparseable versions.
+ */
+export declare function serviceGeneration(version: string): ServiceGeneration | null;
+/** Re-emits resolved CLI flags as mux argv (for the watcher child process). */
+export declare function flagsToArgv(flags: CliFlags): string[];
+/** argv for the spawned watcher process: marker + config path + explicit flags. */
+export declare function buildWatcherArgv(opts: {
+    configPath?: string;
+    flags: CliFlags;
+}): string[];
+/** argv the re-exec'd instance runs inside the fresh tmux session. */
+export declare function buildReexecArgv(entryPath: string, originalArgv: string[]): string[];
+/** tmux new-session argv that boots the detached session and its command. */
+export declare function buildNewSessionCommand(input: {
+    entryPath: string;
+    originalArgv: string[];
+    sessionName: string;
+    cwd: string;
+}): string[];
+export declare function main(argv: string[], deps: CliDeps): Promise<number>;