@brutalsystems/muster 0.4.0 → 0.5.0

package/README.md

@@ -76,16 +76,24 @@ Add `--open` to display the launched session in a new Terminal.app window on mac
 
 ```sh
 muster run codex --open --prompt "Review this project" --format human
-muster run claude --open --prompt "Review this project" --format human
+muster run claude --open --terminal ghostty --prompt "Review this project" --format human
+muster run codex --open --terminal iterm2 --prompt "Review this project" --format human
 ```
 
 MCP `run` accepts `open: true`. This requires tmux and selects it when the host
 is auto; explicit pty hosts and tasks are rejected. Detached launch remains the
-default. Terminal.app is currently the only supported viewer; there is no
-`--terminal` selection yet. The host remains tmux, and successful results include
-`terminal_opened: true` (a launch event, not a live window-status check).
+default. `--terminal auto|terminal|iterm2|ghostty` requires `--open`; omitted or
+`auto` uses Terminal.app. MCP accepts the same `terminal` values. Explicit
+choices never silently fall back. iTerm2 and Ghostty must be installed as
+`iTerm.app` or `Ghostty.app` in `/Applications` or `~/Applications`.
+The host remains tmux. Successful results include `terminal_opened: true` and
+the resolved `terminal` (a launch event, not a live window-status check).
 Closing the Terminal window leaves the session running; use `muster stop <id>`
