@tekyzinc/gsd-t 2.17.0 → 2.18.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [2.18.0] - 2026-02-16
+
+### Added
+- Heartbeat system — real-time event streaming from Claude Code sessions via async hooks
+- `scripts/gsd-t-heartbeat.js` — hook handler that writes JSONL events to `.gsd-t/heartbeat-{session_id}.jsonl`
+- 9 Claude Code hooks: SessionStart, PostToolUse, SubagentStart, SubagentStop, TaskCompleted, TeammateIdle, Notification, Stop, SessionEnd
+- Installer auto-configures heartbeat hooks in settings.json (all async, zero performance impact)
+- Event types: session lifecycle, tool calls with file/command summaries, agent spawn/stop/idle, task completions
+
 ## [2.17.0] - 2026-02-16
 
 ### Added

package/bin/gsd-t.js

@@ -24,6 +24,7 @@ const { execSync } = require("child_process");
 
 const CLAUDE_DIR = path.join(os.homedir(), ".claude");
 const COMMANDS_DIR = path.join(CLAUDE_DIR, "commands");
+const SCRIPTS_DIR = path.join(CLAUDE_DIR, "scripts");
 const GLOBAL_CLAUDE_MD = path.join(CLAUDE_DIR, "CLAUDE.md");
 const SETTINGS_JSON = path.join(CLAUDE_DIR, "settings.json");
 const VERSION_FILE = path.join(CLAUDE_DIR, ".gsd-t-version");
@@ -33,6 +34,7 @@ const UPDATE_CHECK_FILE = path.join(CLAUDE_DIR, ".gsd-t-update-check");
 // Where our package files live (relative to this script)
 const PKG_ROOT = path.resolve(__dirname, "..");
 const PKG_COMMANDS = path.join(PKG_ROOT, "commands");
+const PKG_SCRIPTS = path.join(PKG_ROOT, "scripts");
 const PKG_TEMPLATES = path.join(PKG_ROOT, "templates");
 const PKG_EXAMPLES = path.join(PKG_ROOT, "examples");
 
@@ -144,6 +146,84 @@ function getInstalledCommands() {
   }
 }
 
