@cordfuse/llmux 0.12.4 → 0.13.0

package/README.md

@@ -8,7 +8,7 @@ Each agent runs unmodified — llmux just brokers I/O. Sessions survive
 restarts, attach is raw-TTY, and Claude Code conversations are resumable
 from any client.
 
-> **Status:** v0.12.3 — daemon + CLI client consolidated into one binary
+> **Status:** v0.13.0 — daemon + CLI client consolidated into one binary
 > (`llmux`). Auth, tokens, mobile picker, conversation resume, Claude Code
 > history adapter shipped. See [CHANGELOG.md](./CHANGELOG.md).
 
@@ -181,17 +181,74 @@ currently speaks ws:// only.
 
 ## Config (`.llmux.yaml`)
 
-A YAML config (project-local or global) can override per-agent defaults.
-Discovery order:
+Optional YAML config file. llmux runs without it — defaults are baked into
+`agents.ts`. Use the YAML to override per-agent launch behavior or change
+the daemon's default port without baking a flag into every shell alias.
+
+### Discovery order (first hit wins)
 
 1. `--config <path>` flag
-2. `./.llmux.yaml` (project-local, auto-discovered in cwd)
-3. `~/.config/llmux/config.yaml` (global default)
+2. `./.llmux.yaml` — auto-discovered in the cwd you invoke from
+3. `~/.config/llmux/config.yaml` — global default
 4. `LLMUX_CONFIG=<path>` env var
 
-llmux runs without any YAML file — all defaults are baked into
-`agents.ts`. The `init` command to generate a starter YAML is not yet
-shipped; create one by hand if you want to override defaults today.
+### Schema
+
+```yaml
+# Server defaults — used when `llmux server start` runs with no overriding
+# flag / env. Precedence: --port flag > LLMUXD_PORT env > server.port here.
+server:
+  port: 3030          # daemon listen port (default 3000 when key omitted)
+
+# Per-agent overrides. Key matches the agent's `key` in the catalog
+# (claude, codex, agy, gemini, qwen, opencode, amp, grok, aider, continue,
+# kiro, cursor, plandex, goose, copilot). Only the keys you list override;
+# everything else falls through to the catalog default.
+agents:
+  claude:
+    cmd: claude       # binary path or PATH-lookup name (default: agent's catalog cmd)
+    flags: ""         # launch flags appended after cmd (default: catalog default,
+                      # e.g. "--dangerously-skip-permissions" for claude).
+                      # Empty string disables the default flags entirely.
+  codex:
+    flags: "--model gpt-5"  # keep `codex` as the binary, override flags
+```
+
+### Worked examples
+
+**Strip danger-mode flags from claude on a shared machine:**
+
+```yaml
+agents:
+  claude:
+    flags: ""        # claude launches with no flags — full permission prompts
+```
+
+**Point gemini at a wrapper script (logging, rate-limiting, whatever):**
+
+```yaml
+agents:
+  gemini:
+    cmd: /usr/local/bin/gemini-wrapped
+```
+
+**Run the daemon on a non-default port project-wide:**
+
+```yaml
+server:
+  port: 8080
+```
+
+A bare `llmux server start` from any cwd containing this file binds to
+`:8080`. `--port 3030` still wins per-invocation.
+
+### What this YAML does NOT do today
+
+The schema includes `agents.<key>.readyPrompt`, `server.token`,
+`server.tokenExpiry`, `server.noQr`, and `sessions[]` (auto-spawn list).
+These are reserved for future wiring — setting them has no effect in
+v0.13.x. If you need any of these surfaces, file an issue and they can be
+prioritised.
 
 ## Environment
 

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { readFileSync as readFileSync5 } from "fs";
+import { readFileSync as readFileSync6 } from "fs";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { dirname as dirname4, resolve as resolve3 } from "path";
 
@@ -70,7 +70,7 @@ function parseArgs(argv, specs) {
 }
 
 // src/daemon/handlers.ts
-import { existsSync as existsSync5 } from "fs";
+import { existsSync as existsSync6 } from "fs";
 import { resolve as resolve2 } from "path";
 import { createInterface } from "readline";
 import qrcodeTerminal from "qrcode-terminal";
