mintree 0.5.5 → 0.5.8

package/README.md

@@ -292,6 +292,7 @@ Linear authentication lives in `~/.mintree/credentials.json` (user-scoped, not p
 - **Sessions persist by issue**: each issue gets a UUID stored in `metadata.json`. Subsequent `worktree work` calls pass `--resume <uuid>` so Claude reopens the same conversation.
 - **Live state** (optional): the four hooks installed by `mintree helpers session-signal install` write the current Claude state to `.mintree/session-states/<issue>.json` on every prompt / stop / notification / session-end. The dashboard reads those files to colour each row in real time.
 - **Remote Control** (optional): `mintree doctor` checks `~/.claude.json` for `remoteControlAtStartup: true`. Enabling it lets you continue a local session from a different device.
+- **iTerm2 session badge** (automatic): when you launch on [iTerm2](https://iterm2.com), mintree sets the terminal **badge** — the large translucent label drawn over the session — to the session name (the worktree issue id like `VAL-68`, or the orchestrator's name) so each tab stays identifiable at a glance. It uses the badge rather than the tab title because Claude Code overwrites the title while it runs; the badge is independent of it and persists for the whole session, then clears on exit. No-op on other terminals (detected via `TERM_PROGRAM` / `LC_TERMINAL`).
 
 ---
 

package/dist/lib/claude.js

@@ -2,6 +2,7 @@ import { execSync, spawn } from "child_process";
 import { existsSync, writeFileSync } from "fs";
 import { homedir, tmpdir } from "os";
 import { join } from "path";
+import { setITermBadge, clearITermBadge } from "./terminal.js";
 export const PERMISSION_MODES = ["default", "auto"];
 /**
  * Resolves the absolute path of the Claude Code CLI binary, or null if not on
@@ -74,5 +75,17 @@ export function launchClaude(options) {
     if (options.prompt && options.prompt.length > 0) {
         args.push("--", promptArg(options.prompt));
     }
-    return spawn(bin, args, { stdio: "inherit", cwd: options.cwd });
+    // Label the session with an iTerm2 badge before handing over the TTY. The
+    // badge survives Claude overwriting the terminal title, so the tab stays
+    // identifiable (worktree issue id, or orchestrator name) while it runs.
+    // No-op outside iTerm2.
+    const badge = options.remoteControlName;
+    if (badge)
+        setITermBadge(badge);
+    const child = spawn(bin, args, { stdio: "inherit", cwd: options.cwd });
+    // Clear the badge once Claude exits so the badge doesn't linger on the
+    // shell that regains the TTY.
+    if (badge)
+        child.on("exit", () => clearITermBadge());
+    return child;
 }

package/dist/lib/terminal.d.ts

@@ -0,0 +1,13 @@
+/** True when the active terminal is iTerm2 (also detected through tmux). */
+export declare function isITerm(): boolean;
+/**
+ * Builds the raw iTerm2 SetBadgeFormat escape sequence for `text`. Pure (no I/O)
+ * so it can be unit-tested; an empty string clears the badge. The badge format
+ * supports `\(...)` interpolation in iTerm2, but plain ids/labels carry no
+ * parens so the base64-encoded literal renders verbatim.
+ */
+export declare function buildBadgeSequence(text: string): string;
+/** Sets the iTerm2 badge to `text`. No-op outside iTerm2 or with empty text. */
+export declare function setITermBadge(text: string): void;
+/** Clears the iTerm2 badge. No-op outside iTerm2. */
+export declare function clearITermBadge(): void;

package/dist/lib/terminal.js

@@ -0,0 +1,55 @@
+// iTerm2 badge integration.
+//
+// Claude Code overwrites the terminal title (OSC 0/2) while it runs and exposes
+// no way to disable that or pin a custom title, so a tab title we set before
+// launching wouldn't survive. The iTerm2 *badge* — a large translucent label
+// drawn over the session — is independent of the title and Claude never touches
+// it, so it's the one reliable way to identify a mintree session at a glance
+// (e.g. the worktree issue id `VAL-68`, or `orchestrator-VAL-12_BE-16`).
+//
+// Everything here is a no-op outside iTerm2, so callers can invoke it
+// unconditionally.
+const BEL = String.fromCharCode(7); // \a (BEL)
+const ESC = String.fromCharCode(27); // \e (ESC)
+/** True when the active terminal is iTerm2 (also detected through tmux). */
+export function isITerm() {
+    return process.env["TERM_PROGRAM"] === "iTerm.app" || process.env["LC_TERMINAL"] === "iTerm2";
+}
+// tmux swallows unknown escape sequences unless they're wrapped in its DCS
+// passthrough (with every inner ESC doubled). Harmless when not in tmux, but we
+// only wrap when $TMUX is set to keep the common case clean.
+function wrapForTmux(seq) {
+    if (!process.env["TMUX"])
+        return seq;
+    const doubled = seq.split(ESC).join(ESC + ESC);
+    return `${ESC}Ptmux;${doubled}${ESC}\\`;
+}
+/**
+ * Builds the raw iTerm2 SetBadgeFormat escape sequence for `text`. Pure (no I/O)
+ * so it can be unit-tested; an empty string clears the badge. The badge format
+ * supports `\(...)` interpolation in iTerm2, but plain ids/labels carry no
+ * parens so the base64-encoded literal renders verbatim.
+ */
+export function buildBadgeSequence(text) {
+    const b64 = Buffer.from(text, "utf8").toString("base64");
+    return wrapForTmux(`${ESC}]1337;SetBadgeFormat=${b64}${BEL}`);
+}
+function writeToTty(seq) {
+    // We only call this right before spawning Claude / right after it exits,
+    // moments when the parent process owns the TTY. Skip when stdout isn't a TTY
+    // (piped/CI) — there's no terminal to talk to.
+    if (process.stdout.isTTY)
+        process.stdout.write(seq);
+}
+/** Sets the iTerm2 badge to `text`. No-op outside iTerm2 or with empty text. */
+export function setITermBadge(text) {
+    if (!isITerm() || !text)
+        return;
+    writeToTty(buildBadgeSequence(text));
+}
+/** Clears the iTerm2 badge. No-op outside iTerm2. */
+export function clearITermBadge() {
+    if (!isITerm())
+        return;
+    writeToTty(buildBadgeSequence(""));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "mintree",
-	"version": "0.5.5",
+	"version": "0.5.8",
 	"description": "Issue-driven git worktrees + Claude Code sessions for repos with an opinionated SDD+TDD flow.",
 	"license": "MIT",
 	"author": "Martin Mineo <mmineo@canarytechnologies.com>",