@shumin13/claude-pet 0.1.2

package/README.md

@@ -0,0 +1,274 @@
+# Claude Pet
+
+Claude Pet is a lightweight macOS desktop companion for Claude Code. It listens to local Claude Code hook events, renders a small always-on-top robot overlay, and shows session state without making any model calls.
+
+The implementation is intentionally small:
+
+- Native macOS overlay built with Swift, Cocoa, and WebKit
+- Local Node.js event server bound to `127.0.0.1`
+- No Electron runtime
+- No runtime npm dependencies
+- No telemetry
+- No API keys, OAuth tokens, or credentials
+
+## Animated Demo
+
+<img src="https://raw.githubusercontent.com/shumin13/claude-pet/master/docs/assets/demo.gif" alt="Claude Pet demo showing ready, permission, idle, job done, one waiting notification, and multiple notifications" width="300">
+
+The animated demo cycles through ready, permission, idle, job done, one waiting notification, and multiple project notifications.
+
+Static reference images are available in `docs/assets/screenshots/`.
+
+## Requirements
+
+- macOS
+- Node.js 18 or newer
+- Claude Code with hook support
+
+The npm package ships with a prebuilt macOS overlay. Xcode command line tools are only needed if you are building from source or the prebuilt overlay is missing.
+
+## Install
+
+Install globally with npm:
+
+```sh
+npm install -g @shumin13/claude-pet
+```
+
+Then run setup:
+
+```sh
+claude-pet
+```
+
+That command asks where to install Claude Pet's app files, checks requirements, installs the native macOS overlay, and installs the Claude Code hooks. The default app location is `~/Library/Application Support/claude-pet/app`, which keeps hook paths stable even if your global npm directory changes. After setup, open a new Claude Code session and the pet will launch automatically.
+
+You can also pass the app location explicitly:
+
+```sh
+claude-pet --app-dir "$HOME/Applications/claude-pet"
+```
+
+Choose a dedicated Claude Pet folder. Setup refuses to copy app files into common directories like your home, Documents, Downloads, or Applications folder directly.
+
+Launch or preview it immediately:
+
+```sh
+claude-pet launch
+```
+
+Install or refresh only the Claude Code hooks:
+
+```sh
+claude-pet install-hooks
+```
+
+## Development
+
+Run tests:
+
+```sh
+npm test
+```
+
+Build the local native overlay used by this checkout:
+
+```sh
+npm run build:overlay:local
+```
+
+Build the prebuilt overlay that ships in the npm package:
+
+```sh
+npm run build:overlay:package
+```
+
+Create a source archive for sharing:
+
+```sh
+npm run package:zip
+```
+
+`package:zip` is optional. It writes `.build/claude-pet-source.zip` and is useful for sending the project as a single archive. GitHub users can ignore it and push the source tree directly.
+
+## Architecture
+
+Claude Pet has three small runtime pieces:
+
+| Layer          | Files                                                                           | Responsibility                                                                                                                         |
+| -------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| Event server   | `server.js`, `lib/`                                                             | Serves the UI, accepts local hook POSTs, streams events to the overlay with SSE, and filters noisy notifications.                      |
+| Native overlay | `macos/RobotPetOverlay.swift`                                                   | Creates the transparent always-on-top macOS window, hosts the WebKit view, supports native dragging, and cleans up PID files on close. |
+| Web UI         | `public/index.html`, `public/desktop.css`, `public/styles.css`, `public/app.js` | Renders the robot, notification bubbles, project grouping, collapsed badge, hover controls, preview controls, and resize behavior.     |
+
+The lifecycle scripts keep the overlay singleton across multiple Claude Code sessions:
+
+| Hook           | Script                                     | Behavior                                                                                                            |
+| -------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
+| `SessionStart` | `scripts/launch-desktop-if-needed.js`      | Starts the server and overlay if needed, records the active session, and avoids duplicate windows with a file lock. |
+| `Notification` | `hooks/claude-pet-notify.js`               | Sends permission, idle, and other notifications to the local server with a project/session label.                   |
+| `PostToolUse`  | `hooks/claude-pet-clear.js`                | Clears permission prompts once a tool completes.                                                                    |
+| `Stop`         | `hooks/claude-pet-stop.js`                 | Shows the job-done state for the current session.                                                                   |
+| `SessionEnd`   | `scripts/close-desktop-if-last-session.js` | Removes the active session and shuts down the overlay/server after the final session exits.                         |
+
+## Claude Code Hook Install
+
+Install or refresh the hooks automatically:
+
+```sh
+claude-pet install-hooks
+```
+
+The installer updates `~/.claude/settings.json` and preserves a timestamped backup before writing.
+
+Manual hook configuration is also supported. Replace `/path/to/claude-pet` with the absolute path to this package:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node /path/to/claude-pet/scripts/launch-desktop-if-needed.js"
+          }
+        ]
+      }
+    ],
+    "Notification": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node /path/to/claude-pet/hooks/claude-pet-notify.js"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node /path/to/claude-pet/hooks/claude-pet-clear.js"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node /path/to/claude-pet/hooks/claude-pet-stop.js"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node /path/to/claude-pet/scripts/close-desktop-if-last-session.js"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Runtime Configuration
+
+| Variable                 | Default                                            | Purpose                                                                                    |
+| ------------------------ | -------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `CLAUDE_PET_PORT`        | `37421`                                            | Local server port.                                                                         |
+| `CLAUDE_PET_ENDPOINT`    | `http://127.0.0.1:${CLAUDE_PET_PORT}/events`       | Hook POST target.                                                                          |
+| `CLAUDE_PET_APP_DIR`     | `~/Library/Application Support/claude-pet/app`     | Setup destination for stable app files and hook script paths.                              |
+| `CLAUDE_PET_BUILD_DIR`   | `~/Library/Application Support/claude-pet`         | User-writable runtime directory for the native overlay, PID files, module cache, and logs. |
+| `CLAUDE_PET_ROOT`        | Repository root                                    | Used by the native overlay for cleanup paths.                                              |
+| `CLAUDE_PET_DESKTOP_URL` | `http://127.0.0.1:${CLAUDE_PET_PORT}/desktop.html` | Web UI URL loaded by the native overlay.                                                   |
+
+The server binds to `127.0.0.1` only.
+
+## UI Behavior
+
+Claude Pet keeps one overlay window for all active Claude Code sessions. Multiple sessions do not create multiple pets.
+
+Supported states:
+
+- `ready`: quiet visible robot, no startup bubble, subtle blink
+- `permission_prompt`: priority state with alert badge and permission bubble
+- `idle_prompt`: waiting state with sleepy expression and blink
+- `job_done`: completion state with smaller success smile
+- multiple projects: one compact bubble per project
+- collapsed notifications: compact count badge near the pet
+
+Interaction behavior:
+
+- Drag the pet body to move the native overlay
+- Hover to reveal minimize, close, and resize controls
+- Drag the lower-right resize handle for smooth manual resizing
+- Click the collapsed badge or pet to expand notifications
+
+## Static Preview
+
+The desktop UI can be opened directly for development:
+
+```text
+/path/to/claude-pet/public/index.html
+```
+
+Demo states can be rendered with query parameters when served through the local server:
+
+```text
+http://127.0.0.1:37421/desktop.html?demo=ready
+http://127.0.0.1:37421/desktop.html?demo=permission
+http://127.0.0.1:37421/desktop.html?demo=idle
+http://127.0.0.1:37421/desktop.html?demo=done
+http://127.0.0.1:37421/desktop.html?demo=one
+http://127.0.0.1:37421/desktop.html?demo=multi
+http://127.0.0.1:37421/desktop.html?demo=multi&collapsed=true
+```
+
+## Privacy And Repository Safety
+
+Claude Pet is local-only. It does not send prompts, transcripts, notifications, or usage data to a remote service.
+
+The repository should not contain secrets. A push-readiness scan should only find documentation references to words such as "token" or "API key", not actual credentials.
+
+Local/generated files are ignored:
+
+- `.build/`
+- `node_modules/`
+- `.env*`
+- log files
+- `.DS_Store`
+- coverage output
+- local Claude settings such as `~/.claude/settings.json`
+
+Recommended checks before publishing:
+
+```sh
+rg -n -i "(api[_-]?key|secret|token|password|passwd|authorization|bearer|private[_-]?key|BEGIN (RSA|OPENSSH|PRIVATE)|sk-[A-Za-z0-9]|xox[baprs]-|gh[pousr]_[A-Za-z0-9]|AIza[0-9A-Za-z_-]|AKIA[0-9A-Z]{16})" . -g '!node_modules/**' -g '!.build/**' -g '!*.zip'
+npm test
+npm run build:overlay:package
+npm pack --dry-run
+```
+
+## Project Layout
+
+```text
+.
+├── hooks/                Claude Code event hooks
+├── lib/                  Shared config, runtime helpers, locks, session labels
+├── macos/                Native Swift overlay
+├── public/               Desktop UI
+├── scripts/              Launch, shutdown, hook install, desktop runner
+├── tests/                Integration tests
+├── docs/assets/          README screenshots and demo media
+├── server.js             Local event server
+└── prebuilt/             Packaged macOS overlay binary
+```

