claude-garage 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Saiful Islam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,184 @@
+<div align="center">
+
+<img src="docs/banner.png" alt="claude-garage: a pit wall for your Claude Code agents" width="100%" />
+
+**Multiple Claude agents driving you crazy? Park them all in one
+garage.** Every session, every project, on one live wall: no window
+juggling, no tab hunting, and you know the instant one needs you.
+
+[![npm](https://img.shields.io/npm/v/claude-garage?color=e2a75e&label=npm)](https://www.npmjs.com/package/claude-garage)
+[![license](https://img.shields.io/badge/license-MIT-79b26e)](LICENSE)
+[![node](https://img.shields.io/badge/node-%E2%89%A5%2020-6e9ecc)](package.json)
+[![local](https://img.shields.io/badge/100%25-local-c6cfdb)](#local-only-by-design)
+
+<img src="docs/hero.png" alt="The pit wall: two workspaces, a session asking for permission (amber), a finished worktree session, and the diff pane" width="100%" />
+
+</div>
+
+## Why
+
+Running multiple Claude Code sessions across multiple projects means juggling
+terminal windows and editor windows. There is no single place to see:
+
+- **which sessions exist**, per project
+- **which one is blocked waiting for your input**. The real pain isn't window
+  count, it's attention routing
+- **what each session changed**, reviewable without hunting
+
+claude-garage is that single place: the garage your agents are parked in,
+one screen, built around four things that rarely coexist.
+
+1. 🔌 **Real terminals that survive the tool.** tmux owns every session, not
+   the app. Close the tab, kill the daemon, reboot the Mac:
+   `tmux attach -t garage/<workspace>/<label>` still works, and dead sessions
+   restore with their full conversation (`claude --resume`) in one click.
+2. 🖥️ **Every session of a project on screen at once.** Not a switcher, a
+   live grid of interactive terminals. Split, resize, maximize, float, or
+   detach into standalone views, VS Code-style.
+3. 🚨 **Needs-input triage as a first-class queue.** Blocked sessions sort
+   first everywhere, light up amber, count into the header badge and the tab
+   title; `a` jumps to whichever agent is waiting, across every project.
+   Notifications reach you even when the wall isn't visible.
+4. 📋 **File-by-file diff review with an editor jump.** Per-workspace or
+   per-worktree changes (committed and uncommitted), a full-screen review mode
+   with viewed-tracking, and `o` to open your editor at the exact line.
+
+## Quick start
+
+```bash
+npx claude-garage
+```
+
+Opens the pit wall at `http://127.0.0.1:4747`. Add a workspace, spawn
+sessions with the `+` next to its name, and press `?` for the keys.
+
+**Requirements**
+
+- macOS
+- [tmux](https://github.com/tmux/tmux) ≥ 3.2 (garage offers to `brew install` it if missing)
+- [Claude Code](https://docs.claude.com/en/docs/claude-code) CLI on `PATH`
+- Node.js ≥ 20
+
+**Hooks (recommended):** status updates poll every 2s by default. Click
+**install hooks for me** in the banner for instant detection. The daemon
+merges Claude Code's hooks into `~/.claude/settings.json` (backup kept,
+idempotent).
+
+## Local-only by design
+
+Everything runs on your machine and stays there.
+
+- The daemon binds to `127.0.0.1` only. Nothing listens on your network.
+- **No telemetry, no analytics, no accounts.** garage collects nothing and
+  phones home to no one.
+- All state is a single local file (`~/.garage/state.json`) plus your own
+  tmux server and git repos.
+- Your sessions talk to Claude exactly as they would without garage. The
+  wall is a viewer, not a middleman.
+
+## Session states
+
+| Glyph | State | Meaning |
+|---|---|---|
+| `●` | **needs-input** | Claude is waiting on *you*: permission, question, plan approval. Never fades; sorts first everywhere. |
+| `◐` | working | Claude is running. |
+| `✓` | done | Finished a turn since you last looked (fades after 2 min). |
+| `○` | idle | Waiting for you to *ask*, not to *answer*. |
+| `⟳` | restorable | tmux died (reboot?). One click resurrects the conversation. |
+
+## Also on the wall
+
+- 🌳 **Worktree sessions**: spawn in an isolated git worktree on a
+  `garage/<label>` branch; on close, **merge / discard / keep**.
+- 🎨 **Themes**: garage, claude dark, claude light, or follow the OS.
+  Terminals re-skin in place, full ANSI palettes included.
+- 🔔 **Notifications**: badge + tab title in-app, opt-in browser
+  notifications (click to jump) when the tab is hidden, and a macOS
+  notification when no page is open (clickable with
+  [`terminal-notifier`](https://github.com/julienXX/terminal-notifier)).
+
+## The pit pet 🐈
+
+An optional ASCII companion on the key strip whose mood *is* the wall:
+asleep when all is quiet, watching while agents run, **sprinting toward the
+rail with a `!`** the moment a session needs you (click it, that's the `a`
+jump), hiding in a box if the daemon drops, and celebrating when the last
+blocked session is answered. **Clicking it when nothing is wrong pets it.**
+It appreciates this.
+
+<div align="center">
+<img src="docs/pet-cat.png" width="130" alt="Arthur the shop cat" />
+<img src="docs/pet-duck.png" width="130" alt="Papito the rubber duck" />
+<img src="docs/pet-pup.png" width="130" alt="Segan the pit pup" />
+
+<b>Arthur</b> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <b>Papito</b> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <b>Segan</b>
+</div>
+
+Turn it on (or off again) anytime in ⚙ settings under *pit pet*. It's
+**off by default**: nobody gets a surprise Papito. Each species plays its
+state in character:
+
+| Pet | Personality |
+|---|---|
+| **Arthur** (shop cat) | saunters, barely deigns to bounce, ignores about 40% of your strolls, and celebrates by kneading in place. Cats don't jump for joy in front of you |
+| **Papito** (rubber duck) | deadpan: waddles, **never** bounces, and alerts with a single motionless stare; celebration is exactly one flap |
+| **Segan** (pit pup) | maximum enthusiasm: fastest runner, biggest bounce, and celebrates with zoomies across the strip |
+
+## Keybindings
+
+| Key | Action |
+|---|---|
+| `1`–`9` | switch focused workspace |
+| `[` / `]` | cycle terminals within the workspace |
+| `a` | jump to a session that needs input, anywhere |
+| `\` | split the focused cell (new session beside it) |
+| `m` | maximize the focused cell ⇄ restore |
+| `Tab` | changes pane: toggle list ⇄ diff emphasis |
+| `j` / `k` | next / previous changed file |
+| `r` | enter full-screen review mode |
+| `v` | (review mode) mark file viewed, advance to next unviewed |
+| `o` | open the selected file, or the workspace root, in your editor |
+| `Shift+Enter` | newline in Claude Code's composer (no `/terminal-setup` needed) |
+| `Ctrl+\`` | release keys from the terminal back to garage |
+| `?` | keybindings + status legend |
+
+Bindings pause while a terminal has keyboard focus. The header chip always
+shows where your keys go.
+
+## How it works
+
+```
+tmux  (persistence, source of truth)
+  └─ small Node daemon  (spawn / list / bridge / diff / hooks)
+       └─ browser UI  (React + xterm.js)
+```
+
+The daemon is a thin Fastify process that shells out to `tmux`/`git`/`claude`
+rather than re-implementing them; diffs are computed read-only; hook events
+are token-authed. The UI is a viewer over SSE + WebSockets. tmux is the
+registry: garage can be deleted and your sessions won't notice.
+
+## Development
+
+```bash
+npm install
+npm run dev     # daemon :4747 + Vite :5173
+npm test        # node:test suite (status, poller, hooks, layout, views)
+```
+
+Built through spec-driven phases ([`openspec/`](openspec/)), each verified
+end-to-end on a real system.
+
+## Roadmap
+
+- `claude-garage attach`: adopt an existing tmux session onto the wall
+- Phone push (ntfy/webhook) for when you're away from the machine
+- View renaming and drag-between-views
+- Linux support
+
+## License
+
+[MIT](LICENSE) © Saiful Islam
+
+*claude-garage is a community project, not affiliated with or endorsed by
+Anthropic. "Claude" and "Claude Code" are Anthropic trademarks.*

package/bin/garage.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+// D-packaging: the `npx claude-garage` entrypoint. Checks prerequisites,
+// starts the daemon in-process with GARAGE_SERVE_UI=1 (same-process
+// UI+API serving — see daemon/src/index.js), then prints and best-effort
+// opens the URL. Never touches tmux on shutdown — SIGINT/SIGTERM close the
+// HTTP server only, so live garage sessions survive the process exiting.
+import { execFile, spawn } from "node:child_process";
+import readline from "node:readline/promises";
+
+const PORT = Number(process.env.GARAGE_PORT ?? 4747);
+const HEALTH_URL = `http://127.0.0.1:${PORT}/api/health`;
+const UI_URL = `http://127.0.0.1:${PORT}`;
+
+function execFileP(cmd, args) {
+  return new Promise((resolve, reject) => {
+    execFile(cmd, args, (err, stdout, stderr) => {
+      if (err) reject(err);
+      else resolve({ stdout, stderr });
+    });
+  });
+}
+
+// Presence-only checks (D-packaging Open Questions: version-gate later if a
+// version-specific bug report ever surfaces). Missing binary produces a
+// readable, actionable error rather than letting the daemon fail deeper and
+// more cryptically the first time it shells out to a missing binary.
+async function requireBinary(bin, versionArgs, installHint) {
+  try {
+    await execFileP(bin, versionArgs);
+  } catch (err) {
+    if (err && err.code === "ENOENT") {
+      console.error(`${bin} not found — install: ${installHint}`);
+      process.exit(1);
+    }
+    // Any other failure (non-zero exit, odd version-flag behavior) is
+    // treated as "present" — we only gate on outright absence.
+  }
+}
+
+// tmux missing: offer to install it — consent-gated, never silent (the
+// README promises garage touches nothing without asking). Only when this
+// is an interactive terminal AND Homebrew is present; any other situation
+// falls back to the plain instruction. Streams brew's own output so the
+// user watches exactly what runs.
+async function offerTmuxInstall() {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return false;
+  try {
+    await execFileP("brew", ["--version"]);
+  } catch {
+    return false;
+  }
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  let answer;
+  try {
+    answer = (await rl.question("tmux not found. Install it now with Homebrew? [y/N] "))
+      .trim()
+      .toLowerCase();
+  } finally {
+    rl.close();
+  }
+  if (answer !== "y" && answer !== "yes") return false;
+  console.log("→ brew install tmux");
+  const ok = await new Promise((resolve) => {
+    const child = spawn("brew", ["install", "tmux"], { stdio: "inherit" });
+    child.on("exit", (code) => resolve(code === 0));
+    child.on("error", () => resolve(false));
+  });
+  if (!ok) return false;
+  try {
+    await execFileP("tmux", ["-V"]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function main() {
+  try {
+    await execFileP("tmux", ["-V"]);
+  } catch (err) {
+    if (err && err.code === "ENOENT") {
+      const installed = await offerTmuxInstall();
+      if (!installed) {
+        console.error("tmux not found — install: brew install tmux");
+        process.exit(1);
+      }
+    }
+    // any other failure (odd version-flag behavior) — treat as present,
+    // same discipline as requireBinary below
+  }
+  await requireBinary(
+    "claude",
+    ["--version"],
+    "see https://docs.claude.com/en/docs/claude-code for install instructions"
+  );
+
+  process.env.GARAGE_SERVE_UI = "1";
+
+  // Relative to this file's URL, not cwd — resolves correctly whether run
+  // from a checkout or an installed package (see root package.json `files`).
+  const { app } = await import("../daemon/src/index.js");
+
+  const shutdown = async () => {
+    // app.close() drains connections — but SSE streams and terminal
+    // WebSockets never end on their own, so a polite close hangs forever
+    // when a browser tab is open. Race it against a hard deadline: tmux
+    // owns everything that matters, so force-exiting loses nothing.
+    const deadline = new Promise((r) => setTimeout(r, 1500));
+    try {
+      await Promise.race([app.close(), deadline]);
+    } catch {
+      // best-effort — we're exiting regardless
+    } finally {
+      process.exit(0);
+    }
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+
+  setTimeout(async () => {
+    try {
+      const res = await fetch(HEALTH_URL);
+      if (!res.ok) throw new Error(`health check returned ${res.status}`);
+
+      console.log(`claude-garage pit wall → ${UI_URL}`);
+
+      if (process.platform === "darwin") {
+        // Best-effort convenience, same "never throw for a non-critical
+        // extra" discipline as notify.js's osascript call — swallow any
+        // failure silently.
+        execFile("open", [UI_URL], () => {});
+      }
+    } catch {
+      console.error(
+        `claude-garage did not come up on port ${PORT} — see the log above ` +
+          `(port already in use? set GARAGE_PORT to pick a different one)`
+      );
+      process.exit(1);
+    }
+  }, 600);
+}
+
+main();

package/daemon/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@claude-garage/daemon",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "dev": "node --watch src/index.js",
+    "start": "node src/index.js"
+  }
+}