ai-gains 1.4.0 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-gains",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Interactive browser dashboard for AI development session tracking",
   "main": "src/server.js",
   "bin": {

package/src/init.js

@@ -5,10 +5,25 @@ const path = require('path');
 
 const TEMPLATE_DIR = path.join(__dirname, '..', 'template');
 
+const STALE_HOOK_TYPES = ['SessionStart', 'Stop'];
+const AI_GAINS_LABEL = 'ai-gains';
+
 function mergeSettings(existing, template) {
   const result = JSON.parse(JSON.stringify(existing));
   if (!result.hooks) result.hooks = {};
 
+  // Remove stale ai-gains hooks that no longer exist in the template
+  for (const hookType of STALE_HOOK_TYPES) {
+    if (!result.hooks[hookType]) continue;
+    result.hooks[hookType] = result.hooks[hookType]
+      .map(entry => ({
+        ...entry,
+        hooks: (entry.hooks || []).filter(h => h.label !== AI_GAINS_LABEL)
+      }))
+      .filter(entry => (entry.hooks || []).length > 0);
+    if (result.hooks[hookType].length === 0) delete result.hooks[hookType];
+  }
+
   for (const [hookType, templateEntries] of Object.entries(template.hooks || {})) {
     if (!result.hooks[hookType]) {
       result.hooks[hookType] = templateEntries;
@@ -89,6 +104,16 @@ function initProject(targetDir) {
   fs.copyFileSync(skillSrc, skillDst);
   console.log(`  ${skillExisted ? 'updated' : 'created'} .claude/skills/ai-gains/SKILL.md`);
 
+  // Remove stale hook scripts that no longer exist in the template
+  const staleScripts = ['session-start.cjs', 'stop.cjs'];
+  for (const name of staleScripts) {
+    const stalePath = path.join(scriptsDst, name);
+    if (fs.existsSync(stalePath)) {
+      fs.rmSync(stalePath);
+      console.log(`  removed  .claude/scripts/ai-gains/${name}`);
+    }
+  }
+
   // Copy hook scripts (safe to overwrite)
   const scriptsExisted = fs.existsSync(scriptsDst);
   copyDir(scriptsSrc, scriptsDst);

package/template/.claude/scripts/ai-gains/get-session-times.cjs

@@ -0,0 +1,81 @@
+'use strict';
+const fs = require('fs');
+
+const transcriptPath = process.argv[2];
+if (!transcriptPath) {
+  console.error('Usage: get-session-times.cjs <transcript_path>');
+  process.exit(1);
+}
+
+const CHUNK_SIZE = 4096;
+const fd = fs.openSync(transcriptPath, 'r');
+const { size } = fs.fstatSync(fd);
+
+// Scan from the start for the first entry with a timestamp
+function findFirstTimestamp() {
+  const rl = require('readline').createInterface({
+    input: fs.createReadStream(transcriptPath),
+    crlfDelay: Infinity
+  });
+  return new Promise(resolve => {
+    rl.on('line', line => {
+      if (!line.trim()) return;
+      try {
+        const entry = JSON.parse(line);
+        if (entry.timestamp) {
+          rl.close();
+          resolve(entry.timestamp);
+        }
+      } catch {}
+    });
+    rl.on('close', () => resolve(null));
+  });
+}
+
+// Scan from the end for the last entry with a timestamp
+function findLastTimestamp() {
+  let offset = size;
+  let remainder = '';
+  let lastTimestamp = null;
+
+  while (offset > 0) {
+    const readSize = Math.min(CHUNK_SIZE, offset);
+    offset -= readSize;
+    const buf = Buffer.alloc(readSize);
+    fs.readSync(fd, buf, 0, readSize, offset);
+    const chunk = buf.toString('utf8') + remainder;
+    const lines = chunk.split('\n');
+    remainder = lines.shift(); // incomplete line at chunk boundary
+
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const line = lines[i].trim();
+      if (!line) continue;
+      try {
+        const entry = JSON.parse(line);
+        if (entry.timestamp) {
+          lastTimestamp = entry.timestamp;
+          break;
+        }
+      } catch {}
+    }
+    if (lastTimestamp) break;
+  }
+
+  fs.closeSync(fd);
+  return lastTimestamp;
+}
+
+(async () => {
+  const [start_time, end_time] = await Promise.all([
+    findFirstTimestamp(),
+    Promise.resolve(findLastTimestamp())
+  ]);
+
+  if (!start_time || !end_time) {
+    console.error('Could not extract timestamps from transcript');
+    process.exit(1);
+  }
+
+  const duration_minutes = Math.round((new Date(end_time) - new Date(start_time)) / 60000);
+  console.log(JSON.stringify({ start_time, end_time, duration_minutes }));
+})();

package/template/.claude/scripts/ai-gains/user-prompt-submit.cjs

@@ -4,8 +4,8 @@ let raw = '';
 process.stdin.setEncoding('utf8');
 process.stdin.on('data', chunk => { raw += chunk; });
 process.stdin.on('end', () => {
-  const { session_id } = JSON.parse(raw);
+  const { session_id, transcript_path } = JSON.parse(raw);
   process.stdout.write(
-    `Session ID: ${session_id}. IMPORTANT: In your final response, remind the user to update the ai-gains session log (the /ai-gains skill).`
+    `Session ID: ${session_id}. Transcript: ${transcript_path}. IMPORTANT: In your final response, remind the user to update the ai-gains session log (the /ai-gains skill).`
   );
 });

package/template/.claude/settings.json

@@ -1,16 +1,5 @@
 {
   "hooks": {
-    "SessionStart": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "label": "ai-gains",
-            "command": "node .claude/scripts/ai-gains/session-start.cjs"
-          }
-        ]
-      }
-    ],
     "UserPromptSubmit": [
       {
         "hooks": [
@@ -21,17 +10,6 @@
           }
         ]
       }
-    ],
-    "Stop": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "label": "ai-gains",
-            "command": "node .claude/scripts/ai-gains/stop.cjs"
-          }
-        ]
-      }
     ]
   }
 }