package/bin/claude-pet.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const binDir = dirname(fileURLToPath(import.meta.url));
+const root = join(binDir, "..");
+const defaultAppDir = join(homedir(), "Library", "Application Support", "claude-pet", "app");
+
+const commands = new Map([
+  ["setup", ["scripts/setup.js"]],
+  ["launch", ["scripts/launch-desktop-if-needed.js"]],
+  ["install-hooks", ["scripts/install-claude-hook.js"]],
+  ["server", ["server.js"]]
+]);
+
+const aliases = new Map([
+  ["start", "launch"],
+  ["hooks", "install-hooks"]
+]);
+
+function printHelp() {
+  console.log(`Claude Pet
+
+Usage:
+  claude-pet               Set up hooks and install the overlay
+  claude-pet setup         Set up hooks and install the overlay
+  claude-pet --app-dir DIR Install stable app files in DIR during setup
+  claude-pet launch        Launch or preview the pet now
+  claude-pet install-hooks Install or refresh Claude Code hooks
+  claude-pet server        Run the local event server
+
+Install:
+  npm install -g @shumin13/claude-pet`);
+}
+
+function run(script, args = []) {
+  const scriptRoot = script[0].startsWith(defaultAppDir) ? defaultAppDir : root;
+  const child = spawn(process.execPath, [...script, ...args], {
+    cwd: scriptRoot,
+    stdio: "inherit"
+  });
+  child.on("exit", code => {
+    process.exit(code || 0);
+  });
+  child.on("error", error => {
+    console.error(error?.message || error);
+    process.exit(1);
+  });
+}
+
+function commandScript(command) {
+  const script = commands.get(command);
+  if (!script || command === "setup") return script;
+
+  const stableScript = join(defaultAppDir, script[0]);
+  const marker = join(defaultAppDir, ".claude-pet-app");
+  if (existsSync(marker) && existsSync(stableScript)) {
+    return [stableScript];
+  }
+
+  return script;
+}
+
+const rawCommand = process.argv[2] || "setup";
+const commandArgs = process.argv.slice(3);
+const command = aliases.get(rawCommand) || rawCommand;
+
+if (command === "help" || command === "--help" || command === "-h") {
+  printHelp();
+  process.exit(0);
+}
+
+const script = rawCommand.startsWith("-") ? commands.get("setup") : commandScript(command);
+if (!script) {
+  console.error(`Unknown command: ${rawCommand}`);
+  console.error("");
+  printHelp();
+  process.exit(1);
+}
+
+run(script, rawCommand.startsWith("-") ? process.argv.slice(2) : commandArgs);

