claude-garage 0.1.0

package/daemon/src/tmux.js

@@ -0,0 +1,124 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const run = promisify(execFile);
+
+export const GARAGE_PREFIX = "garage/";
+export const NAME_RE = /^[a-z0-9-]+$/;
+
+export function sessionId(workspace, label) {
+  return `${GARAGE_PREFIX}${workspace}/${label}`;
+}
+
+// `=` forces exact-name matching; bare -t does prefix matching.
+const exact = (id) => `=${id}`;
+
+export async function listSessions() {
+  let stdout;
+  try {
+    ({ stdout } = await run("tmux", [
+      "ls",
+      "-F",
+      "#{session_name}\t#{session_path}\t#{session_attached}",
+    ]));
+  } catch {
+    // tmux exits non-zero when no server is running — that means "no sessions".
+    return [];
+  }
+  return stdout
+    .split("\n")
+    .filter((line) => line.startsWith(GARAGE_PREFIX))
+    .map((line) => {
+      const [name, dir, attached] = line.split("\t");
+      const [, workspace, label] = name.split("/");
+      return { id: name, workspace, label, dir, attached: attached !== "0" };
+    });
+}
+
+// D-branch: live pane cwd per garage session, keyed by session name — NOT
+// `session_path` (that's the session's *starting* dir, frozen at creation;
+// a user who `cd`s into a worktree inside the pane changes pane_current_path
+// but not session_path). `-a` lists every pane on the server across every
+// session, so results are filtered to the garage prefix same as
+// listSessions(). A session can have multiple panes/windows if the user
+// split it manually — only the first pane encountered per session is kept,
+// there's no principled way to pick "the" cwd of a multi-pane session.
+export async function listPanePaths() {
+  let stdout;
+  try {
+    ({ stdout } = await run("tmux", [
+      "list-panes",
+      "-a",
+      "-F",
+      "#{session_name}\t#{pane_current_path}",
+    ]));
+  } catch {
+    // No tmux server running — no panes.
+    return new Map();
+  }
+  const paths = new Map();
+  for (const line of stdout.split("\n")) {
+    if (!line.startsWith(GARAGE_PREFIX)) continue;
+    const [name, panePath] = line.split("\t");
+    if (!paths.has(name)) paths.set(name, panePath);
+  }
+  return paths;
+}
+
+// D-branch: shared by sessions.js (per-session, keyed off live pane cwd)
+// and workspaces.js (per-workspace, keyed off the registered dir) — both
+// just need "what branch is HEAD at in this directory", so the git call
+// lives here once. `null` for anything that isn't a usable git working
+// dir (no dir, not a repo, dir vanished, etc.) rather than throwing —
+// callers render it as "no chip" and must never let a git failure break
+// the sessions/workspaces list response.
+export async function resolveBranch(dir) {
+  if (!dir) return null;
+  try {
+    const { stdout } = await run("git", ["-C", dir, "rev-parse", "--abbrev-ref", "HEAD"]);
+    const branch = stdout.trim();
+    if (branch && branch !== "HEAD") return branch;
+    // Detached HEAD — abbrev-ref returns the literal string "HEAD" — fall
+    // back to a short sha, prefixed so it's visually distinct from a real
+    // branch name in the UI chip.
+    const { stdout: sha } = await run("git", ["-C", dir, "rev-parse", "--short", "HEAD"]);
+    const short = sha.trim();
+    return short ? `@${short}` : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function hasSession(id) {
+  try {
+    await run("tmux", ["has-session", "-t", exact(id)]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// extraArgs are appended as separate argv entries after `command` — tmux
+// joins the trailing shell-command words itself (e.g. `command, "--resume",
+// sessionId` becomes the pane's `claude --resume <sessionId>`), so callers
+// must not pre-join them into a single string.
+export async function createSession(id, dir, command, extraArgs = []) {
+  await run("tmux", ["new-session", "-d", "-s", id, "-c", dir, command, ...extraArgs]);
+  // The pit wall renders its own session title bars, so tmux's status line
+  // is visual noise in every grid cell. Per-session option — a plain
+  // `tmux attach` escape-hatch user can restore it with `set status on`.
+  // set-option does not accept the `=` exact-match target prefix; the full
+  // freshly-created name is unambiguous here.
+  await run("tmux", ["set-option", "-t", id, "status", "off"]).catch(() => {});
+}
+
+export async function killSession(id) {
+  await run("tmux", ["kill-session", "-t", exact(id)]);
+}
+
+// D-rename: renames the tmux session entity itself. Attached clients (grid
+// ptys, iTerm) stay attached across a rename — they're bound to the session
+// entity, not its name — so this is safe to call on a live, attached session.
+export async function renameSession(oldId, newId) {
+  await run("tmux", ["rename-session", "-t", exact(oldId), newId]);
+}

package/daemon/src/workspaces.js

@@ -0,0 +1,139 @@
+import { stat } from "node:fs/promises";
+import {
+  GARAGE_PREFIX,
+  NAME_RE,
+  listSessions,
+  renameSession,
+  resolveBranch,
+  killSession,
+} from "./tmux.js";
+import {
+  listWorkspaces,
+  upsertWorkspace,
+  getWorkspace,
+  renameWorkspace,
+  removeWorkspace,
+} from "./registry.js";
+
+export default async function workspaceRoutes(app) {
+  // D-branch: same helper as sessions.js's per-session branch (tmux.js's
+  // resolveBranch), keyed off the registered dir instead of a live pane
+  // cwd — a registered workspace has no pane of its own. This route isn't
+  // hit on every SSE tick the way GET /api/sessions is, so no per-request
+  // dedup here; a plain per-workspace resolve is cheap enough at this
+  // scale (one execFile pair per registered workspace).
+  app.get("/api/workspaces", async () => {
+    const workspaces = await listWorkspaces();
+    return Promise.all(
+      workspaces.map(async (w) => ({ ...w, branch: await resolveBranch(w.dir) }))
+    );
+  });
+
+  app.put("/api/workspaces", async (req, reply) => {
+    const { name, dir } = req.body ?? {};
+
+    if (!NAME_RE.test(name ?? "")) {
+      return reply.code(400).send({ error: "name must match [a-z0-9-]+" });
+    }
+    const dirStat = await stat(dir ?? "").catch(() => null);
+    if (!dirStat?.isDirectory()) {
+      return reply.code(400).send({ error: `dir is not a directory: ${dir}` });
+    }
+
+    const workspace = await upsertWorkspace(name, dir);
+    return reply.code(200).send(workspace);
+  });
+
+  // D-rename: renames everything that embeds the workspace name — the
+  // registry key, every live tmux session under it, and their
+  // resume-metadata keys. Live-session renames happen first (best-effort,
+  // no rollback on partial failure per design) so a mid-flight failure
+  // still leaves the registry consistent with whichever sessions actually
+  // got renamed.
+  app.patch("/api/workspaces/:name", async (req, reply) => {
+    const oldName = req.params.name;
+    const { name: newName } = req.body ?? {};
+
+    const existing = await getWorkspace(oldName);
+    if (!existing) {
+      return reply.code(404).send({ error: `unknown workspace: ${oldName}` });
+    }
+    if (!NAME_RE.test(newName ?? "")) {
+      return reply.code(400).send({ error: "name must match [a-z0-9-]+" });
+    }
+    if (newName !== oldName && (await getWorkspace(newName))) {
+      return reply
+        .code(409)
+        .send({ error: `workspace already registered: ${newName}` });
+    }
+
+    const oldPrefix = `${GARAGE_PREFIX}${oldName}/`;
+    const newPrefix = `${GARAGE_PREFIX}${newName}/`;
+    const live = (await listSessions()).filter((s) => s.id.startsWith(oldPrefix));
+
+    const renamedSessions = [];
+    const failedSessions = [];
+    for (const s of live) {
+      const newId = newPrefix + s.id.slice(oldPrefix.length);
+      try {
+        await renameSession(s.id, newId);
+        renamedSessions.push({ from: s.id, to: newId });
+      } catch (err) {
+        failedSessions.push({ id: s.id, error: err.message ?? String(err) });
+      }
+    }
+
+    const workspace = await renameWorkspace(oldName, newName);
+
+    const response = { ...workspace, renamedSessions };
+    if (failedSessions.length > 0) {
+      response.failedSessions = failedSessions;
+    }
+    return reply.code(200).send(response);
+  });
+
+  // Removing a workspace by default NEVER touches tmux: the registry is a
+  // directory mapping, not a session store. Live sessions keep running and
+  // reappear in the rail as an unregistered group; the workspace's resume
+  // metadata is dropped (removeWorkspace handles that) so no
+  // permanently-unrestorable ghosts linger.
+  //
+  // p7 follow-up: `?sessions=kill` opts into shutting the workspace down
+  // for real — every live garage/<name>/* tmux session is killed first,
+  // then the registry entry (and, via removeWorkspace, the resume
+  // metadata) is removed. Per-session kill failures are reported without
+  // aborting the rest. Worktree directories/branches are deliberately left
+  // untouched — bulk removal must never silently discard branch work; they
+  // remain recoverable via plain git.
+  app.delete("/api/workspaces/:name", async (req, reply) => {
+    const name = req.params.name;
+    if (!(await getWorkspace(name))) {
+      return reply.code(404).send({ error: `unknown workspace: ${name}` });
+    }
+
+    const killMode = req.query?.sessions === "kill";
+    if (!killMode) {
+      await removeWorkspace(name);
+      return reply.code(204).send();
+    }
+
+    const prefix = `${GARAGE_PREFIX}${name}/`;
+    const live = (await listSessions()).filter((s) => s.id.startsWith(prefix));
+    const killedSessions = [];
+    const failedSessions = [];
+    for (const s of live) {
+      try {
+        await killSession(s.id);
+        killedSessions.push(s.id);
+      } catch (err) {
+        failedSessions.push({ id: s.id, error: err.message ?? String(err) });
+      }
+    }
+
+    await removeWorkspace(name);
+
+    const response = { removed: name, killedSessions };
+    if (failedSessions.length > 0) response.failedSessions = failedSessions;
+    return reply.code(200).send(response);
+  });
+}

package/daemon/src/worktrees.js

@@ -0,0 +1,180 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { existsSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+
+const run = promisify(execFile);
+
+// D-wt-location: outside any repo, so a worktree never pollutes `git status`
+// for the repo itself. Keyed by workspace so `~/.garage/worktrees/<ws>/` is
+// one place to `ls` per workspace.
+const WORKTREES_ROOT = path.join(homedir(), ".garage", "worktrees");
+
+// D-wt-branch: namespaced so a repo's real branches never collide with ours,
+// and so the discard/merge cleanup guard below can refuse to touch anything
+// that isn't ours.
+const GARAGE_BRANCH_PREFIX = "garage/";
+
+async function git(dir, args) {
+  try {
+    return await run("git", ["-C", dir, ...args]);
+  } catch (err) {
+    // execFile's rejection already carries .stderr/.stdout when the process
+    // ran and exited non-zero; wrap so callers get a clean .message (git's
+    // stderr, trimmed) while still exposing the raw stderr for surfacing to
+    // the API caller (D-wt-finish: merge conflicts return git's stderr).
+    const wrapped = new Error(err.stderr?.trim() || err.message);
+    wrapped.stderr = err.stderr;
+    wrapped.cause = err;
+    throw wrapped;
+  }
+}
+
+function assertGarageBranch(branch) {
+  if (typeof branch !== "string" || !branch.startsWith(GARAGE_BRANCH_PREFIX)) {
+    const err = new Error(`refusing to touch non-garage branch: ${branch}`);
+    err.statusCode = 400;
+    throw err;
+  }
+}
+
+async function branchExists(repoDir, branch) {
+  try {
+    await run("git", ["-C", repoDir, "rev-parse", "--verify", "--quiet", `refs/heads/${branch}`]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// D-wt-location / D-wt-branch: both the directory and the branch name are
+// derived from the same candidate label, suffixed together (-2, -3, ...)
+// until a candidate is free on both axes — keeps `garage/<label>` and its
+// worktree dir visually paired even after a collision.
+async function pickCandidate(repoDir, workspace, label) {
+  const baseDir = path.join(WORKTREES_ROOT, workspace);
+  let suffix = 1;
+  let candidate = label;
+  for (;;) {
+    const dirPath = path.join(baseDir, candidate);
+    const branch = `${GARAGE_BRANCH_PREFIX}${candidate}`;
+    const dirTaken = existsSync(dirPath);
+    const branchTaken = dirTaken || (await branchExists(repoDir, branch));
+    if (!dirTaken && !branchTaken) return { dirPath, branch };
+    suffix += 1;
+    candidate = `${label}-${suffix}`;
+  }
+}
+
+// Creates `~/.garage/worktrees/<workspace>/<label>` (suffixed on collision)
+// as a new git worktree on a fresh `garage/<label>` branch cut from repoDir's
+// current HEAD. Throws a 400 error (with git's stderr as .message) if repoDir
+// isn't a git repo or `git worktree add` fails for any reason (dirty/locked
+// repo state, etc.) — callers should surface err.statusCode / err.message
+// directly, no session or tmux state is created before this succeeds.
+export async function createWorktree({ repoDir, workspace, label }) {
+  try {
+    await run("git", ["-C", repoDir, "rev-parse", "--is-inside-work-tree"]);
+  } catch {
+    const err = new Error(`not a git repository: ${repoDir}`);
+    err.statusCode = 400;
+    throw err;
+  }
+
+  const { dirPath, branch } = await pickCandidate(repoDir, workspace, label);
+  await mkdir(path.dirname(dirPath), { recursive: true });
+
+  try {
+    await run("git", ["-C", repoDir, "worktree", "add", "-b", branch, dirPath]);
+  } catch (err) {
+    const wrapped = new Error(err.stderr?.trim() || err.message);
+    wrapped.statusCode = 400;
+    throw wrapped;
+  }
+
+  return { path: dirPath, branch };
+}
+
+// D-wt-finish: runs after the session is dead — repoDir/path/branch come
+// from the worktree record the caller already holds (DELETE's response
+// body), never re-derived. `merge` and `discard` are guarded to garage/*
+// branches so this can never touch a repo's real branches even if a caller
+// passes a bogus record. `keep` is a deliberate no-op so the UI's three-way
+// finish prompt is uniform (dismissing it is equivalent).
+export async function finishWorktree({ repoDir, path: wtPath, branch, action }) {
+  if (action === "keep") {
+    return { action: "keep", path: wtPath, branch };
+  }
+
+  if (action !== "merge" && action !== "discard") {
+    const err = new Error(`unknown action: ${action}`);
+    err.statusCode = 400;
+    throw err;
+  }
+
+  assertGarageBranch(branch);
+
+  if (action === "merge") {
+    // The most common failure isn't a conflict — it's an agent that edited
+    // but never committed: the branch has nothing to merge and `worktree
+    // remove` would refuse anyway. Catch it up front with a human message.
+    const dirty = await git(wtPath, ["status", "--porcelain"]).catch(() => null);
+    if (dirty?.stdout && dirty.stdout.trim() !== "") {
+      const err = new Error(
+        "worktree has uncommitted changes — commit them in the session first, or discard"
+      );
+      err.statusCode = 409;
+      throw err;
+    }
+    try {
+      await git(repoDir, ["merge", "--no-ff", branch]);
+    } catch (err) {
+      // D-wt-finish: non-zero exit -> 409, worktree and branch kept, the
+      // user resolves manually (no conflict UI in v1).
+      const conflictErr = new Error(err.message);
+      conflictErr.statusCode = 409;
+      conflictErr.stderr = err.stderr;
+      throw conflictErr;
+    }
+    await git(repoDir, ["worktree", "remove", wtPath]);
+    await git(repoDir, ["branch", "-d", branch]);
+    return { action: "merge", path: wtPath, branch, merged: true };
+  }
+
+  // discard
+  await git(repoDir, ["worktree", "remove", "--force", wtPath]);
+  await git(repoDir, ["branch", "-D", branch]);
+  return { action: "discard", path: wtPath, branch, discarded: true };
+}
+
+export default async function worktreeRoutes(app) {
+  app.post("/api/worktrees/finish", async (req, reply) => {
+    const { worktree, action } = req.body ?? {};
+
+    if (!worktree || typeof worktree !== "object") {
+      return reply.code(400).send({ error: "worktree record required" });
+    }
+    const { path: wtPath, branch, repoDir } = worktree;
+    if (!wtPath || !branch || !repoDir) {
+      return reply
+        .code(400)
+        .send({ error: "worktree record requires path, branch, and repoDir" });
+    }
+    if (!["merge", "discard", "keep"].includes(action)) {
+      return reply
+        .code(400)
+        .send({ error: "action must be one of merge, discard, keep" });
+    }
+
+    try {
+      const result = await finishWorktree({ repoDir, path: wtPath, branch, action });
+      return reply.code(200).send(result);
+    } catch (err) {
+      const body = { error: err.message };
+      if (err.stderr) body.stderr = err.stderr;
+      return reply.code(err.statusCode ?? 500).send(body);
+    }
+  });
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "claude-garage",
+  "version": "0.1.0",
+  "description": "Multiple Claude agents driving you crazy? Park them all in one garage: every session on one live terminal wall, no window juggling. Needs-input triage, worktree isolation, diff review. tmux owns the sessions; close the app and nothing dies.",
+  "license": "MIT",
+  "author": "Saiful Islam <saifulislamadar@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adar2378/claude-garage.git"
+  },
+  "homepage": "https://github.com/adar2378/claude-garage#readme",
+  "bugs": "https://github.com/adar2378/claude-garage/issues",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "tmux",
+    "terminal",
+    "agents",
+    "session-manager",
+    "dashboard",
+    "xterm",
+    "git-worktree",
+    "developer-tools"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "claude-garage": "bin/garage.js"
+  },
+  "files": [
+    "bin",
+    "daemon/src",
+    "daemon/package.json",
+    "ui/dist"
+  ],
+  "workspaces": [
+    "daemon",
+    "ui"
+  ],
+  "scripts": {
+    "dev": "concurrently -n daemon,ui -c blue,magenta \"npm:dev --workspace daemon\" \"npm:dev --workspace ui\"",
+    "test": "node --test \"daemon/test/*.test.js\" \"ui/test/*.test.js\"",
+    "postinstall": "chmod +x node_modules/node-pty/prebuilds/darwin-*/spawn-helper 2>/dev/null || true",
+    "prepack": "npm run build --workspace ui"
+  },
+  "dependencies": {
+    "@fastify/static": "^10.1.0",
+    "fastify": "^5.3.0",
+    "node-pty": "^1.1.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "concurrently": "^10.0.3"
+  }
+}