package/template/.claude/skills/ai-gains/SKILL.md

@@ -7,17 +7,11 @@ description: Manages the AI gains session log. Session initialization and user p
 
 ## Context
 
-Session tracking is managed automatically via hooks configured in `.claude/settings.json`:
+Session tracking is managed automatically via a hook configured in `.claude/settings.json`:
 
-- **SessionStart hook**: Reads Claude Code's `session_id` from stdin and creates `.ai-gains/<start_time>_<session_id>.json` with `start_time` and `author`. The timestamp uses `-` instead of `:` for cross-platform filename compatibility (e.g. `2026-03-02T09-00-00Z_<session_id>.json`).
-- **UserPromptSubmit hook**: Reads the `session_id` from stdin and echoes it into context with a lightweight reminder for Claude to prompt the user to update the log at the end of each response. The skill itself is not loaded automatically — only when the user invokes `/ai-gains`.
-- **Stop hook**: Reads the `session_id` from stdin, locates the matching `.ai-gains/*_<session_id>.json` file, and updates `end_time` after every Claude response.
+- **UserPromptSubmit hook**: Reads `session_id` and `transcript_path` from stdin and echoes both into context, along with a lightweight reminder for Claude to prompt the user to update the log at the end of each response. The skill itself is not loaded automatically — only when the user invokes `/ai-gains`.
 
-`duration_minutes` is the wall-clock time from `start_time` to `end_time`. This intentionally includes human review time, approval of actions, reading diffs, etc. — giving a true picture of total time spent with AI vs. without.
-
-Files are named `<start_time>_<session_id>.json` so they sort chronologically and concurrent sessions never conflict.
-
-Claude should note the Session ID echoed by each UserPromptSubmit hook and use it to locate the session file.
+`duration_minutes` is derived from the first and last timestamped entries in the session transcript. This reflects actual conversation activity from first message to last response, and intentionally includes human review time, approval of actions, reading diffs, etc. — giving a true picture of total time spent with AI vs. without.
 
 ## Proactive Log Reminders
 
@@ -31,19 +25,24 @@ Claude should use judgment about what counts as "meaningful" -- a single quick a
 
 When the user invokes `/ai-gains` or confirms they want to update the log:
 