package/hooks/claude-pet-clear.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+
+import { eventsUrl } from "../lib/config.js";
+import { postJson } from "../lib/runtime.js";
+
+const endpoint = process.env.CLAUDE_PET_ENDPOINT || eventsUrl;
+
+try {
+  await postJson(endpoint, {
+    type: "ready",
+    title: "Claude Pet is awake",
+    message: "Waiting for Claude Code notifications.",
+    replay: true
+  });
+} catch {
+  process.exitCode = 1;
+}

package/hooks/claude-pet-notify.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+import { labelForEvent, withSessionPrefix } from "../lib/session-labels.js";
+import { eventsUrl } from "../lib/config.js";
+import { postJson, readStdinJson } from "../lib/runtime.js";
+
+const endpoint = process.env.CLAUDE_PET_ENDPOINT || eventsUrl;
+const ignoredTypes = new Set(["auth_success"]);
+const genericBashPermission = "Claude needs your permission to use Bash";
+
+try {
+  const event = await readStdinJson();
+  const type = event.notification_type || event.type;
+  if (!ignoredTypes.has(type) && !(type === "permission_prompt" && String(event.message || "").trim() === genericBashPermission)) {
+    const label = await labelForEvent(event);
+    const response = await postJson(endpoint, {
+      ...event,
+      message: withSessionPrefix(event.message, label),
+      replay: false
+    });
+
+    if (!response.ok) process.exitCode = 1;
+  }
+} catch {
+  process.exitCode = 1;
+}

