mulmoterminal 1.0.0 → 1.2.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,13 @@ 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.
+
 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`).
@@ -71,6 +107,7 @@ server, and opens the browser. For local development from a clone, see
 - [Configuration](#configuration)
 - [Running](#running)
 - [Scripts (Run menu)](#scripts-run-menu)
+- [Skills (Skill menu)](#skills-skill-menu)
 - [Files view (browse & edit)](#files-view-browse--edit)
 - [Git worktrees & pull requests](#git-worktrees--pull-requests)
 - [Cost & token usage](#cost--token-usage)
@@ -495,6 +532,39 @@ the last 32 KB of output. See
 
 ---
 
+## Skills (Skill menu)
+
+Next to the **▶ Run ▾** dropdown, every running terminal's header has a **⚡ Skill ▾**
+dropdown — in both the single view and each grid cell, and **only when the open
+project has skills** (nothing discovered, no button). It lists the
+[Claude skills](https://docs.claude.com/en/docs/claude-code/skills) discoverable for
+that terminal's directory — both **project scope** (`<dir>/.claude/skills`) and **user
+scope** (`~/.claude/skills`), the same skills Claude sees — and, on pick, **runs the
+skill in that session**: it types the skill's invocation into the terminal and submits
+it (for Claude, its `/<slug>` command; for Codex, which has no slash command, a plain
+`Use the "<slug>" skill.` instruction). Unlike **▶ Run** — which launches a
+`script.json` shell command in a spare cell — a skill runs **in the session you
+picked it from**, continuing that conversation.
+
+**Ordering:** working-dir (project) skills come **first**, then user-scope ones,
+alphabetical within each group; a project skill of the same slug shadows the user one.
+
+**Filtering:** add a `skills` array to the directory's
+[`.mulmoterminal.json`](#per-directory-settings-projectmulmoterminaljson) to narrow the menu —
+an allowlist of slugs that also sets the order (only those show, in that order). Omit
+it to show everything.
+
+```jsonc
+// <dir>/.mulmoterminal.json
+{ "skills": ["review-diff", "commit-msg"] }
+```
+
+Each menu item shows the skill's id, with its `SKILL.md` `description` as the hover
+tooltip. A directory (or workspace) without any `.claude/skills` simply shows no
+button. Skills are discovered read-only; the menu never creates or edits them.
+
+---
+
 ## Files view (browse & edit)
 
 A terminal header can carry a **📁 Files** button — add it as a [header button](#header-buttons)
@@ -683,6 +753,30 @@ position the client sends back to `/ws/run`).
 A missing or invalid `script.json` is **not** an error — it yields an empty
 `scripts` array.
 
+### HTTP: `GET /api/skills`
+
+The Claude skills discoverable for a terminal's chosen directory (`?cwd=<dir>`,
+falling back to `CLAUDE_CWD`) — project scope (`<cwd>/.claude/skills`) plus user scope
+(`~/.claude/skills`), deduped by slug (project shadows user), **working-dir skills
+first**; see [Skills (Skill menu)](#skills-skill-menu). A `skills` allowlist in that
+directory's `.mulmoterminal.json` narrows and reorders the result; absent → all. The
+resolved `cwd` is echoed back. Each entry carries its `slug` (the skill invoked as
+`/<slug>`) and the `SKILL.md` `description` (the menu tooltip).
+
+```jsonc
+// GET /api/skills?cwd=/Users/me/proj
+{
+  "cwd": "/Users/me/proj",
+  "skills": [
+    { "slug": "commit", "description": "Write a commit message" },
+    { "slug": "review", "description": "Review the current diff" }
+  ]
+}
+```
+
+A directory without any discoverable skills is **not** an error — it yields an empty
+`skills` array.
+
 ### HTTP: `POST /api/command/summarize`
 
 Runs `claude -p` **headless** over a command cell's captured terminal output and
@@ -1025,22 +1119,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,87 @@ 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");
+}
+
 function pickOpenCommand() {
   if (process.platform === "darwin") return "open";
   if (process.platform === "win32") return "start";
@@ -225,12 +295,15 @@ 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)
 
 Options:
   --cwd <dir>       Working directory claude runs in (default: current directory; relative paths allowed)
@@ -239,6 +312,18 @@ 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.includes("--help") || args.includes("-h")) {
+    printHelp();
     return;
   }
   if (args.includes("--version")) {

package/dist/assets/{abnfDiagram-VRR7QNED-6nNByj6v-DheBdjws.js → abnfDiagram-VRR7QNED-6nNByj6v-CK1tLzZi.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-CcAjWs6c.js";import"./chunk-WYO6CB5R-B83L_z6I-CTQn5U85.js";import"./chunk-VAUOI2AC-DrcykVNK-jGzw5YJX.js";import{n as i,r as a,t as o}from"./chunk-MOJQB5TN-CqxshQHA-ozqXE506.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-CdLorTPK.js";import"./chunk-WYO6CB5R-B83L_z6I-C1WGAsfM.js";import"./chunk-VAUOI2AC-DrcykVNK-Cm1y1eF0.js";import{n as i,r as a,t as o}from"./chunk-MOJQB5TN-CqxshQHA-hb8sT9ul.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-H5BlYssV.js

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