-1. Get the current UTC time:
+1. Get `session_id` and `transcript_path` from the context echoed by the UserPromptSubmit hook.
+
+2. Run `get-session-times.cjs` with the transcript path to get accurate start/end times and duration:
    ```bash
-   node -e "console.log(new Date().toISOString().replace(/\.\d{3}Z$/, 'Z'))"
+   node .claude/scripts/ai-gains/get-session-times.cjs <transcript_path>
    ```
+   This outputs `{ start_time, end_time, duration_minutes }` derived from the first and last timestamped entries in the transcript.
 
-2. Use the Session ID echoed by the UserPromptSubmit hook (present in context) to locate the session file:
+3. Get the author from git config:
+   ```bash
+   git config user.email
+   ```
+
+4. Check if a session file already exists for this session:
    ```
    .ai-gains/*_<session_id>.json
    ```
-
-3. Read the session file to get `start_time` and `end_time`.
-
-4. Calculate `duration_minutes` as the difference between `end_time` and `start_time` in minutes (wall-clock time). This includes all time spent in the session — AI working, human reviewing, approving actions, reading output, etc.
+   If it exists, read the existing `achievements` array to use as a starting point for merging.
 
 5. Reflect on all work done this session: research done, features built, bugs fixed, problems solved, code reviewed, debugging done, documentation updated, etc.
 
@@ -60,14 +59,16 @@ When the user invokes `/ai-gains` or confirms they want to update the log:
    - `ui-ux` — designing or improving user interfaces and user experiences
    - `other` — anything that doesn't fit the above
 
-8. Write the updated JSON back to `.ai-gains/<start_utc_timestamp>_<uuid>.json`, preserving existing fields. The JSON structure should look like this:
+8. Merge new achievements with any existing ones from step 4. If a prior achievement is superseded or refined by new work in the same area, update it in place rather than duplicating it.
+
+9. Write the session file to `.ai-gains/<start_time_with_colons_replaced>_<session_id>.json`. The filename uses `-` instead of `:` in the timestamp for cross-platform compatibility. The JSON structure should look like this:
 
 ```json
 {
-  "uuid": "<session-uuid>",
+  "session_id": "<session-id>",
   "start_time": "<ISO start time>",
+  "end_time": "<ISO end time>",
   "author": "<git user email>",
-  "end_time": "<ISO current time>",
   "duration_minutes": "<number>",
   "achievements": [
     {
@@ -80,4 +81,4 @@ When the user invokes `/ai-gains` or confirms they want to update the log:
 }
 ```
 
-8. Confirm to the user that the log has been updated and summarize the key achievements.
+10. Confirm to the user that the log has been updated and summarize the key achievements.

package/template/.claude/scripts/ai-gains/session-start.cjs

@@ -1,24 +0,0 @@
-'use strict';
-const fs = require('fs');
-const { execSync } = require('child_process');
-
-let raw = '';
-process.stdin.setEncoding('utf8');
-process.stdin.on('data', chunk => { raw += chunk; });
-process.stdin.on('end', () => {
-  const { session_id } = JSON.parse(raw);
-  const start_time = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
-
-  let author = 'unknown';
-  try {
-    author = execSync('git config user.email', { stdio: ['pipe', 'pipe', 'pipe'] })
-      .toString().trim();
-  } catch {}
-
-  const safeTs = start_time.replace(/:/g, '-');
-  fs.mkdirSync('.ai-gains', { recursive: true });
-  fs.writeFileSync(
-    `.ai-gains/${safeTs}_${session_id}.json`,
-    JSON.stringify({ session_id, start_time, author }, null, 2) + '\n'
-  );
-});

package/template/.claude/scripts/ai-gains/stop.cjs

@@ -1,16 +0,0 @@
-'use strict';
-const fs = require('fs');
-
-let raw = '';
-process.stdin.setEncoding('utf8');
-process.stdin.on('data', chunk => { raw += chunk; });
-process.stdin.on('end', () => {
-  const { session_id } = JSON.parse(raw);
-  const match = fs.readdirSync('.ai-gains').find(f => f.endsWith(`_${session_id}.json`));
-  if (!match) return;
-  const file = `.ai-gains/${match}`;
-
-  const session = JSON.parse(fs.readFileSync(file, 'utf8'));
-  session.end_time = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
-  fs.writeFileSync(file, JSON.stringify(session, null, 2) + '\n');
-});