package/hooks/claude-pet-stop.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+
+import { labelForEvent, withSessionPrefix } from "../lib/session-labels.js";
+import { eventsUrl } from "../lib/config.js";
+import { postJson, readStdinJson } from "../lib/runtime.js";
+
+const endpoint = process.env.CLAUDE_PET_ENDPOINT || eventsUrl;
+
+try {
+  const event = await readStdinJson();
+  const label = await labelForEvent(event);
+  const message = event.stop_hook_active
+    ? "Claude finished and skipped recursive stop hooks."
+    : "Claude finished the current response.";
+
+  await postJson(endpoint, {
+    type: "job_done",
+    title: "Job done",
+    message: withSessionPrefix(message, label),
+    replay: false
+  });
+} catch {
+  process.exitCode = 1;
+}

package/lib/config.js

@@ -0,0 +1,19 @@
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+export const root = fileURLToPath(new URL("..", import.meta.url));
+export const port = process.env.CLAUDE_PET_PORT || process.env.PORT || "37421";
+export const buildDir = process.env.CLAUDE_PET_BUILD_DIR || join(homedir(), "Library", "Application Support", "claude-pet");
+export const swiftModuleCacheDir = join(buildDir, "module-cache");
+export const logDir = join(buildDir, "logs");
+export const overlayPath = join(buildDir, "robot-pet-overlay");
+export const overlayPidFile = join(buildDir, "robot-pet-overlay.pid");
+export const serverPidFile = join(buildDir, "claude-pet-server.pid");
+export const sessionsFile = join(buildDir, "active-claude-sessions.json");
+export const lifecycleLockDir = join(buildDir, "claude-pet-lifecycle.lock");
+export const swiftSource = join(root, "macos", "RobotPetOverlay.swift");
+export const prebuiltOverlayPath = join(root, "prebuilt", "macos", "robot-pet-overlay");
+export const healthUrl = `http://127.0.0.1:${port}/health`;
+export const eventsUrl = `http://127.0.0.1:${port}/events`;
+export const desktopUrl = `http://127.0.0.1:${port}/desktop.html`;

package/lib/lock.js

@@ -0,0 +1,35 @@
+import { mkdir, rmdir, stat } from "node:fs/promises";
+
+export async function withFileLock(lockDir, fn, options = {}) {
+  const timeoutMs = options.timeoutMs ?? 5000;
+  const retryMs = options.retryMs ?? 50;
+  const staleMs = options.staleMs ?? 15000;
+  const deadline = Date.now() + timeoutMs;
+
+  while (true) {
+    try {
+      await mkdir(lockDir, { recursive: false });
+      break;
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      try {
+        const details = await stat(lockDir);
+        if (Date.now() - details.mtimeMs > staleMs) await rmdir(lockDir);
+      } catch {
+        // If the lock disappeared between checks, retry immediately.
+      }
+      if (Date.now() >= deadline) throw error;
+      await new Promise(resolve => setTimeout(resolve, retryMs));
+    }
+  }
+
+  try {
+    return await fn();
+  } finally {
+    try {
+      await rmdir(lockDir);
+    } catch {
+      // Another cleanup path may already have removed it.
+    }
+  }
+}