-to stop it. macOS may require Terminal automation permission. If opening fails,
+to stop it. Terminal.app and iTerm2 may require macOS Automation permission.
+Ghostty opens a separate app instance that exits when its last window closes;
+it uses the [Ghostty macOS launch interface](https://github.com/ghostty-org/ghostty/discussions/9221).
+iTerm2 uses its [documented scripting interface](https://iterm2.com/documentation-scripting.html).
+If the launch request to the viewer fails,
 Muster stops the launched session and returns an error.
 
 Auto-selection tries tmux, then pty. Every peer includes `host`, `capabilities`

package/dist/format.js

@@ -43,7 +43,7 @@ function recordHuman(record, color) {
     if (record.host)
         lines.push(field("Host", `${clean(record.host)}${record.host === "pty" ? " (not watchable or attachable)" : ""}`));
     if (record.terminal_opened)
-        lines.push(field("Terminal", "Terminal.app (opened at launch)"));
+        lines.push(field("Terminal", `${record.terminal === "ghostty" ? "Ghostty" : record.terminal === "iterm2" ? "iTerm2" : "Terminal.app"} (opened at launch)`));
     if (record.exit_code !== undefined)
         lines.push(field("Exit code", badExit ? paint(clean(record.exit_code), 31) : clean(record.exit_code)));
     if (record.signal)

package/dist/guard.js

@@ -14,6 +14,7 @@ export const runSchema = z
     kind: z.enum(["session", "task"]).default("session"),
     host: z.enum(["auto", "tmux", "pty", "macos-terminal"]).optional(),
     open: z.boolean().optional(),
+    terminal: z.enum(["auto", "terminal", "iterm2", "ghostty"]).optional(),
     permissions: z.enum(["auto", "deny", "bypass"]).optional(),
     sandbox: z.enum(["read-only", "workspace-write", "full-access"]).optional(),
     args: z.array(z.string()).default([]),

package/dist/hosts/terminal.js

@@ -1,13 +1,30 @@
 import { access, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
 import { constants } from "node:fs";
 import { delimiter, join } from "node:path";
 import { command } from "../identity/processes.js";
-export async function terminalAvailable(platform = process.platform) {
+export async function terminalAvailable(platform = process.platform, terminal = "terminal") {
     if (platform !== "darwin")
         return false;
     try {
-        await access("/System/Applications/Utilities/Terminal.app");
-        await access("/usr/bin/osascript", constants.X_OK);
+        if (terminal === "terminal") {
+            await access("/System/Applications/Utilities/Terminal.app");
+        }
+        else {
+            const name = terminal === "ghostty" ? "Ghostty.app" : "iTerm.app";
+            const found = await Promise.all(["/Applications", join(homedir(), "Applications")].map(async (dir) => {
+                try {
+                    await access(join(dir, name));
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            }));
+            if (!found.some(Boolean))
+                return false;
+        }
+        await access(terminal === "ghostty" ? "/usr/bin/open" : "/usr/bin/osascript", constants.X_OK);
         return true;
     }
     catch {
@@ -25,23 +42,51 @@ export async function tmuxExecutable() {
         }
         catch { }
     }
-    throw new Error("Cannot locate tmux executable for Terminal.app");
+    throw new Error("Cannot locate tmux executable for terminal viewer");
 }
-export async function openTerminal(tmux, server, hostRef, deadline) {
+export async function openTerminal(tmux, server, hostRef, deadline, terminal = "terminal") {
     if (!/^[a-zA-Z0-9_-]+$/.test(server) || !/^@\d+$/.test(hostRef))
         throw new Error("Invalid tmux terminal target");
     if (Date.now() >= deadline)
-        throw new Error("Launch deadline expired before opening Terminal.app");
+        throw new Error("Launch deadline expired before opening terminal");
+    const timeout = Math.max(1, Math.min(10000, deadline - Date.now()));
+    if (terminal === "ghostty") {
+        await command("/usr/bin/open", [
+            "-na",
+            "Ghostty",
+            "--args",
+            "--quit-after-last-window-closed=true",
+            "-e",
+            tmux,
+            "-L",
+            server,
+            "attach-session",
+            "-t",
+            "muster",
+            ";",
+            "select-window",
+            "-t",
+            hostRef,
+        ], timeout);
+        return;
+    }
     const quoted = "'" + tmux.replaceAll("'", "'\\''") + "'";
     const shellCommand = `${quoted} -L ${server} attach-session -t muster \\; select-window -t ${hostRef}`;
     await command("/usr/bin/osascript", [
         "-e",
-        `on run argv
+        terminal === "iterm2"
+            ? `on run argv
+  tell application "iTerm"
+    create window with default profile command (item 1 of argv)
+    activate
+  end tell
+end run`
+            : `on run argv
   tell application "Terminal"
     activate
     do script (item 1 of argv)
   end tell
 end run`,
         shellCommand,
-    ], Math.max(1, Math.min(10000, deadline - Date.now())));
+    ], timeout);
 }

package/dist/hosts/tmux.js

@@ -24,11 +24,11 @@ export class TmuxHost {
             return false;
         }
     }
-    openAvailable() {
-        return terminalAvailable();
+    openAvailable(terminal = "terminal") {
+        return terminalAvailable(process.platform, terminal);
     }
-    async open(hostRef, deadline) {
-        await openTerminal(await tmuxExecutable(), this.server, hostRef, deadline);
+    async open(hostRef, deadline, terminal = "terminal") {
+        await openTerminal(await tmuxExecutable(), this.server, hostRef, deadline, terminal);
     }
     capabilities() {
         return { watchable: true, attachable: true, survivesParentExit: true };

package/dist/muster.js

@@ -13,7 +13,7 @@ const listSchema = z
     .strict();
 const idSchema = z.object({ id: z.string().min(1) }).strict();
 const help = `Usage:
-  muster run <codex|claude> --prompt TEXT [--cwd DIR] [--kind session|task] [--host ID] [--open] [-- RUNTIME_OPTIONS]
+  muster run <codex|claude> --prompt TEXT [--cwd DIR] [--kind session|task] [--host ID] [--open] [--terminal APP] [-- RUNTIME_OPTIONS]
   muster list [--kind session|task] [--format json|human]
   muster stop <id> [--format json|human]
   muster output <id>
@@ -21,7 +21,8 @@ const help = `Usage:
 
 run also accepts --format json|human, --permissions auto|deny|bypass,
 and --sandbox read-only|workspace-write|full-access before -- RUNTIME_OPTIONS.
---open displays a tmux session in Terminal.app on macOS.
+--open displays a tmux session on macOS. --terminal accepts auto (Terminal.app),
+terminal, iterm2, or ghostty, and requires --open.
 run, list and stop default to JSON. output prints raw task text.
 
 pty launches print their record and keep this process running. Ctrl-C stops the
@@ -53,7 +54,7 @@ async function main() {
             });
         });
     if (mcp) {
-        const server = new Server({ name: "muster", version: "0.4.0" }, { capabilities: { tools: {} } });
+        const server = new Server({ name: "muster", version: "0.5.0" }, { capabilities: { tools: {} } });
         server.setRequestHandler(ListToolsRequestSchema, async () => ({
             tools: [
                 {
@@ -76,7 +77,12 @@ async function main() {
                             },
                             open: {
                                 type: "boolean",
-                                description: "Open the tmux session in Terminal.app (macOS only).",
+                                description: "Open the tmux session in a terminal viewer (macOS only).",
+                            },
+                            terminal: {
+                                type: "string",
+                                enum: ["auto", "terminal", "iterm2", "ghostty"],
+                                description: "Viewer app; requires open. Auto uses Terminal.app.",
                             },
                             permissions: {
                                 type: "string",
@@ -170,6 +176,7 @@ async function main() {
                 kind: { type: "string" },
                 host: { type: "string" },
                 open: { type: "boolean" },
+                terminal: { type: "string" },
                 format: { type: "string" },
                 permissions: { type: "string" },
                 sandbox: { type: "string" },

package/dist/run.js

@@ -52,6 +52,9 @@ export class Muster {
             throw new Error("cwd is not a directory");
         if (req.kind === "task" && req.host)
             throw new Error("host applies only to session launches");
+        if (req.terminal && !req.open)
+            throw new Error("--terminal requires --open");
+        const terminal = !req.terminal || req.terminal === "auto" ? "terminal" : req.terminal;
         const requestedHost = req.host ?? this.config.host;
         if (req.open &&
             (req.kind !== "session" || !["auto", "tmux"].includes(requestedHost)))
@@ -60,8 +63,9 @@ export class Muster {
         const argv = launchArgs(req, this.config), driver = req.kind === "session"
             ? await selectHost(req.open ? "tmux" : requestedHost, this.drivers)
             : undefined;
-        if (req.open && (!driver?.open || !(await driver.openAvailable?.())))
-            throw new Error("--open requires Terminal.app on macOS and tmux");
+        if (req.open &&
+            (!driver?.open || !(await driver.openAvailable?.(terminal))))
+            throw new Error(`--open requires the selected terminal (${terminal}) installed on macOS and tmux`);
         let policy = [];
         if (req.runtime === "claude")
             await assertClaudePolicy(this.env);
@@ -81,7 +85,7 @@ export class Muster {
                 prompt: req.prompt,
                 host: driver?.id ?? null,
                 requester,
-                ...(req.open ? { open: true } : {}),
+                ...(req.open ? { open: true, terminal } : {}),
                 args: req.args,
                 ...permissions,
             });
@@ -186,8 +190,9 @@ export class Muster {
                         };
                         if (req.open) {
                             openingTerminal = true;
-                            await driver.open(launched.hostRef, deadline);
+                            await driver.open(launched.hostRef, deadline, terminal);
                             peer.terminal_opened = true;
+                            peer.terminal = terminal;
                         }
                         entry = await this.registry.update(entry.launchId, {
                             id: identity.id,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brutalsystems/muster",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Launch instructed, reachable local agent sessions",
   "type": "module",
   "engines": {