mulmoterminal 1.4.0 → 1.6.0

package/README.md

@@ -12,9 +12,9 @@ ping to your phone when a task finishes. One `npx` command, no Electron, no conf
 npx mulmoterminal        # starts on http://localhost:34567 and opens your browser
 ```
 
-![MulmoTerminal's grid view — several coding agents running side by side](https://raw.githubusercontent.com/receptron/mulmoterminal/main/docs/guide/images/grid-2x2.png)
+![MulmoTerminal's grid view — four live Claude sessions running side by side, each in its own color-coded project](https://raw.githubusercontent.com/receptron/mulmoterminal/main/docs/guide/images/grid-2x2-live.png)
 
-*The grid is a **cockpit for parallel agents** — each cell is one agent (Claude or Codex). A cell's **border color signals its state** — working (blue), needs-you (amber — a permission or answer), idle — and an attention chime pulls you back to a stuck cell off-screen, so you can supervise many and only step in where you're called. (See the [Cost & token usage](#cost--token-usage) shot below for a single cell's live header.)*
+*The grid is a **cockpit for parallel agents** — here, four live Claude sessions, each in its own color-coded project. Every cell's header carries what you need to triage at a glance: **model · context %**, **token counts** (`⇡in ⇣out`), the **git branch / changes** chip, and an AI summary of what the agent is doing. A cell's **border color signals state** — working / done (blue), needs-you (amber — e.g. waiting on a permission), idle — with an attention chime so a stuck cell off-screen still pulls you back. Supervise many; only step in where you're called.*
 
 ## Why you'll want it
 
@@ -94,6 +94,19 @@ listener and needs a browser **on the host**. Either way it needs a Desktop OAut
 as `~/.secrets/client_secret_*.json`; the refresh token lands in `~/.config/mulmo/google-token.json`
 and is **shared with MulmoClaude**, so one link per machine covers both apps.
 
+**Local models (optional).** The package also ships `claude-ollama` — a one-command launcher that
+runs Claude Code **fully locally against an [Ollama](https://ollama.com) model** (no cloud, no API
+key). It starts a large-context Ollama server and launches `claude` with a minimal system prompt so
+small models aren't drowned:
+
+```bash
+ollama pull qwen3:4b
+npx -p mulmoterminal claude-ollama qwen3:4b   # or, if installed globally: claude-ollama qwen3:4b
+```
+
+See [Local models with claude-ollama](https://receptron.github.io/mulmoterminal/guide/en/claude-ollama.html)
+for the details and model notes.
+
 > **Already linked before the calendar-list / colour features?** They need a read scope your existing
 > link doesn't have, so `listCalendars` (and, in practice, `colors`) fail with an insufficient-scope
 > 403 until you re-authorize: **Settings → Google account → Unlink**, then sign in again (or re-run
@@ -225,6 +238,17 @@ today — **Claude Code** (the default) and **Codex**.
 cell's launch form and the Collections browser carry a **Claude / Codex** toggle (your
 choice is remembered).
 
+**Other models.**
+Claude Code can run against any **Anthropic-compatible** backend (OpenRouter, Moonshot, a
+LiteLLM gateway). Backends are listed in `~/.mulmoterminal/config.json` under `providers`,
+and their **keys are read from the server's environment** — never from a file the app
+serves. A directory sets its default in `.mulmoterminal.json` (`provider` / `model`), and
+each grid cell's launch form has a **MODEL** select that overrides it for one session,
+listing ~27 curated models with the measured pass rate of a real tool-using task beside
+each. A provider whose token can't be resolved **refuses to start** rather than falling
+back to Anthropic, and providers can't be combined with the Docker sandbox. Full walkthrough — setup, the measured model list, adding your own models, troubleshooting:
+[Using another model via OpenRouter](https://receptron.github.io/mulmoterminal/guide/en/providers.html).
+
 **Skills for Codex.** Codex has no `/<slug>` slash commands, so on session setup
 MulmoTerminal **mirrors the workspace's `.claude/skills` into `~/.codex/skills`** (each
 mirrored directory carries a `.mt-mirror` marker so a re-sync overwrites what MulmoTerminal
@@ -483,6 +507,7 @@ yarn dev:client         # Vite dev server only
 
 yarn build              # type-check (vue-tsc) + vite build -> dist/
 yarn typecheck:server   # type-check the server (tsconfig.server.json)
+yarn typecheck:test     # type-check the specs (tsconfig.test*.json)
 yarn server             # run backend; serves dist/ + the APIs on :34567
 yarn test               # vitest run
 ```