package/lib/overlay-binary.js

@@ -0,0 +1,104 @@
+import { access, chmod, copyFile, mkdir, rm, stat } from "node:fs/promises";
+import { constants } from "node:fs";
+import { dirname } from "node:path";
+import { spawn } from "node:child_process";
+import {
+  overlayPath,
+  prebuiltOverlayPath,
+  root,
+  swiftModuleCacheDir,
+  swiftSource
+} from "./config.js";
+
+export async function commandExists(command) {
+  try {
+    await run(command, ["--version"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function executable(path) {
+  try {
+    await access(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function hasPrebuiltOverlay() {
+  return executable(prebuiltOverlayPath);
+}
+
+export function run(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: root,
+      stdio: options.stdio || "inherit",
+      env: {
+        ...process.env,
+        CLANG_MODULE_CACHE_PATH: swiftModuleCacheDir,
+        ...options.env
+      }
+    });
+    child.on("error", reject);
+    child.on("exit", code => {
+      if (code === 0) resolve();
+      else reject(new Error(`${command} exited with ${code}`));
+    });
+  });
+}
+
+async function targetIsCurrentWithPrebuilt() {
+  if (!(await executable(overlayPath))) return false;
+  const [prebuiltStat, overlayStat] = await Promise.all([stat(prebuiltOverlayPath), stat(overlayPath)]);
+  return overlayStat.size === prebuiltStat.size && overlayStat.mtimeMs >= prebuiltStat.mtimeMs;
+}
+
+async function targetIsCurrentWithSource() {
+  if (!(await executable(overlayPath))) return false;
+  const [sourceStat, overlayStat] = await Promise.all([stat(swiftSource), stat(overlayPath)]);
+  return overlayStat.mtimeMs >= sourceStat.mtimeMs;
+}
+
+export async function ensureOverlayBinary({ quiet = false } = {}) {
+  if (await hasPrebuiltOverlay()) {
+    if (await targetIsCurrentWithPrebuilt()) {
+      if (!quiet) console.log("Native overlay is already installed.");
+      return "current";
+    }
+
+    if (!quiet) console.log("Installing prebuilt native macOS overlay...");
+    await mkdir(dirname(overlayPath), { recursive: true });
+    await copyFile(prebuiltOverlayPath, overlayPath);
+    await chmod(overlayPath, 0o755);
+    return "prebuilt";
+  }
+
+  if (await targetIsCurrentWithSource()) {
+    if (!quiet) console.log("Native overlay is already built.");
+    return "current";
+  }
+
+  if (!(await commandExists("swiftc"))) {
+    throw new Error("Xcode command line tools are required because no prebuilt overlay was found and swiftc is not available.");
+  }
+
+  if (!quiet) console.log("Building native macOS overlay...");
+  await rm(swiftModuleCacheDir, { recursive: true, force: true });
+  await mkdir(swiftModuleCacheDir, { recursive: true });
+  await mkdir(dirname(overlayPath), { recursive: true });
+  await run("swiftc", [
+    "macos/RobotPetOverlay.swift",
+    "-framework",
+    "Cocoa",
+    "-framework",
+    "WebKit",
+    "-o",
+    overlayPath
+  ]);
+  await rm(swiftModuleCacheDir, { recursive: true, force: true });
+  return "built";
+}

package/lib/runtime.js

@@ -0,0 +1,49 @@
+import { readFile, unlink } from "node:fs/promises";
+
+export async function readStdinJson() {
+  if (process.stdin.isTTY) return {};
+
+  let input = "";
+  process.stdin.setEncoding("utf8");
+  for await (const chunk of process.stdin) input += chunk;
+  try {
+    return input.trim() ? JSON.parse(input) : {};
+  } catch {
+    return {};
+  }
+}
+
+export async function postJson(endpoint, payload) {
+  return fetch(endpoint, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(payload)
+  });
+}
+
+export async function readPid(path) {
+  try {
+    const pid = Number((await readFile(path, "utf8")).trim());
+    return pid || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function isAlive(pid) {
+  if (!pid) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function removeFile(path) {
+  try {
+    await unlink(path);
+  } catch {
+    // Already gone.
+  }
+}