@dawsson/mux 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dawson
+
+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,49 @@
+# mux
+
+Configurable tmux session manager for dev workflows. Reads pane config from `package.json` and manages named tmux sessions.
+
+## Install
+
+```bash
+bun install -g mux
+```
+
+Or run directly with `bun run src/cli.ts`.
+
+## Config
+
+Add a `"mux"` key to your project's `package.json`:
+
+```json
+{
+  "mux": {
+    "session": "my-project",
+    "panes": [
+      { "name": "api",  "cmd": "bun run dev",       "cwd": "packages/api" },
+      { "name": "web",  "cmd": "bun run start",      "cwd": "packages/web" },
+      { "name": "expo", "cmd": "bun expo start",     "cwd": "apps/mobile"  }
+    ]
+  }
+}
+```
+
+- `session` — tmux session name (defaults to directory basename)
+- `panes[].name` — pane identifier used in commands
+- `panes[].cmd` — shell command to run in the pane
+- `panes[].cwd` — working directory relative to project root (optional)
+
+## Commands
+
+| Command              | Description                                      |
+|----------------------|--------------------------------------------------|
+| `mux`                | Start session if not running, attach if it is   |
+| `mux start`          | Explicit start, then attach                      |
+| `mux start --detach` | Start in background (no attach), useful for CI  |
+| `mux stop`           | Kill the session                                 |
+| `mux status`         | List panes and their indices                     |
+| `mux logs [pane]`    | Capture pane output (all panes if none given)   |
+| `mux restart [pane]` | Restart a pane (all panes if none given)        |
+
+## Logs
+
+Pane output is available via `mux logs`. Session log files are written to `/tmp/mux-<session>/`.

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@dawsson/mux",
+  "version": "0.1.0",
+  "description": "Configurable tmux session manager for dev workflows",
+  "type": "module",
+  "bin": {
+    "mux": "src/cli.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "bun test"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "bun-types": "^1.3.9"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,137 @@
+#!/usr/bin/env bun
+import { findConfig } from "./config";
+import {
+  hasSession,
+  startSession,
+  killSession,
+  attach,
+  listPanes,
+  capturePane,
+  restartPane,
+} from "./tmux";
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+
+function loadConfig() {
+  try {
+    return findConfig();
+  } catch (e: any) {
+    console.error(`Error: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+function printUsage() {
+  console.log(`mux — configurable tmux session manager
+
+Usage:
+  mux                    Start session if not running, attach if it is
+  mux start [--detach]   Start the session (--detach: don't attach)
+  mux stop               Kill the session
+  mux status             Show running panes
+  mux logs [pane]        Capture pane output (all panes if none specified)
+  mux restart [pane]     Restart a pane or all panes
+`);
+}
+
+if (!cmd || cmd === "start") {
+  const config = loadConfig();
+  const detach = args.includes("--detach");
+
+  if (hasSession(config.session)) {
+    if (!detach) {
+      attach(config.session);
+    } else {
+      console.log(`Session "${config.session}" already running.`);
+    }
+  } else {
+    startSession(config);
+    if (!detach) {
+      attach(config.session);
+    } else {
+      console.log(`Session "${config.session}" started (detached).`);
+    }
+  }
+} else if (cmd === "stop") {
+  const config = loadConfig();
+  if (hasSession(config.session)) {
+    killSession(config.session);
+    console.log(`Session "${config.session}" stopped.`);
+  } else {
+    console.log(`Session "${config.session}" is not running.`);
+  }
+} else if (cmd === "status") {
+  const config = loadConfig();
+  if (!hasSession(config.session)) {
+    console.log(`Session "${config.session}" is not running.`);
+    process.exit(0);
+  }
+  const panes = listPanes(config.session);
+  console.log(`Session: ${config.session}`);
+  for (let i = 0; i < panes.length; i++) {
+    const p = panes[i];
+    const name = config.panes[i]?.name ?? `pane-${i}`;
+    const active = p.active ? " (active)" : "";
+    console.log(`  [${p.index}] ${name}${active}`);
+  }
+} else if (cmd === "logs") {
+  const config = loadConfig();
+  if (!hasSession(config.session)) {
+    console.error(`Session "${config.session}" is not running.`);
+    process.exit(1);
+  }
+  const targetPane = args[1];
+  const panes = listPanes(config.session);
+
+  if (targetPane) {
+    const idx = config.panes.findIndex((p) => p.name === targetPane);
+    if (idx === -1) {
+      console.error(`Unknown pane: ${targetPane}`);
+      process.exit(1);
+    }
+    const pane = panes[idx];
+    if (!pane) {
+      console.error(`Pane ${targetPane} not found in tmux session.`);
+      process.exit(1);
+    }
+    const output = capturePane(pane.id);
+    console.log(`=== ${targetPane} ===`);
+    console.log(output);
+  } else {
+    for (let i = 0; i < panes.length; i++) {
+      const name = config.panes[i]?.name ?? `pane-${i}`;
+      const output = capturePane(panes[i].id);
+      console.log(`=== ${name} ===`);
+      console.log(output);
+      console.log();
+    }
+  }
+} else if (cmd === "restart") {
+  const config = loadConfig();
+  if (!hasSession(config.session)) {
+    console.error(`Session "${config.session}" is not running.`);
+    process.exit(1);
+  }
+  const targetPane = args[1];
+  if (targetPane) {
+    try {
+      restartPane(config, targetPane);
+      console.log(`Restarted pane "${targetPane}".`);
+    } catch (e: any) {
+      console.error(`Error: ${e.message}`);
+      process.exit(1);
+    }
+  } else {
+    for (const pane of config.panes) {
+      restartPane(config, pane.name);
+      console.log(`Restarted pane "${pane.name}".`);
+    }
+  }
+} else if (cmd === "--help" || cmd === "-h" || cmd === "help") {
+  printUsage();
+} else {
+  console.error(`Unknown command: ${cmd}`);
+  printUsage();
+  process.exit(1);
+}

package/src/config.ts

@@ -0,0 +1,57 @@
+import { existsSync, readFileSync } from "fs";
+import { join, dirname, basename } from "path";
+
+export interface PaneConfig {
+  name: string;
+  cmd: string;
+  cwd?: string;
+}
+
+export interface MuxConfig {
+  session: string;
+  panes: PaneConfig[];
+  root: string; // absolute path to the project root (where package.json lives)
+}
+
+interface RawMuxConfig {
+  session?: string;
+  panes?: unknown[];
+}
+
+export function findConfig(from: string = process.cwd()): MuxConfig {
+  let dir = from;
+
+  while (true) {
+    const pkgPath = join(dir, "package.json");
+    if (existsSync(pkgPath)) {
+      const raw = JSON.parse(readFileSync(pkgPath, "utf8"));
+      if (raw.mux) {
+        return parseConfig(raw.mux, dir);
+      }
+    }
+
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  throw new Error(
+    'No "mux" config found in any package.json from here to /'
+  );
+}
+
+export function parseConfig(raw: RawMuxConfig, root: string): MuxConfig {
+  const session = raw.session || basename(root);
+
+  if (!raw.panes || !Array.isArray(raw.panes) || raw.panes.length === 0) {
+    throw new Error("mux config needs at least one pane");
+  }
+
+  const panes: PaneConfig[] = raw.panes.map((p: any, i: number) => {
+    if (!p.name) throw new Error(`pane ${i} missing "name"`);
+    if (!p.cmd) throw new Error(`pane ${i} missing "cmd"`);
+    return { name: p.name, cmd: p.cmd, cwd: p.cwd };
+  });
+
+  return { session, panes, root };
+}

package/src/mux.test.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect } from "bun:test";
+import { parseConfig } from "./config";
+
+describe("parseConfig", () => {
+  const root = "/tmp/test-project";
+
+  it("parses a valid config", () => {
+    const config = parseConfig(
+      {
+        session: "my-app",
+        panes: [
+          { name: "api", cmd: "bun run dev", cwd: "packages/api" },
+          { name: "web", cmd: "bun run start", cwd: "packages/web" },
+        ],
+      },
+      root
+    );
+    expect(config.session).toBe("my-app");
+    expect(config.root).toBe(root);
+    expect(config.panes).toHaveLength(2);
+    expect(config.panes[0]).toEqual({ name: "api", cmd: "bun run dev", cwd: "packages/api" });
+    expect(config.panes[1]).toEqual({ name: "web", cmd: "bun run start", cwd: "packages/web" });
+  });
+
+  it("defaults session to directory basename", () => {
+    const config = parseConfig(
+      { panes: [{ name: "dev", cmd: "bun run dev" }] },
+      "/home/user/my-project"
+    );
+    expect(config.session).toBe("my-project");
+  });
+
+  it("allows pane without cwd", () => {
+    const config = parseConfig(
+      { panes: [{ name: "dev", cmd: "bun run dev" }] },
+      root
+    );
+    expect(config.panes[0].cwd).toBeUndefined();
+  });
+
+  it("throws when panes is missing", () => {
+    expect(() => parseConfig({}, root)).toThrow("at least one pane");
+  });
+
+  it("throws when panes is empty", () => {
+    expect(() => parseConfig({ panes: [] }, root)).toThrow("at least one pane");
+  });
+
+  it("throws when a pane is missing name", () => {
+    expect(() =>
+      parseConfig({ panes: [{ cmd: "bun run dev" }] }, root)
+    ).toThrow('missing "name"');
+  });
+
+  it("throws when a pane is missing cmd", () => {
+    expect(() =>
+      parseConfig({ panes: [{ name: "api" }] }, root)
+    ).toThrow('missing "cmd"');
+  });
+});

package/src/tmux.ts

@@ -0,0 +1,138 @@
+import { mkdirSync, existsSync } from "fs";
+import type { MuxConfig, PaneConfig } from "./config";
+import { join } from "path";
+
+function run(...args: string[]): string {
+  const result = Bun.spawnSync(["tmux", ...args], {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  return result.stdout.toString().trim();
+}
+
+function runOk(...args: string[]): boolean {
+  const result = Bun.spawnSync(["tmux", ...args], {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  return result.exitCode === 0;
+}
+
+export function hasSession(name: string): boolean {
+  return runOk("has-session", "-t", name);
+}
+
+export function createSession(name: string, cwd: string): void {
+  run("new-session", "-d", "-s", name, "-c", cwd);
+}
+
+export function splitPane(session: string, cwd: string): string {
+  return run(
+    "split-window",
+    "-t",
+    session,
+    "-c",
+    cwd,
+    "-P",
+    "-F",
+    "#{pane_id}"
+  );
+}
+
+export function sendKeys(session: string, target: string, cmd: string): void {
+  run("send-keys", "-t", target, cmd, "Enter");
+}
+
+export function killSession(name: string): void {
+  run("kill-session", "-t", name);
+}
+
+export function selectLayout(session: string, layout: string): void {
+  run("select-layout", "-t", session, layout);
+}
+
+export function renameWindow(session: string, name: string): void {
+  run("rename-window", "-t", session, name);
+}
+
+export function attach(session: string): void {
+  const proc = Bun.spawnSync(["tmux", "attach", "-t", session], {
+    stdin: "inherit",
+    stdout: "inherit",
+    stderr: "inherit",
+  });
+  process.exit(proc.exitCode ?? 0);
+}
+
+export function listPanes(
+  session: string
+): { id: string; index: string; title: string; active: boolean }[] {
+  const out = run(
+    "list-panes",
+    "-t",
+    session,
+    "-F",
+    "#{pane_id}\t#{pane_index}\t#{pane_title}\t#{pane_active}"
+  );
+  if (!out) return [];
+  return out.split("\n").map((line) => {
+    const [id, index, title, active] = line.split("\t");
+    return { id, index, title, active: active === "1" };
+  });
+}
+
+export function capturePane(target: string, lines = 100): string {
+  return run("capture-pane", "-t", target, "-p", "-S", `-${lines}`);
+}
+
+function logDir(session: string): string {
+  return `/tmp/mux-${session}`;
+}
+
+export function setupLogging(config: MuxConfig): void {
+  const dir = logDir(config.session);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+export function startSession(config: MuxConfig): void {
+  const { session, panes, root } = config;
+
+  createSession(session, root);
+  setupLogging(config);
+
+  // First pane is the session window's initial pane
+  const firstPane = panes[0];
+  const firstCwd = firstPane.cwd ? join(root, firstPane.cwd) : root;
+  // Set cwd for first pane
+  sendKeys(session, `${session}:0.0`, `cd ${firstCwd}`);
+  sendKeys(session, `${session}:0.0`, firstPane.cmd);
+
+  // Additional panes via split
+  for (let i = 1; i < panes.length; i++) {
+    const pane = panes[i];
+    const cwd = pane.cwd ? join(root, pane.cwd) : root;
+    const paneId = splitPane(session, cwd);
+    sendKeys(session, paneId, pane.cmd);
+  }
+
+  // Even layout
+  selectLayout(session, "tiled");
+  renameWindow(session, "mux");
+}
+
+export function restartPane(
+  config: MuxConfig,
+  paneName: string
+): void {
+  const paneConfig = config.panes.find((p) => p.name === paneName);
+  if (!paneConfig) throw new Error(`Unknown pane: ${paneName}`);
+
+  const panes = listPanes(config.session);
+  const idx = config.panes.findIndex((p) => p.name === paneName);
+  const target = panes[idx];
+  if (!target) throw new Error(`Pane ${paneName} not found in tmux session`);
+
+  // Send Ctrl-C then re-run command
+  run("send-keys", "-t", target.id, "C-c", "");
+  sendKeys(config.session, target.id, paneConfig.cmd);
+}