@@ -491,6 +516,12 @@ The backend is TypeScript run directly via `tsx` (no build step); `server/` is
 type-checked separately through `tsconfig.server.json` (`strict`), kept out of
 the main `build` so the two type-check independently.
 
+Specs sit outside both of those projects, and vitest strips types rather than
+checking them — so `yarn typecheck:test` is what keeps them honest. It mirrors
+the same split: `tsconfig.test.json` (client specs, DOM + `.vue`) and
+`tsconfig.test-server.json` (server specs, node). CI runs it alongside the
+other two.
+
 In dev, open the Vite URL; its proxy forwards `/ws`, `/ws/pubsub`, and `/api` to
 `:34567`. In production, run `yarn build` then `yarn server` and open
 `http://localhost:34567`.
@@ -661,8 +692,10 @@ Each grid cell's header shows two badges for its session, refreshed when a turn
 
 - **Context badge** — e.g. `Opus · ctx 35%`: the model family plus how full its context
   window is (the *last* turn's input + cache tokens ÷ the model's window — **1M** for
-  current-gen Opus / Sonnet / Fable, **200k** otherwise; an unknown model shows the label
-  with no %).
+  current-gen Opus / Sonnet / Fable, **200k** otherwise). A session running on a
+  [provider model](#agents-claude--codex) shows that model's name and its published window
+  (`Kimi K2.7 Code · ctx 12%`); a model in neither list keeps the label and hides the %,
+  since the window is never guessed.
 - **Token badge** — `⇡<in> ⇣<out>`: cumulative input (fresh + cache-read + cache-creation)
   and output tokens for the session, k/M-formatted, with a full breakdown in the tooltip.
 
@@ -724,6 +757,13 @@ Favorited collections get their own toolbar buttons.
 
 - **Timeline** (🕘) — a read-only per-session activity timeline (tools run, newest first),
   from `GET /api/transcript/timeline`.
+- **Bring another cell's turn here** (💬) — pick another terminal in the grid and its
+  **last completed turn** is pasted into *this* cell's input box, so you can have Claude
+  and Codex look at each other's work (or pull in a session running in a different repo).
+  The excerpt comes from the agent's own log, not the screen buffer, so it carries no
+  ANSI debris and nothing lost to scrollback. It is **pasted, never sent** — you read
+  what arrived and press Enter, in the cell you were already in. A turn still running
+  isn't available yet (Codex writes its rollout only once the turn ends).
 - **Tools pane** — the available GUI tools plus a live tool-call history for the active
   session.
 - **Notifications** (🔔) — a toolbar bell with an unread badge and a dropdown of active
@@ -889,6 +929,7 @@ same-origin-guarded.
 | `GET /api/codex/sessions?cwd=` | Codex sessions for the project (from `~/.codex` rollouts), newest first. |
 | `GET /api/cost?cwd=&session=` | Estimated $ cost — session / today / month. |
 | `GET /api/transcript/timeline?session=&cwd=` | Per-session activity timeline (tools run). |
+| `GET /api/transcript/last-turn?session=&cwd=&agent=` | A session's last completed exchange (`prompt`, `reply`) plus the `text` to paste into another terminal. `agent=codex` reads the codex rollout instead of the Claude transcript. |
 
 **Git & worktrees**
 
@@ -923,8 +964,9 @@ same-origin-guarded.
 
 | Endpoint | Purpose |
 | -------- | ------- |
-| `GET\|POST /api/config` | User UI config (`cwdPresets`, `soundFile`, `prRepos`, `launchers`, `userMcpServers`). |
+| `GET\|POST /api/config` | User UI config (`cwdPresets`, `soundFile`, `prRepos`, `launchers`, `userMcpServers`, `providers`). |
 | `GET /api/sound` · `/api/dir-sound?cwd=` · `/api/dir-config?cwd=` | Custom / per-directory attention sound + per-dir config. |
+| `GET /api/launch-options` | The Anthropic-compatible backends this server can reach, each with its models and — when it can't — the reason. Reports the **name** of the env var a key is read from, never the key. |
 | `GET /api/notifications`(`/history`) · `POST /api/notifications/:id/clear` | Notification feed. |
 | `POST /api/transcribe`(`/model`…) | Voice-input transcription (Whisper, macOS). |
 | `POST /api/translation` | Runtime UI-string translation. |

package/bin/claude-ollama.js

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+
+// `claude-ollama <model> [claude args…]` — run Claude Code fully locally against an
+// Ollama-served model. Ollama 0.31+ serves a native Anthropic-compatible `/v1/messages`, so
+// Claude Code connects directly; this launcher just sets up the three things that make it
+// actually work with a small local model:
+//   1. a dedicated large-context `ollama serve` (the 4096 default overflows Claude's prompt),
+//   2. `--bare --disable-slash-commands` so the system prompt is small enough for the model,
+//   3. the env recipe (unset ANTHROPIC_API_KEY, point ANTHROPIC_BASE_URL at the local server).
+
+import { execSync, spawn } from "node:child_process";
+import { createServer } from "node:net";
+import { get as httpGet } from "node:http";
+import { parseClaudeOllamaArgs, buildClaudeEnv, buildOllamaServeEnv, buildClaudeArgs, modelIsInstalled, OLLAMA_CONTEXT_LENGTH } from "./ollama-launch.js";
+
+const log = (msg) => console.log(`\x1b[36m[claude-ollama]\x1b[0m ${msg}`);
+const error = (msg) => console.error(`\x1b[31m[claude-ollama]\x1b[0m ${msg}`);
+
+const READY_TIMEOUT_MS = 20_000;
+const READY_POLL_MS = 400;
+
+function printHelp() {
+  console.log(
+    [
+      "Usage: claude-ollama <model> [claude args…]",
+      "",
+      "Run Claude Code against a local Ollama model — no cloud, no API key.",
+      "Starts a dedicated large-context Ollama server on a private port and launches",
+      "Claude Code with a minimal system prompt (--bare) so small models aren't drowned.",
+      "",
+      "Examples:",
+      "  claude-ollama qwen3:4b",
+      '  claude-ollama qwen3:30b-a3b "refactor this module"',
+      "",
+      "Notes:",
+      "  - The model must be pulled first:  ollama pull <model>",
+      "  - Validate a model through a real multi-turn tool run; small ones vary.",
+    ].join("\n"),
+  );
+}
+
+function hasCommand(cmd) {
+  try {
+    execSync(`${cmd} --version`, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// A free TCP port for the private ollama server, so an Ollama the user already runs (11434)
+// is left alone.
+function findFreePort() {
+  return new Promise((resolve, reject) => {
+    const probe = createServer();
+    probe.once("error", reject);
+    probe.listen(0, "127.0.0.1", () => {
+      const { port } = probe.address();
+      probe.close(() => resolve(port));
+    });
+  });
+}
+
+// GET a small JSON endpoint on the local server, best-effort (null on any failure).
+function getJson(port, path, timeout_ms = 2000) {
+  return new Promise((resolve) => {
+    const req = httpGet({ host: "127.0.0.1", port, path, timeout: timeout_ms }, (res) => {
+      let body = "";
+      res.on("data", (chunk) => (body += chunk));
+      res.on("end", () => {
+        try {
+          resolve(JSON.parse(body));
+        } catch {
+          resolve(null);
+        }
+      });
+    });
+    req.on("error", () => resolve(null));
+    req.on("timeout", () => {
+      req.destroy();
+      resolve(null);
+    });
+  });
+}
+
+async function waitUntilReady(port) {
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < READY_TIMEOUT_MS) {
+    if (await getJson(port, "/api/version")) return true;
+    await new Promise((r) => setTimeout(r, READY_POLL_MS));
+  }
+  return false;
+}
+
+function requireCommands() {
+  if (!hasCommand("ollama")) {
+    error("`ollama` not found on PATH. Install it: https://ollama.com/download");
+    process.exit(1);
+  }
+  if (!hasCommand("claude")) {
+    error("`claude` (Claude Code) not found. Install it: npm install -g @anthropic-ai/claude-code");
+    process.exit(1);
+  }
+}
+
+// Start the private ollama server and return a `stop` that kills it. The stop is wired to
+// this process's own exit and signals so the server never outlives the launcher.
+function startPrivateOllama(host) {
+  const serve = spawn("ollama", ["serve"], {
+    stdio: "ignore",
+    env: buildOllamaServeEnv(process.env, host, OLLAMA_CONTEXT_LENGTH),
+  });
+  let stopped = false;
+  const stop = () => {
+    if (stopped) return;
+    stopped = true;
+    try {
+      serve.kill("SIGTERM");
+    } catch {
+      // already gone
+    }
+  };
+  process.on("exit", stop);
+  for (const signal of ["SIGINT", "SIGTERM"]) {
+    process.on(signal, () => {
+      stop();
+      process.exit(signal === "SIGINT" ? 130 : 143);
+    });
+  }
+  serve.on("error", (e) => {
+    error(`failed to start ollama serve: ${e.message}`);
+    process.exit(1);
+  });
+  return stop;
+}
+
+// Hand off to interactive Claude Code; exit with its code and stop our server behind it.
+function runClaude(model, baseUrl, claudeArgs, stopServe) {
+  log(`launching Claude Code on ${model} (minimal prompt: --bare --disable-slash-commands)`);
+  const claude = spawn("claude", buildClaudeArgs(claudeArgs), {
+    stdio: "inherit",
+    env: buildClaudeEnv(process.env, model, baseUrl),
+  });
+  claude.on("error", (e) => {
+    error(`failed to launch claude: ${e.message}`);
+    stopServe();
+    process.exit(1);
+  });
+  claude.on("exit", (code) => {
+    stopServe();
+    process.exit(code ?? 0);
+  });
+}
+
+async function main() {
+  const { help, model, claudeArgs } = parseClaudeOllamaArgs(process.argv.slice(2));
+  if (help || !model) {
+    printHelp();
+    process.exit(help ? 0 : 1);
+  }
+  requireCommands();
+  const port = await findFreePort();
+  const host = `127.0.0.1:${port}`;
+  log(`starting a private Ollama server on ${host} (context ${OLLAMA_CONTEXT_LENGTH})…`);
+  const stopServe = startPrivateOllama(host);
+  if (!(await waitUntilReady(port))) {
+    error("the Ollama server did not become ready in time");
+    stopServe();
+    process.exit(1);
+  }
+  const tags = await getJson(port, "/api/tags");
+  if (tags && !modelIsInstalled(tags, model)) {
+    error(`model '${model}' is not installed. Pull it first:  ollama pull ${model}`);
+    stopServe();
+    process.exit(1);
+  }
+  runClaude(model, `http://${host}`, claudeArgs, stopServe);
+}
+
+main().catch((e) => {
+  error(e?.message || String(e));
+  process.exit(1);
+});

package/bin/cli-args.d.ts

@@ -0,0 +1,11 @@
+export type PortChoice = { port: number; explicit: boolean } | { error: string };
+export type CwdChoice = { path: string; mustExist: boolean } | { error: string };
+export declare function parsePortArg(args: string[], defaultPort: number): PortChoice;
+export declare function chooseCwd(args: string[], env: Record<string, string | undefined>): CwdChoice;
+export declare function portInUseMessage(port: number, explicit: boolean): string;
+export declare function portInUseAction(explicit: boolean, isTTY: boolean | undefined): "ask" | "stop";
+export declare function secondInstancePrompt(port: number): string;
+export declare function saysYes(answer: unknown): boolean;
+export declare const SECOND_INSTANCE_NOTE: string;
+export declare const MIN_NODE_LABEL: string;
+export declare function nodeMeetsMinimum(version: string): boolean;

package/bin/cli-args.js

@@ -0,0 +1,135 @@
+// What the launcher decides before it starts anything, kept out of the executable so each
+// decision can be checked without a process to exit or a terminal to type into.
+//
+// `--cwd` picks the workspace claude runs in and whose sessions the sidebar lists, so it is
+// a data-scope boundary: getting it wrong points the whole app at someone else's project.
+// `--port` decides whether a clash is a hard error or a silent retry. Both used to be
+// decided inside the executable, where they exit the process on a bad value and so could not
+// be checked at all (#611 A3).
+//
+// These return a decision; the caller prints and exits. Nothing here reads argv, the
+// environment or the filesystem.
+
+/**
+ * Which port the launcher should ask for.
+ * `--port` must be a plain integer in range: a value that merely starts with digits ("80x")
+ * or carries a sign or padding ("+80", "080") is a typo, and silently launching on 80 is
+ * worse than saying so.
+ */
+export function parsePortArg(args, defaultPort) {
+  const at = args.indexOf("--port");
+  if (at === -1) return { port: defaultPort, explicit: false };
+  const raw = args[at + 1];
+  const parsed = Number.parseInt(raw ?? "", 10);
+  if (!Number.isInteger(parsed) || String(parsed) !== raw || parsed < 1 || parsed > 65535) {
+    return { error: `Invalid --port value: "${raw ?? ""}" (expected integer 1..65535)` };
+  }
+  return { port: parsed, explicit: true };
+}
+
+/**
+ * Which directory to run in, before it is made absolute.
+ * Precedence: `--cwd` (relative allowed) > CLAUDE_CWD > the directory the launcher was run
+ * from. `mustExist` is set only for `--cwd`: a typo there should stop the launch, while a
+ * CLAUDE_CWD naming a directory that isn't there yet is the managed-workspace case the
+ * server creates on boot.
+ */
+export function chooseCwd(args, env) {
+  const at = args.indexOf("--cwd");
+  if (at === -1) return { path: env.CLAUDE_CWD ?? ".", mustExist: false };
+  const value = args[at + 1];
+  // A missing value swallows the next flag ("--cwd --port 3000" would run in a directory
+  // called "--port"), so anything flag-shaped is treated as absent.
+  if (value === undefined || value.startsWith("-")) return { error: "--cwd requires a directory path" };
+  return { path: value, mustExist: true };
+}
+
+/**
+ * What to say when the port is taken.
+ *
+ * Running a second server is not a supported setup: both share ~/.mulmoterminal and the
+ * workspace, but each keeps its own PTYs, pub/sub and in-memory caches, so the two disagree
+ * about state neither can see the other change. Starting one silently on another port —
+ * which is what a plain second `npx mulmoterminal` used to do — is how someone ends up in
+ * that setup without knowing (#611).
+ *
+ * So the message has to answer the two things the user actually wants: where the running one
+ * is, and how to insist if a second is really wanted.
+ */
+export function portInUseMessage(port, explicit) {
+  const lines = [`Port ${port} is already in use.`];
+  lines.push(`  If that is MulmoTerminal, it is already running at http://localhost:${port}`);
+  lines.push(explicit ? "  Pick a different --port, or stop the other process." : "  To start a second one anyway: --port <number>");
+  return lines.join("\n");
+}
+
+/**
+ * What to do when the wanted port is taken: "ask" whether to start a second instance,
+ * or "stop".
+ *
+ * Two conditions rule the question out. An explicit --port already named the port that
+ * was wanted, so offering a different one answers a question nobody asked; and with no
+ * terminal to type into (a script, a service, CI) a prompt has nobody to answer it and
+ * would hang the start instead of failing it.
+ */
+export function portInUseAction(explicit, isTTY) {
+  return explicit || !isTTY ? "stop" : "ask";
+}
+
+/**
+ * The question asked when the default port is taken and there is somebody to answer.
+ *
+ * Two servers is not a supported setup (#611), but it is a legitimate thing to want on
+ * purpose — so the answer is a question rather than a refusal, and the default is no.
+ */
+export function secondInstancePrompt(port) {
+  return [`Port ${port} is already in use — MulmoTerminal may already be running at http://localhost:${port}`, "Start a second instance anyway? [y/N] "].join(
+    "\n",
+  );
+}
+
+/**
+ * Whether an answer to that question is a yes.
+ *
+ * Only an explicit yes counts. The prompt says [y/N], so Enter — and anything unrecognised —
+ * means no: starting a second server by misreading a stray keystroke is the outcome worth
+ * avoiding, and saying no costs one retyped command.
+ */
+export function saysYes(answer) {
+  return /^y(es)?$/i.test(String(answer ?? "").trim());
+}
+
+/**
+ * What someone who said yes should know before the second one comes up.
+ *
+ * One line, and only the part that is still true: config and the hidden-session list are
+ * safe across instances, but a session's tool history is cached per process and its live
+ * updates never cross — so the instance that did not start a session shows a frozen history
+ * for it (#611).
+ */
+export const SECOND_INSTANCE_NOTE = [
+  "  Note: both share ~/.mulmoterminal. A session's tool history does not live-update",
+  "  in the instance that did not start it.",
+].join("\n");
+
+const MIN_NODE_MAJOR = 22;
+const MIN_NODE_MINOR = 9;
+
+/**
+ * The lowest Node the `init` check reports as good, for the "needs ≥ x.y" line.
+ */
+export const MIN_NODE_LABEL = `${MIN_NODE_MAJOR}.${MIN_NODE_MINOR}`;
+
+/**
+ * Whether the running Node is new enough for the `init` pre-flight tick.
+ *
+ * `process.versions.node` is "major.minor.patch", with a "-prerelease" tag on the patch for
+ * nightlies ("22.9.0-nightly…"). Only major.minor gate, and Number.parseInt stops at the
+ * first non-digit, so that tag never reaches the comparison. A string that is not a version
+ * parses to NaN, and every comparison against NaN is false, so an unreadable version reads as
+ * "below minimum" — the safe direction for a display-only check.
+ */
+export function nodeMeetsMinimum(version) {
+  const [major, minor] = version.split(".").map((part) => Number.parseInt(part, 10));
+  return major > MIN_NODE_MAJOR || (major === MIN_NODE_MAJOR && minor >= MIN_NODE_MINOR);
+}