mulmoterminal 1.1.0 → 1.3.0

package/README.md

@@ -1,28 +1,57 @@
 # mulmoterminal
 
-A browser-based terminal + GUI workspace for coding agents — [Claude Code](https://claude.com/claude-code)
-and OpenAI's **Codex** — with a sidebar that lists the current project's chat sessions
-and shows live, hook-driven activity for each one.
-
-Each session runs as a real PTY on the server (the agent CLI in a pseudo-terminal) and
-is streamed to an [xterm.js](https://xtermjs.org/) terminal in the browser over a
-WebSocket. A sidebar lists every session for the project and reflects, in real time,
-which sessions are **working** (the agent is thinking) and which **need attention**
-(waiting for input, or finished with output you haven't seen).
-
-Around the terminal sit the things a coding session needs: a **grid** of parallel
-sessions, an optional **GUI panel** for rich tool output (documents, forms, images,
-charts), **git worktree** isolation with one-click **push / open PR**, a full-screen
-**file browser + editor**, per-session **cost & token** readouts, a cross-repo **PRs &
-Issues** view, and read-only **Wiki** and **Collections** browsers over the shared
-workspace.
-
-**Inserting a file path** — like a native terminal, you can put a file's absolute
-path into the prompt: **drag a file** onto the terminal (works where the browser
-exposes the path via `file://` — Firefox/Safari), or click the **📎 file button**
-in the terminal header, which asks the local server to open the OS file dialog and
-inserts the chosen path (works in every browser, including Chrome). The path is
-inserted at the cursor — it is not submitted, so you can review it first.
+**Run a whole team of coding agents from your browser — and actually keep up with them.**
+
+MulmoTerminal turns [Claude Code](https://claude.com/claude-code) (and OpenAI's **Codex**)
+into a parallel, observable workspace: many agent sessions at once in a grid, each one
+color-coded so you see at a glance which are **working**, which **need you**, and which are
+**done** — plus rich GUI output, git worktrees with one-click PRs, cost readouts, and a
+ping to your phone when a task finishes. One `npx` command, no Electron, no config.
+
+```bash
+npx mulmoterminal        # starts on http://localhost:34567 and opens your browser
+```
+
+## Why you'll want it
+
+- **See every agent at once.** A grid of live sessions, each cell color-coded by state —
+  **working** (blue), **blocked / needs a permission** (amber), **done, unreviewed** (blue),
+  **idle** — with an attention chime and a toolbar tally, so an off-screen agent that's stuck
+  never slips past you. Stop babysitting one terminal; supervise ten.
+- **A GUI for your agents, not just a terminal.** Beside the terminal, a **Canvas** panel
+  renders what an agent produces over MCP — **documents, forms, charts, generated images,
+  HTML, collection cards** — each drawn by its own plugin. The agent doesn't just print
+  text; it hands you an interface.
+- **Get pulled back from anywhere.** A finished background task sends a **Web Push to your
+  phone**, and the **RemoteHost** companion lets you watch and start sessions from the phone
+  itself — walk away, get pinged, jump back in.
+- **Nothing is lost on a restart.** With `tmux`, every session survives a server crash,
+  restart, or `node --watch` reload — a mid-turn agent, a long build, a dev server all keep
+  running and reattach when you come back.
+- **Ship without leaving the grid.** Each repo cell shows a **git branch chip**, isolates
+  work in a one-click **git worktree**, opens a **diff** panel, and does **commit / push /
+  open PR** — so several agents can work the same repo without colliding.
+- **Know what it's costing.** Per-session **context %**, **token**, and **estimated $**
+  readouts, an **activity timeline** of tool calls, and **AI-summarized** cell titles and
+  command-output explanations — so a wall of parallel agents stays legible.
+- **Make it yours.** Per-directory **themes, colors, and name badges** (`prod` in red,
+  `staging` in amber), a configurable header (buttons + info chips), custom attention sounds,
+  and Run / Skill menus to launch a project's scripts and `.claude/skills` right inside a cell.
+
+### What it is, under the hood
+
+Each session runs as a real PTY on the server (the agent CLI in a pseudo-terminal) and is
+streamed to an [xterm.js](https://xtermjs.org/) terminal in the browser over a WebSocket. A
+sidebar lists every session for the project and reflects, in real time, which are **working**
+(the agent is thinking) and which **need attention** (waiting for input, or finished with
+output you haven't seen) — driven by Claude/Codex activity hooks the server injects per spawn.
+
+**Inserting a file path** — like a native terminal, you can put a file's absolute path into
+the prompt: **drag a file** onto the terminal (works where the browser exposes the path via
+`file://` — Firefox/Safari), or click the **📎 file button** in the terminal header, which
+asks the local server to open the OS file dialog and inserts the chosen path (works in every
+browser, including Chrome). The path is inserted at the cursor — it is not submitted, so you
+can review it first.
 
 ---
 
@@ -41,6 +70,27 @@ npm install -g mulmoterminal
 mulmoterminal
 ```
 
+**First-run setup (optional).** `npx mulmoterminal init` checks your environment (Node ≥ 22.9,
+the `claude` CLI, plus optional `tmux` / `gh` / `codex`), seeds the launcher's **directory
+presets** from the projects in your Claude Code history, and writes `~/.mulmoterminal/config.json`.
+It's **idempotent** — re-run it any time to refresh the presets; it overwrites the managed parts
+and keeps your other settings. When `claude` is installed it can hand off to the
+`/mulmoterminal-config` skill for interactive tweaks.
+
+**Google account (optional).** Link a Google account to enable the chat's `google` tool and the
+phone's `google.calendar.*` commands: read/create events on any calendar (not just your primary),
+list the calendars you've subscribed to, and read the colour palettes. Sign in from
+**Settings → Google account**, or run `npx mulmoterminal google login` — the CLI is the fallback
+for when you're driving MulmoTerminal from another machine, since consent finishes on a loopback
+listener and needs a browser **on the host**. Either way it needs a Desktop OAuth client JSON saved
+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.
+
+> **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
+> `google login`). Reading/creating events on your primary calendar keeps working without re-linking.
+
 A global install isn't auto-updated, so on startup MulmoTerminal checks npm and
 prints a one-line notice when a newer version is available (`npm i -g mulmoterminal`
 to update). Disable with `MULMOTERMINAL_NO_UPDATE_CHECK=1` (or `NO_UPDATE_NOTIFIER=1`).
@@ -1083,22 +1133,26 @@ resumed session falls back to any on-disk `ai-title`.
 server/
   index.ts        Express app, /api routes, upgrade routing, PTY lifecycle,
                   session state, hook injection, session discovery, GUI-MCP mount
-  agents/         AgentAdapter seam — claude.ts, codex.ts, registry.ts
-  codex-*.ts      Codex sessions, args, rollout discovery, skill mirroring
-  tmux.ts         tmux-backed session persistence (own -L mulmoterminal server)
-  sandbox.ts      Docker sandbox spawn for the single-view Claude session
-  worktrees.ts, worktree-*.ts   git worktree create/list/diff/push/PR + routes
-  git-status.ts, gitRemote.ts, gh.ts, prs.ts, issues.ts   git & GitHub (via gh)
-  cost.ts, transcript.ts        cost estimate; usage/context from transcripts
-  files-browse.ts               file tree + read/write (contained to project root)
-  scripts.ts                    Run-menu script.json loader
-  command-summary.ts            POST /api/command/summarize (claude -p headless)
-  header-title.ts               cheap-model AI title for the cell header (recent turns)
-  app-config.ts, config-routes.ts, dir-config.ts   user + per-directory config
-  plugins-registry.ts, mcp/     GUI plugin registry + per-session MCP broker
-  backends/                     wiki, collections, feeds, accounting, notifier,
-                                translation, whisper, remote-host, html, files
-  pubsub.ts                     socket.io pub/sub at /ws/pubsub
+  agents/         AgentAdapter seam + per-agent args/sessions: claude.ts,
+                  codex.ts, registry.ts, claude-args.ts, codex-args.ts,
+                  codex-session(s).ts, codex-skills.ts
+  config/         user + per-directory + header config: app-config.ts,
+                  config-routes.ts, config-schema.ts, dir-config.ts,
+                  cwd-presets.ts, header-*.ts
+  session/        per-session transcript/activity/cost: transcript.ts,
+                  session-resolve.ts, activity-*.ts, cost.ts,
+                  command-summary.ts, terminal-replay.ts, file-cache.ts
+  git/            git & GitHub (via gh) + worktrees: git-status.ts, gitRemote.ts,
+                  gh.ts, prs.ts, issues.ts, pr-for-branch.ts, worktrees.ts, worktree-*.ts
+  files/          files-browse.ts (contained tree read/write), pick-file.ts,
+                  open-dir.ts, scripts.ts (Run-menu script.json loader)
+  infra/          process/transport/misc: tmux.ts, tmux-routes.ts, sandbox.ts,
+                  pubsub.ts (socket.io /ws/pubsub), spa-fallback.ts, host-tools.ts,
+                  plugins-registry.ts, web-push.ts, install-config-skill.ts, accounting-tool.ts
+  mcp/            per-session MCP broker
+  backends/       wiki, collections, feeds, accounting, notifier,
+                  translation, whisper, remote-host, html, files
+  skills/         bundled mulmoterminal-config skill assets
   fix-pty-perms.js              postinstall: fixes node-pty binary permissions
 src/
   App.vue                       Layout; owns the active session + single/grid view

package/bin/mulmoterminal.js

@@ -11,6 +11,7 @@ import { get as httpGet } from "node:http";
 import { createRequire } from "node:module";
 import { createServer } from "node:net";
 import { dirname, join, resolve } from "node:path";
+import { createInterface } from "node:readline";
 import { fileURLToPath } from "node:url";
 import { fetchLatestVersion, isNewerVersion } from "./update-check.js";
 
@@ -46,18 +47,104 @@ function checkForUpdate() {
     });
 }
 
-function claudeInstalled() {
+// Detect a CLI on the user's PATH by asking for its version. Intentionally resolves from
+// PATH — detecting the user's installed tools is the whole point of the pre-flight /
+// `init` checks.
+function hasCommand(cmd, versionArg = "--version") {
   try {
-    // Intentionally resolves `claude` from the user's PATH — detecting their
-    // Claude Code CLI install is the whole point of this pre-flight check.
     // eslint-disable-next-line sonarjs/no-os-command-from-path
-    execSync("claude --version", { stdio: "pipe" });
+    execSync(`${cmd} ${versionArg}`, { stdio: "pipe" });
     return true;
   } catch {
     return false;
   }
 }
 
+function claudeInstalled() {
+  return hasCommand("claude");
+}
+
+function promptYesNo(question) {
+  return new Promise((res) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => {
+      rl.close();
+      res(/^y(es)?$/i.test(answer.trim()));
+    });
+  });
+}
+
+// `npx mulmoterminal init` — idempotent first-run setup. Environment/CLI checks + the
+// optional interactive-config launch live here (PATH-command detection); the config
+// derivation + write is the tsx-run server/cli-init.ts.
+async function runInit(initArgs) {
+  log("Setting up MulmoTerminal…\n");
+
+  const [maj, min] = process.versions.node.split(".").map((n) => Number.parseInt(n, 10));
+  const nodeOk = maj > 22 || (maj === 22 && min >= 9);
+  console.log(nodeOk ? `  ✓ Node ${process.versions.node}` : `  ✗ Node ${process.versions.node} — MulmoTerminal needs ≥ 22.9`);
+
+  const hasClaude = claudeInstalled();
+  if (hasClaude) {
+    console.log("  ✓ Claude Code CLI");
+  } else {
+    console.log("  ✗ Claude Code CLI — not found");
+    console.log("      → npm install -g @anthropic-ai/claude-code   (then run `claude` and log in)");
+  }
+
+  for (const [cmd, versionArg, why, hint] of [
+    ["tmux", "-V", "sessions survive a restart", "brew install tmux  ·  apt install tmux"],
+    ["gh", "--version", "PRs & Issues view + one-click PRs", "https://cli.github.com  (then: gh auth login)"],
+    ["codex", "--version", "run OpenAI Codex as an agent", "npm install -g @openai/codex"],
+  ]) {
+    console.log(hasCommand(cmd, versionArg) ? `  ✓ ${cmd} — ${why}` : `  ○ ${cmd} — optional (${why})\n      → ${hint}`);
+  }
+
+  // Config half: derive working-dir presets from Claude history + write config.json.
+  console.log("");
+  const initExit = await new Promise((res) => {
+    const child = spawn(process.execPath, ["--import", "tsx", join(PKG_DIR, "server", "cli-init.ts"), ...initArgs], {
+      cwd: PKG_DIR,
+      env: { ...process.env },
+      stdio: "inherit",
+    });
+    child.on("exit", (code) => res(code ?? 0));
+  });
+  if (initExit) {
+    process.exitCode = initExit;
+    error("Setup did not complete — see the error above.");
+    return;
+  }
+
+  // Offer the interactive skill only in a real terminal; a non-TTY run (CI / piped input)
+  // must never block waiting on stdin.
+  if (hasClaude && process.stdin.isTTY && (await promptYesNo("\nConfigure interactively now with the /mulmoterminal-config skill? [y/N] "))) {
+    log("Launching Claude — use  /mulmoterminal-config  (or just ask it to configure MulmoTerminal).");
+    // eslint-disable-next-line sonarjs/no-os-command-from-path
+    spawn("claude", ["Use the mulmoterminal-config skill to configure MulmoTerminal."], { stdio: "inherit" });
+    return;
+  }
+  if (hasClaude) log("Later: run `claude` in any project and use  /mulmoterminal-config");
+  log("Setup done. Start MulmoTerminal:  npx mulmoterminal");
+}
+
+// `npx mulmoterminal google <command>` — Google account linking. Consent needs a
+// loopback listener on this machine, so it can't be driven from the web UI (a phone
+// browser can't reach 127.0.0.1 here); the flow lives in the tsx-run server/cli-google.ts.
+function runGoogle(googleArgs) {
+  return new Promise((res) => {
+    const child = spawn(process.execPath, ["--import", "tsx", join(PKG_DIR, "server", "cli-google.ts"), ...googleArgs], {
+      cwd: PKG_DIR,
+      env: { ...process.env },
+      stdio: "inherit",
+    });
+    child.on("exit", (code) => {
+      process.exitCode = code ?? 0;
+      res();
+    });
+  });
+}
+
 function pickOpenCommand() {
   if (process.platform === "darwin") return "open";
   if (process.platform === "win32") return "start";
@@ -225,12 +312,17 @@ function runServer(port, noOpen, cwd, onChild) {
   });
 }
 
-async function main() {
-  const args = process.argv.slice(2);
+function printHelp() {
+  console.log(`
+Usage: npx mulmoterminal [command] [options]
 
-  if (args.includes("--help") || args.includes("-h")) {
-    console.log(`
-Usage: npx mulmoterminal [options]
+Commands:
+  (none)            Start the server (default)
+  init              First-run setup: check your environment, seed working-directory
+                    presets from your Claude Code history, and write
+                    ~/.mulmoterminal/config.json (idempotent — safe to re-run)
+  google login      Link a Google account (browser consent, on this machine) so the
+                    Calendar tool and the phone's google.calendar.* commands can run
 
 Options:
   --cwd <dir>       Working directory claude runs in (default: current directory; relative paths allowed)
@@ -239,6 +331,23 @@ Options:
   --version         Show version
   --help            Show this help
 `);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args[0] === "init") {
+    await runInit(args.slice(1));
+    return;
+  }
+
+  if (args[0] === "google") {
+    await runGoogle(args.slice(1));
+    return;
+  }
+
+  if (args.includes("--help") || args.includes("-h")) {
+    printHelp();
     return;
   }
   if (args.includes("--version")) {

package/common/themeColors.ts

@@ -0,0 +1,30 @@
+// The xterm ITheme keys a `.mulmoterminal.json` `colors` block may override. Shared across
+// the build boundary: the server config schema validates/strips a config against this set,
+// and the client dir-config parser re-checks the server-sanitized response against the same
+// set. Kept in common/ so the two can't drift — a key in one list but not the other would be
+// silently accepted on one side and dropped on the other.
+export const THEME_COLOR_KEYS = [
+  "foreground",
+  "background",
+  "cursor",
+  "cursorAccent",
+  "selectionBackground",
+  "selectionForeground",
+  "selectionInactiveBackground",
+  "black",
+  "red",
+  "green",
+  "yellow",
+  "blue",
+  "magenta",
+  "cyan",
+  "white",
+  "brightBlack",
+  "brightRed",
+  "brightGreen",
+  "brightYellow",
+  "brightBlue",
+  "brightMagenta",
+  "brightCyan",
+  "brightWhite",
+] as const;

package/dist/assets/{abnfDiagram-VRR7QNED-6nNByj6v-DGtwdUf8.js → abnfDiagram-VRR7QNED-6nNByj6v-SXl7Pz9E.js}

@@ -1 +1 @@
-import{n as e}from"./chunk-Y2CYZVJY-Bdt8pFDJ-DsF7k-Jl.js";import{f as t}from"./src-Brzfja-q-ch1VcTiG.js";import{_ as n,g as r}from"./mermaid-parser.core-DC7NPJ_M-IqvgPv4-.js";import"./chunk-WYO6CB5R-B83L_z6I-DOF2nExc.js";import"./chunk-VAUOI2AC-DrcykVNK-Dj0ZfRKp.js";import{n as i,r as a,t as o}from"./chunk-MOJQB5TN-CqxshQHA--ID4cJe7.js";import{t as s}from"./chunk-JWPE2WC7-BQ3zXr2k-DSd3Ct95.js";var c=r().RailroadAbnf.parser.LangiumParser,l=e(e=>{let t=e.alternatives.map(u);return t.length===1?t[0]:{type:`choice`,alternatives:t}},`transformAlternation`),u=e(e=>{let t=e.elements.map(f);return t.length===1?t[0]:{type:`sequence`,elements:t}},`transformConcatenation`),d=e(e=>{if(e.includes(`*`)){let[t,n]=e.split(`*`);return{min:t?parseInt(t,10):0,max:n?parseInt(n,10):1/0}}let t=parseInt(e,10);return{min:t,max:t}},`parseRepeat`),f=e(e=>{let t=p(e.primary);if(!e.repeat)return t;let{min:n,max:r}=d(e.repeat);return n===0&&r===1?{type:`optional`,element:t}:{type:`repetition`,element:t,min:n,max:r}},`transformElement`),p=e(e=>{switch(e.$type){case`AbnfStringLiteral`:return{type:`terminal`,value:e.value};case`AbnfNumVal`:return{type:`terminal`,value:e.value};case`AbnfRuleName`:return{type:`nonterminal`,name:e.name};case`AbnfGroup`:return l(e.element);case`AbnfOptionalGroup`:return{type:`optional`,element:l(e.element)};default:throw Error(`Unsupported ABNF primary node: ${e.$type}`)}},`transformPrimary`),m=e(e=>({name:e.name,definition:l(e.definition)}),`transformRule`),h=e(e=>{s(e,a),e.title&&a.setTitle(e.title),e.rules.map(e=>a.addRule(m(e)))},`populateDb`),g={parser:{parse:e(e=>{a.clear(),t.debug(`[ABNF Parser] Starting Langium parse`);let r=c.parse(e);if(r.lexerErrors.length>0||r.parserErrors.length>0)throw new n(r);let i=r.value;t.debug(`[ABNF Parser] Parsed rules:`,i.rules.length),h(i),t.debug(`[ABNF Parser] Parse complete`)},`parse`),parser:{yy:a}},db:a,renderer:o,styles:i};export{g as diagram};
+import{n as e}from"./chunk-Y2CYZVJY-Bdt8pFDJ-DsF7k-Jl.js";import{f as t}from"./src-Brzfja-q-ch1VcTiG.js";import{_ as n,g as r}from"./mermaid-parser.core-DC7NPJ_M-BaedRaqr.js";import"./chunk-WYO6CB5R-B83L_z6I-DnTETCPT.js";import"./chunk-VAUOI2AC-DrcykVNK-Bu15Aaxk.js";import{n as i,r as a,t as o}from"./chunk-MOJQB5TN-CqxshQHA-ClImkhQQ.js";import{t as s}from"./chunk-JWPE2WC7-BQ3zXr2k-DSd3Ct95.js";var c=r().RailroadAbnf.parser.LangiumParser,l=e(e=>{let t=e.alternatives.map(u);return t.length===1?t[0]:{type:`choice`,alternatives:t}},`transformAlternation`),u=e(e=>{let t=e.elements.map(f);return t.length===1?t[0]:{type:`sequence`,elements:t}},`transformConcatenation`),d=e(e=>{if(e.includes(`*`)){let[t,n]=e.split(`*`);return{min:t?parseInt(t,10):0,max:n?parseInt(n,10):1/0}}let t=parseInt(e,10);return{min:t,max:t}},`parseRepeat`),f=e(e=>{let t=p(e.primary);if(!e.repeat)return t;let{min:n,max:r}=d(e.repeat);return n===0&&r===1?{type:`optional`,element:t}:{type:`repetition`,element:t,min:n,max:r}},`transformElement`),p=e(e=>{switch(e.$type){case`AbnfStringLiteral`:return{type:`terminal`,value:e.value};case`AbnfNumVal`:return{type:`terminal`,value:e.value};case`AbnfRuleName`:return{type:`nonterminal`,name:e.name};case`AbnfGroup`:return l(e.element);case`AbnfOptionalGroup`:return{type:`optional`,element:l(e.element)};default:throw Error(`Unsupported ABNF primary node: ${e.$type}`)}},`transformPrimary`),m=e(e=>({name:e.name,definition:l(e.definition)}),`transformRule`),h=e(e=>{s(e,a),e.title&&a.setTitle(e.title),e.rules.map(e=>a.addRule(m(e)))},`populateDb`),g={parser:{parse:e(e=>{a.clear(),t.debug(`[ABNF Parser] Starting Langium parse`);let r=c.parse(e);if(r.lexerErrors.length>0||r.parserErrors.length>0)throw new n(r);let i=r.value;t.debug(`[ABNF Parser] Parsed rules:`,i.rules.length),h(i),t.debug(`[ABNF Parser] Parse complete`)},`parse`),parser:{yy:a}},db:a,renderer:o,styles:i};export{g as diagram};

package/dist/assets/architecture-TIHT7OUA-CYMWc3UT-BLPeuYWZ.js

@@ -0,0 +1 @@
+import{f as e}from"./mermaid-parser.core-DC7NPJ_M-BaedRaqr.js";export{e as createArchitectureServices};