@@ -205,23 +205,59 @@ function isAgentInstalled(agent) {
   return which(head);
 }
 
-// src/daemon/state.ts
-import { existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, writeFileSync } from "fs";
+// src/daemon/config.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
 import { homedir as homedir2 } from "os";
-import { dirname, join as join2 } from "path";
+import { join as join2 } from "path";
+import { parse as parseYaml } from "yaml";
+var DEFAULT_CONFIG = {
+  server: { port: 3e3, noQr: false },
+  agents: {},
+  sessions: []
+};
+function discoverConfigPath(opts = {}) {
+  if (opts.explicit) return opts.explicit;
+  const cwd = opts.cwd ?? process.cwd();
+  const projectLocal = join2(cwd, ".llmux.yaml");
+  if (existsSync2(projectLocal)) return projectLocal;
+  const home = opts.home ?? homedir2();
+  const globalDefault = join2(home, ".config", "llmux", "config.yaml");
+  if (existsSync2(globalDefault)) return globalDefault;
+  const env = opts.envVar ?? process.env.LLMUX_CONFIG;
+  if (env && existsSync2(env)) return env;
+  return null;
+}
+function loadConfig(opts = {}) {
+  const path = discoverConfigPath(opts);
+  if (!path) return DEFAULT_CONFIG;
+  const raw = readFileSync2(path, "utf8");
+  const parsed = parseYaml(raw);
+  const merged = {
+    server: { ...DEFAULT_CONFIG.server, ...parsed?.server ?? {} },
+    agents: { ...DEFAULT_CONFIG.agents, ...parsed?.agents ?? {} },
+    sessions: parsed?.sessions ?? [],
+    sourcePath: path
+  };
+  return merged;
+}
+
+// src/daemon/state.ts
+import { existsSync as existsSync3, mkdirSync, readFileSync as readFileSync3, writeFileSync } from "fs";
+import { homedir as homedir3 } from "os";
+import { dirname, join as join3 } from "path";
 var EMPTY = { version: 1, sessions: {} };
 function stateDir() {
   const xdg = process.env.XDG_STATE_HOME;
-  return xdg ? join2(xdg, "llmuxd") : join2(homedir2(), ".local", "state", "llmuxd");
+  return xdg ? join3(xdg, "llmuxd") : join3(homedir3(), ".local", "state", "llmuxd");
 }
 function statePath() {
-  return join2(stateDir(), "sessions.json");
+  return join3(stateDir(), "sessions.json");
 }
 function load() {
   const path = statePath();
-  if (!existsSync2(path)) return structuredClone(EMPTY);
+  if (!existsSync3(path)) return structuredClone(EMPTY);
   try {
-    const parsed = JSON.parse(readFileSync2(path, "utf8"));
+    const parsed = JSON.parse(readFileSync3(path, "utf8"));
     if (parsed.version !== 1 || typeof parsed.sessions !== "object" || parsed.sessions === null) {
       return structuredClone(EMPTY);
     }
@@ -336,8 +372,8 @@ function attachOrSwitch(name) {
 }
 
 // src/daemon/auth-store.ts
-import { existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
-import { dirname as dirname2, join as join3 } from "path";
+import { existsSync as existsSync4, mkdirSync as mkdirSync2, readFileSync as readFileSync4, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname2, join as join4 } from "path";
 
 // src/daemon/token.ts
 import { randomBytes } from "crypto";
@@ -352,13 +388,13 @@ function tokenId(token) {
 // src/daemon/auth-store.ts
 var EMPTY2 = { version: 1, tokens: [] };
 function authPath() {
-  return join3(stateDir(), "auth.json");
+  return join4(stateDir(), "auth.json");
 }
 function load2() {
   const p = authPath();
-  if (!existsSync3(p)) return structuredClone(EMPTY2);
+  if (!existsSync4(p)) return structuredClone(EMPTY2);
   try {
-    const parsed = JSON.parse(readFileSync3(p, "utf8"));
+    const parsed = JSON.parse(readFileSync4(p, "utf8"));
     if (parsed.version === 1 && Array.isArray(parsed.tokens)) {
       return { version: 1, tokens: parsed.tokens };
     }
@@ -411,7 +447,7 @@ function authEnabled() {
 
 // src/daemon/web/server.ts
 import { createServer } from "http";
-import { readFileSync as readFileSync4, existsSync as existsSync4 } from "fs";
+import { readFileSync as readFileSync5, existsSync as existsSync5 } from "fs";
 import { fileURLToPath } from "url";
 import { dirname as dirname3, resolve } from "path";
 import { WebSocketServer } from "ws";
@@ -501,7 +537,7 @@ function readDaemonVersion() {
       resolve(here, "./package.json")
     ]) {
       try {
-        const pkg = JSON.parse(readFileSync4(candidate, "utf8"));
+        const pkg = JSON.parse(readFileSync5(candidate, "utf8"));
         if (pkg.name === "@cordfuse/llmux" && typeof pkg.version === "string") return pkg.version;
       } catch {
       }
@@ -2090,7 +2126,7 @@ function createSession(input) {
   }
   const cwdRaw = input.cwd && input.cwd.trim() || process.env.HOME || process.cwd();
   const cwd = expandTilde(cwdRaw);
-  if (!existsSync4(cwd)) return { ok: false, error: `cwd does not exist: ${cwdRaw}` };
+  if (!existsSync5(cwd)) return { ok: false, error: `cwd does not exist: ${cwdRaw}` };
   const flagsOverride = input.flags !== void 0 ? input.flags.trim() : void 0;
   const envOverride = input.env !== void 0 ? parseEnvText(input.env) : void 0;
   const resumeFrom = input.resumeFrom && agentDef.history ? input.resumeFrom : void 0;
@@ -2190,7 +2226,7 @@ function editSession(oldName, patch) {
       return { ok: false, error: `session "${newName}" already exists` };
     }
   }
-  if (newCwd !== void 0 && newCwd.length > 0 && !existsSync4(expandTilde(newCwd))) {
+  if (newCwd !== void 0 && newCwd.length > 0 && !existsSync5(expandTilde(newCwd))) {
     return { ok: false, error: `cwd does not exist: ${newCwd}` };
   }
   const renaming = newName !== void 0 && newName !== oldName && newName.length > 0;
@@ -2559,13 +2595,26 @@ function printBanner(port) {
 }
 
 // src/daemon/handlers.ts
+function applyAgentOverrides(base) {
+  const cfg = loadConfig();
+  const o = cfg.agents[base.key];
+  if (!o) return base;
+  return {
+    ...base,
+    ...o.cmd !== void 0 ? { cmd: o.cmd } : {},
+    ...o.flags !== void 0 ? { flags: o.flags } : {}
+  };
+}
 function expandAgentList(spec) {
-  if (spec === "all") return Object.values(DEFAULT_AGENTS).filter(isAgentInstalled);
+  if (spec === "all") {
+    return Object.values(DEFAULT_AGENTS).map(applyAgentOverrides).filter(isAgentInstalled);
+  }
   const keys = spec.split(",").map((k) => k.trim()).filter(Boolean);
   const out = [];
   for (const k of keys) {
-    const def = DEFAULT_AGENTS[k];
-    if (!def) throw new Error(`unknown agent "${k}". Known: ${Object.keys(DEFAULT_AGENTS).join(", ")}`);
+    const base = DEFAULT_AGENTS[k];
+    if (!base) throw new Error(`unknown agent "${k}". Known: ${Object.keys(DEFAULT_AGENTS).join(", ")}`);
+    const def = applyAgentOverrides(base);
     if (!isAgentInstalled(def)) throw new Error(`agent "${k}" is not installed (looked for: ${def.cmd})`);
     out.push(def);
   }
@@ -2577,7 +2626,7 @@ function buildCommand(agent) {
 function resolveCwd(input) {
   if (!input) return process.cwd();
   const out = resolve2(input);
-  if (!existsSync5(out)) throw new Error(`cwd does not exist: ${out}`);
+  if (!existsSync6(out)) throw new Error(`cwd does not exist: ${out}`);
   return out;
 }
 function resolveTarget(target) {
@@ -2714,7 +2763,8 @@ function handleChat(args) {
 }
 async function handleServe(args) {
   requireTmux();
-  const portRaw = args.flags.port ?? process.env.LLMUXD_PORT ?? "3000";
+  const cfg = loadConfig();
+  const portRaw = args.flags.port ?? process.env.LLMUXD_PORT ?? String(cfg.server.port);
   const port = Number(portRaw);
   if (!Number.isFinite(port) || port <= 0 || port > 65535) {
     throw new Error(`invalid port: ${portRaw}`);
@@ -3448,7 +3498,7 @@ function readVersion() {
     const here = dirname4(fileURLToPath2(import.meta.url));
     for (const candidate of [resolve3(here, "../package.json"), resolve3(here, "../../package.json")]) {
       try {
-        const pkg = JSON.parse(readFileSync5(candidate, "utf8"));
+        const pkg = JSON.parse(readFileSync6(candidate, "utf8"));
         if (pkg.name === "@cordfuse/llmux" && typeof pkg.version === "string") return pkg.version;
       } catch {
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cordfuse/llmux",
-  "version": "0.12.4",
+  "version": "0.13.0",
   "description": "tmux-based AI agent dispatcher — REST/WS daemon + CLI client in one binary",
   "license": "MIT",
   "type": "module",

package/src/daemon/handlers.ts

@@ -3,6 +3,7 @@ import { resolve } from 'node:path';
 import { createInterface } from 'node:readline';
 import qrcodeTerminal from 'qrcode-terminal';
 import { DEFAULT_AGENTS, isAgentInstalled, type AgentDefinition } from './agents.ts';
+import { loadConfig } from './config.ts';
 import * as state from './state.ts';
 import * as tmux from './tmux.ts';
 import * as authStore from './auth-store.ts';
@@ -12,13 +13,32 @@ import type { ParsedArgs } from '../cli.ts';
 
 // ---------- helpers ----------
 
+/**
+ * Merge YAML `agents.<key>.{cmd,flags}` overrides over the catalog default.
+ * Discovery uses process.cwd() so a project-local `.llmux.yaml` takes effect
+ * when the operator invokes from that project.
+ */
+function applyAgentOverrides(base: AgentDefinition): AgentDefinition {
+  const cfg = loadConfig();
+  const o = cfg.agents[base.key];
+  if (!o) return base;
+  return {
+    ...base,
+    ...(o.cmd !== undefined ? { cmd: o.cmd } : {}),
+    ...(o.flags !== undefined ? { flags: o.flags } : {}),
+  };
+}
+
 function expandAgentList(spec: string): AgentDefinition[] {
-  if (spec === 'all') return Object.values(DEFAULT_AGENTS).filter(isAgentInstalled);
+  if (spec === 'all') {
+    return Object.values(DEFAULT_AGENTS).map(applyAgentOverrides).filter(isAgentInstalled);
+  }
   const keys = spec.split(',').map((k) => k.trim()).filter(Boolean);
   const out: AgentDefinition[] = [];
   for (const k of keys) {
-    const def = DEFAULT_AGENTS[k];
-    if (!def) throw new Error(`unknown agent "${k}". Known: ${Object.keys(DEFAULT_AGENTS).join(', ')}`);
+    const base = DEFAULT_AGENTS[k];
+    if (!base) throw new Error(`unknown agent "${k}". Known: ${Object.keys(DEFAULT_AGENTS).join(', ')}`);
+    const def = applyAgentOverrides(base);
     if (!isAgentInstalled(def)) throw new Error(`agent "${k}" is not installed (looked for: ${def.cmd})`);
     out.push(def);
   }
@@ -193,7 +213,13 @@ export function handleChat(args: ParsedArgs): void {
 
 export async function handleServe(args: ParsedArgs): Promise<void> {
   tmux.requireTmux();
-  const portRaw = (args.flags.port as string | undefined) ?? process.env.LLMUXD_PORT ?? '3000';
+  const cfg = loadConfig();
+  // Precedence: CLI --port > LLMUXD_PORT env > config.server.port (schema
+  // default already 3000 when no YAML present).
+  const portRaw =
+    (args.flags.port as string | undefined) ??
+    process.env.LLMUXD_PORT ??
+    String(cfg.server.port);
   const port = Number(portRaw);
   if (!Number.isFinite(port) || port <= 0 || port > 65535) {
     throw new Error(`invalid port: ${portRaw}`);