+// ─── Heartbeat ──────────────────────────────────────────────────────────────
+
+const HEARTBEAT_SCRIPT = "gsd-t-heartbeat.js";
+const HEARTBEAT_HOOKS = [
+  "SessionStart", "PostToolUse", "SubagentStart", "SubagentStop",
+  "TaskCompleted", "TeammateIdle", "Notification", "Stop", "SessionEnd"
+];
+
+function installHeartbeat() {
+  ensureDir(SCRIPTS_DIR);
+
+  // Copy heartbeat script
+  const src = path.join(PKG_SCRIPTS, HEARTBEAT_SCRIPT);
+  const dest = path.join(SCRIPTS_DIR, HEARTBEAT_SCRIPT);
+
+  if (!fs.existsSync(src)) {
+    warn("Heartbeat script not found in package — skipping");
+    return;
+  }
+
+  const srcContent = fs.readFileSync(src, "utf8");
+  const destContent = fs.existsSync(dest) ? fs.readFileSync(dest, "utf8") : "";
+
+  if (srcContent !== destContent) {
+    copyFile(src, dest, HEARTBEAT_SCRIPT);
+  } else {
+    info("Heartbeat script unchanged");
+  }
+
+  // Configure hooks in settings.json
+  const hooksAdded = configureHeartbeatHooks(dest);
+  if (hooksAdded > 0) {
+    success(`${hooksAdded} heartbeat hooks configured in settings.json`);
+  } else {
+    info("Heartbeat hooks already configured");
+  }
+}
+
+function configureHeartbeatHooks(scriptPath) {
+  let settings = {};
+  if (fs.existsSync(SETTINGS_JSON)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(SETTINGS_JSON, "utf8"));
+    } catch {
+      warn("settings.json has invalid JSON — cannot configure hooks");
+      return 0;
+    }
+  }
+
+  if (!settings.hooks) settings.hooks = {};
+
+  const cmd = `node "${scriptPath.replace(/\\/g, "\\\\")}"`;
+  let added = 0;
+
+  for (const event of HEARTBEAT_HOOKS) {
+    if (!settings.hooks[event]) settings.hooks[event] = [];
+
+    // Check if heartbeat hook already exists for this event
+    const hasHeartbeat = settings.hooks[event].some((entry) =>
+      entry.hooks && entry.hooks.some((h) => h.command && h.command.includes(HEARTBEAT_SCRIPT))
+    );
+
+    if (!hasHeartbeat) {
+      settings.hooks[event].push({
+        matcher: "",
+        hooks: [{ type: "command", command: cmd, async: true }],
+      });
+      added++;
+    }
+  }
+
+  if (added > 0) {
+    fs.writeFileSync(SETTINGS_JSON, JSON.stringify(settings, null, 2));
+  }
+
+  return added;
+}
+
 // ─── Commands ────────────────────────────────────────────────────────────────
 
 function doInstall(opts = {}) {
@@ -226,10 +306,14 @@ function doInstall(opts = {}) {
     copyFile(globalSrc, GLOBAL_CLAUDE_MD, "CLAUDE.md installed → ~/.claude/CLAUDE.md");
   }
 
-  // 4. Save version
+  // 4. Install heartbeat script + hooks
+  heading("Heartbeat (Real-time Events)");
+  installHeartbeat();
+
+  // 5. Save version
   saveInstalledVersion();
 
-  // 5. Summary
+  // 6. Summary
   heading("Installation Complete!");
   log("");
   log(`  Commands: ${gsdtCommands.length} GSD-T + ${utilityCommands.length} utility commands in ~/.claude/commands/`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "2.17.0",
+  "version": "2.18.0",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 41 slash commands with backlog management, impact analysis, test sync, and milestone archival",
   "author": "Tekyz, Inc.",
   "license": "MIT",
@@ -23,6 +23,7 @@
   "files": [
     "bin/",
     "commands/",
+    "scripts/",
     "templates/",
     "examples/",
     "docs/",

package/scripts/gsd-t-heartbeat.js

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+
+/**
+ * GSD-T Heartbeat — Claude Code Hook Event Writer
+ *
+ * Writes structured events to .gsd-t/heartbeat-{session_id}.jsonl
+ * Installed as an async hook for multiple Claude Code events.
+ *
+ * Events captured:
+ *   SessionStart, PostToolUse, SubagentStart, SubagentStop,
+ *   TaskCompleted, TeammateIdle, Notification, Stop, SessionEnd
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+let input = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (d) => (input += d));
+process.stdin.on("end", () => {
+  try {
+    const hook = JSON.parse(input);
+    const dir = hook.cwd || process.cwd();
+    const gsdtDir = path.join(dir, ".gsd-t");
+
+    if (!fs.existsSync(gsdtDir)) return;
+
+    const sid = hook.session_id || "unknown";
+    const file = path.join(gsdtDir, `heartbeat-${sid}.jsonl`);
+
+    const event = buildEvent(hook);
+    if (event) {
+      fs.appendFileSync(file, JSON.stringify(event) + "\n");
+    }
+  } catch (e) {
+    // Silent failure — never interfere with Claude Code
+  }
+});
+
+function buildEvent(hook) {
+  const base = {
+    ts: new Date().toISOString(),
+    sid: hook.session_id,
+  };
+
+  switch (hook.hook_event_name) {
+    case "SessionStart":
+      return {
+        ...base,
+        evt: "session_start",
+        data: { source: hook.source, model: hook.model },
+      };
+
+    case "PostToolUse":
+      return {
+        ...base,
+        evt: "tool",
+        tool: hook.tool_name,
+        data: summarize(hook.tool_name, hook.tool_input),
+      };
+
+    case "SubagentStart":
+      return {
+        ...base,
+        evt: "agent_spawn",
+        data: { agent_id: hook.agent_id, agent_type: hook.agent_type },
+      };
+
+    case "SubagentStop":
+      return {
+        ...base,
+        evt: "agent_stop",
+        data: { agent_id: hook.agent_id, agent_type: hook.agent_type },
+      };
+
+    case "TaskCompleted":
+      return {
+        ...base,
+        evt: "task_done",
+        data: { task: hook.task_subject, agent: hook.teammate_name },
+      };
+
+    case "TeammateIdle":
+      return {
+        ...base,
+        evt: "agent_idle",
+        data: { agent: hook.teammate_name, team: hook.team_name },
+      };
+
+    case "Notification":
+      return {
+        ...base,
+        evt: "notification",
+        data: { message: hook.message, title: hook.title },
+      };
+
+    case "Stop":
+      return { ...base, evt: "session_stop" };
+
+    case "SessionEnd":
+      return {
+        ...base,
+        evt: "session_end",
+        data: { reason: hook.reason },
+      };
+
+    default:
+      return null;
+  }
+}
+
+function summarize(tool, input) {
+  if (!tool || !input) return {};
+  switch (tool) {
+    case "Read":
+      return { file: shortPath(input.file_path) };
+    case "Edit":
+      return { file: shortPath(input.file_path) };
+    case "Write":
+      return { file: shortPath(input.file_path) };
+    case "Bash":
+      return {
+        cmd: (input.command || "").slice(0, 150),
+        desc: input.description,
+      };
+    case "Grep":
+      return { pattern: input.pattern, path: shortPath(input.path) };
+    case "Glob":
+      return { pattern: input.pattern };
+    case "Task":
+      return { desc: input.description, type: input.subagent_type };
+    case "WebSearch":
+      return { query: input.query };
+    case "WebFetch":
+      return { url: input.url };
+    case "NotebookEdit":
+      return { file: shortPath(input.notebook_path) };
+    default:
+      return {};
+  }
+}
+
+function shortPath(p) {
+  if (!p) return null;
+  // Convert absolute paths to relative for readability
+  const cwd = process.cwd();
+  if (p.startsWith(cwd)) {
+    return p.slice(cwd.length + 1).replace(/\\/g, "/");
+  }
+  // For home-dir paths, abbreviate
+  const home = require("os").homedir();
+  if (p.startsWith(home)) {
+    return "~" + p.slice(home.length).replace(/\\/g, "/");
+  }
+  return p.replace(/\\/g, "/");
+}