ai-lens 0.8.48 → 0.8.51

package/.commithash

@@ -1 +1 @@
-85bad35
+7c4d056

package/README.md

@@ -1,6 +1,6 @@
 # AI Lens
 
-Hook-based analytics for AI coding sessions. Captures events from Claude Code and Cursor, normalizes them to a unified format, queues locally, and ships to a centralized server with a web dashboard.
+Analytics for AI coding sessions. Captures hook events from Claude Code and Cursor, and near-real-time session events from Codex, normalizes them to a unified format, queues locally, and ships to a centralized server with a web dashboard.
 
 ```
 Hook fires → capture.js → normalize → queue.jsonl → sender.js → POST /api/events → server → dashboard
@@ -15,9 +15,10 @@ npx -y ai-lens init
 ```
 
 This will:
-1. Detect installed AI tools (Claude Code, Cursor)
+1. Detect installed AI tools (Claude Code, Cursor, Codex)
 2. Copy client files to `~/.ai-lens/client/`
 3. Configure hooks in `~/.claude/settings.json` and/or `~/.cursor/hooks.json`
+4. Start the Codex watcher for user-level and project-local Codex sessions
 
 Re-running is safe — it updates outdated hooks and skips current ones.
 
@@ -38,7 +39,7 @@ Configure the server URL and optionally filter projects:
 ```bash
 # In your shell profile (~/.zshrc, ~/.bashrc)
 export AI_LENS_SERVER_URL=http://your-server:13300
-export AI_LENS_PROJECTS="~/work/, ~/projects/"   # optional, default: all
+export AI_LENS_PROJECTS="~/work/, ~/projects/"   # optional, default: all; nested repos under these roots are included
 ```
 
 <details>
@@ -76,6 +77,14 @@ export AI_LENS_PROJECTS="~/work/, ~/projects/"   # optional, default: all
 }
 ```
 
+**Codex** — no hook file. Run `ai-lens init` to start the local watcher, or start it manually:
+
+```bash
+node ~/.ai-lens/client/codex-watcher.js
+```
+
+The watcher tails the user-level Codex directory (`~/.codex`) and any project-local `.codex` directories found under `AI_LENS_PROJECTS`. It respects `AI_LENS_PROJECTS` the same way as Claude Code and Cursor: only sessions whose `cwd` is inside a configured monitored root are sent.
+
 </details>
 
 ## Server Setup
@@ -103,11 +112,12 @@ Default credentials:
 ### Local development
 
 ```bash
+docker compose up postgres -d
 npm install --prefix server   # Install server deps (auto-runs via prestart)
-npm start                     # Express on port 3000, SQLite at ~/.ai-lens-server/data.db
+DATABASE_URL=postgresql://ailens:ailens@localhost:5432/ailens npm start
 ```
 
-SQLite is used when `DATABASE_URL` is not set. PostgreSQL is used in Docker via `DATABASE_URL=postgresql://...`.
+The server now requires PostgreSQL via `DATABASE_URL`. The old SQLite fallback is no longer supported.
 
 ## Dashboard
 
@@ -181,7 +191,7 @@ Aggregate endpoints for dashboard charts (stats, trends, tool usage, etc.).
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `PORT` | `3000` (local), `13300` (Docker) | Server port |
-| `DATABASE_URL` | _(unset = SQLite)_ | PostgreSQL connection string |
+| `DATABASE_URL` | _(required)_ | PostgreSQL connection string |
 | `AI_LENS_SERVER_URL` | `http://localhost:3000` | Client → server endpoint |
 | `AI_LENS_AUTH_TOKEN` | `collector:secret-collector-token-2026-ai-lens` | Client auth (`user:password`) |
 | `AI_LENS_PROJECTS` | _(all)_ | Comma-separated project paths to monitor (`~` supported) |

package/cli/hooks.js

@@ -145,7 +145,7 @@ export function cursorCaptureCommand(useTilde = false, customPath = null) {
 // Client file installation
 // ---------------------------------------------------------------------------
 
-const CLIENT_FILES = ['capture.js', 'sender.js', 'config.js', 'redact.js'];
+const CLIENT_FILES = ['capture.js', 'sender.js', 'config.js', 'redact.js', 'codex.js', 'codex-watcher.js'];
 
 /**
  * Copy client/ files from the package source to ~/.ai-lens/client/.

package/cli/init.js

@@ -1,7 +1,7 @@
 import { createInterface } from 'node:readline';
 import { execSync, spawn } from 'node:child_process';
 import { existsSync, copyFileSync, readdirSync } from 'node:fs';
-import { join, resolve, relative } from 'node:path';
+import { join, resolve, relative, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { request as httpRequest } from 'node:http';
 import { request as httpsRequest } from 'node:https';
@@ -146,6 +146,19 @@ function sleep(ms) {
   return new Promise(resolve => setTimeout(resolve, ms));
 }
 
+function startCodexWatcher(watcherPath) {
+  if (!existsSync(watcherPath)) return false;
+  if (process.env.AI_LENS_TEST_NO_DETACHED_SPAWN === '1') return true;
+  const child = spawn(process.execPath, [watcherPath], {
+    detached: true,
+    stdio: 'ignore',
+    windowsHide: true,
+  });
+  child.on('error', () => {});
+  child.unref();
+  return true;
+}
+
 async function deviceCodeAuth(serverUrl) {
   // 1. Fetch Auth0 config from server
   let config;
@@ -386,14 +399,12 @@ export default async function init() {
   }
 
   if (tools.length === 0) {
-    warn('No supported AI tools detected.');
-    info('Looked for ~/.claude/ and ~/.cursor/ directories.');
-    info('Install Claude Code or Cursor, then re-run: npx -y ai-lens init');
-    return;
-  }
-
-  for (const tool of tools) {
-    success(`  Found: ${tool.name} (${tool.dirPath})`);
+    warn('No Claude Code or Cursor installation detected.');
+    info('Continuing with AI Lens client install, config, and Codex watcher setup.');
+  } else {
+    for (const tool of tools) {
+      success(`  Found: ${tool.name} (${tool.dirPath})`);
+    }
   }
 
   // Configuration
@@ -419,19 +430,20 @@ export default async function init() {
 
   // Project filter
   const currentProjects = currentConfig.projects || null;
+  const projectHooksDefault = flags.projectHooks ? resolve(process.cwd()) : null;
   let projects;
   if (flags.projects) {
     projects = flags.projects;
   } else if (auto) {
-    projects = currentProjects;
+    projects = currentProjects || projectHooksDefault;
   } else {
-    const projectsDefault = currentProjects || 'all';
+    const projectsDefault = currentProjects || projectHooksDefault || 'all';
     const projectsInput = await ask(
       `Projects to track (comma-separated, ~ supported, Enter = ${projectsDefault}): `,
     );
     projects = (projectsInput && projectsInput.trim() && projectsInput.trim().toLowerCase() !== 'all')
       ? projectsInput
-      : null;
+      : (projectHooksDefault || null);
   }
   // Guard: non-string (e.g. array from corrupt config) → treat as unset
   if (projects && typeof projects !== 'string') {
@@ -530,8 +542,12 @@ export default async function init() {
     }
   }
 
-  if (flags.noHooks) {
-    info('--no-hooks: skipping hook configuration and MCP setup');
+  if (flags.noHooks || tools.length === 0) {
+    if (tools.length === 0 && !flags.noHooks) {
+      info('No Claude Code or Cursor hooks to configure in this environment.');
+    } else if (flags.noHooks) {
+      info('--no-hooks: skipping hook configuration and MCP setup');
+    }
     saveLensConfig(newConfig);
   } else {
     // Analyze each tool
@@ -727,6 +743,33 @@ export default async function init() {
     warn(`  Migration skipped: ${err.message}`);
   }
 
+  heading('Codex');
+  let enableCodex = currentConfig.codexEnabled === true;
+  if (auto) {
+    enableCodex = true;
+  } else {
+    const defaultLabel = enableCodex ? 'Y/n' : 'y/N';
+    const answer = await ask(`  Enable Codex session tracking? [${defaultLabel}] `);
+    if (answer) {
+      enableCodex = ['y', 'yes'].includes(answer.toLowerCase());
+    }
+  }
+  newConfig.codexEnabled = enableCodex;
+  saveLensConfig(newConfig);
+
+  if (enableCodex) {
+    const watcherPath = flags.useRepoPath
+      ? join(dirname(REPO_CAPTURE_PATH), 'codex-watcher.js')
+      : join(dirname(CAPTURE_PATH), 'codex-watcher.js');
+    if (startCodexWatcher(watcherPath)) {
+      success('  Codex watcher started');
+    } else {
+      warn(`  Codex watcher not started: missing ${watcherPath}`);
+    }
+  } else {
+    info('  Codex tracking disabled');
+  }
+
   // Flush any pending events with the new config (e.g. backlog from previous 401/network errors)
   const senderPath = join(homedir(), '.ai-lens', 'client', 'sender.js');
   if (existsSync(senderPath)) {

package/cli/remove.js

@@ -12,6 +12,7 @@ import {
   buildStrippedConfig, writeHooksConfig, removeClientFiles, getVersionInfo,
   cleanupLegacyHooks, cleanupEmptyMcpJson, removeCursorMcp,
 } from './hooks.js';
+import { stopCodexWatcher } from '../client/codex-watcher.js';
 
 function ask(question) {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -121,6 +122,23 @@ export default async function remove() {
   }
   blank();
 
+  // Stop Codex watcher before deleting ~/.ai-lens files so the process does not
+  // keep running against removed paths or leave a stale lock behind.
+  heading('Stopping Codex watcher...');
+  try {
+    const watcherResult = await stopCodexWatcher();
+    if (watcherResult.previousState === 'active') {
+      success(`  Codex watcher stopped (pid ${watcherResult.pid}${watcherResult.forced ? ', forced' : ''})`);
+    } else if (watcherResult.previousState === 'missing') {
+      info('  Codex watcher not running');
+    } else {
+      success(`  Codex watcher lock cleaned up (${watcherResult.previousState})`);
+    }
+  } catch (err) {
+    error(`  Failed to stop Codex watcher: ${err.message}`);
+  }
+  blank();
+
   // Remove MCP servers
   heading('Removing MCP servers...');
 

package/cli/status.js

@@ -5,8 +5,9 @@ import { homedir, release as osRelease, arch as osArch } from 'node:os';
 import { randomUUID } from 'node:crypto';
 
 import { getVersionInfo, readLensConfig, detectInstalledTools, getCursorToolConfig, getClaudeCodeToolConfig, analyzeToolHooks, checkHooksDisabled, CAPTURE_PATH, TOOL_CONFIGS } from './hooks.js';
-import { DATA_DIR, PENDING_DIR, SENDING_DIR, SESSION_PATHS_DIR, LOG_PATH, CAPTURE_LOG_PATH, getGitIdentity } from '../client/config.js';
+import { DATA_DIR, PENDING_DIR, SENDING_DIR, SESSION_PATHS_DIR, LOG_PATH, CAPTURE_LOG_PATH, getGitIdentity, getMonitoredProjects } from '../client/config.js';
 import { isLockStale } from '../client/sender.js';
+import { readCodexWatcherLock, resolveWatchedCodexDirs } from '../client/codex-watcher.js';
 import { initLogger, info, success, warn, error, heading, blank } from './logger.js';
 
 const INIT_LOG_PATH = join(DATA_DIR, 'init.log');
@@ -223,14 +224,15 @@ function checkCaptureRun(installedTools) {
     });
     let shellOk = false;
     let shellDetail = '';
+    // Declared outside try: GUI PATH test below uses isCursor + shellCommand (must stay in scope).
+    const isWin = process.platform === 'win32';
+    const isCursor = name === 'Cursor' || name.startsWith('Cursor (');
+    const usePS = isWin && isCursor;
+    let shellCommand = !isWin && command.startsWith('& ') ? command.slice(2).trim() : command;
     try {
       // On Windows, Cursor runs hooks via PowerShell (needs `& "..."` call-operator),
       // but Claude Code runs hooks via bash/cmd (no `&` prefix).
       // On non-Windows, strip leading "& " if present (e.g. config copied from Windows) so bash doesn't background the process.
-      const isWin = process.platform === 'win32';
-      const isCursor = name === 'Cursor' || name.startsWith('Cursor (');
-      const usePS = isWin && isCursor;
-      let shellCommand = !isWin && command.startsWith('& ') ? command.slice(2).trim() : command;
       // Expand ~ in the command: bash/zsh won't expand ~ inside single quotes,
       // so replace '~/...' and bare ~/... with the absolute home path.
       if (!isWin) {
@@ -545,6 +547,51 @@ function checkQueue() {
   return { ok, summary, detail, lineCount: pendingCount, lockStatus };
 }
 
+function pluralize(count, singular, plural = singular + 's') {
+  return `${count} ${count === 1 ? singular : plural}`;
+}
+
+export function checkCodexWatcher({
+  dataDir = DATA_DIR,
+  monitoredRoots = getMonitoredProjects(),
+  homeDir = homedir(),
+  userCodexDirs,
+} = {}) {
+  const watchedDirs = resolveWatchedCodexDirs(monitoredRoots, userCodexDirs, homeDir);
+  const lock = readCodexWatcherLock(join(dataDir, 'codex-watcher.lock'));
+  const watchedSummary = pluralize(watchedDirs.length, 'watched dir');
+
+  if (lock.state === 'active') {
+    return {
+      ok: true,
+      summary: `active (pid ${lock.pid}, ${watchedSummary})`,
+      detail: `Lock: ${lock.lockPath}\nPID: ${lock.pid}\nWatched dirs:\n${watchedDirs.map(dir => `- ${dir}`).join('\n') || '(none discovered yet)'}`,
+    };
+  }
+
+  if (lock.state === 'stale') {
+    return {
+      ok: false,
+      summary: `stale lock (pid ${lock.pid}, ${watchedSummary})`,
+      detail: `Lock: ${lock.lockPath}\nStale PID: ${lock.pid}\nWatched dirs:\n${watchedDirs.map(dir => `- ${dir}`).join('\n') || '(none discovered yet)'}`,
+    };
+  }
+
+  if (lock.state === 'invalid' || lock.state === 'error') {
+    return {
+      ok: false,
+      summary: `lock ${lock.state} (${watchedSummary})`,
+      detail: `Lock: ${lock.lockPath}\nError: ${lock.error || '(none)'}\nWatched dirs:\n${watchedDirs.map(dir => `- ${dir}`).join('\n') || '(none discovered yet)'}`,
+    };
+  }
+
+  return {
+    ok: watchedDirs.length > 0 ? false : null,
+    summary: `not running (${watchedSummary})`,
+    detail: `Lock: ${lock.lockPath}\nWatched dirs:\n${watchedDirs.map(dir => `- ${dir}`).join('\n') || '(none discovered yet)'}`,
+  };
+}
+
 function checkSenderLog() {
   if (!existsSync(LOG_PATH)) {
     return { ok: null, summary: 'no log file', detail: 'Sender log does not exist (sender has not run yet)' };
@@ -1062,6 +1109,9 @@ export default async function status() {
   const configResult = checkConfig();
   printLine('Config', configResult);
 
+  // 5b. Codex watcher
+  printLine('Codex watcher', checkCodexWatcher());
+
   // 6. Hooks: global + project (Cursor then Claude Code; within each: global then project)
   const installedTools = detectInstalledTools();
   const toolsWithProject = getToolsForCaptureTest();

package/client/capture.js

@@ -13,19 +13,24 @@ import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { createHash } from 'node:crypto';
 import {
+  DATA_DIR,
   ensureDataDir,
   PENDING_DIR,
+  SENDING_DIR,
   DEDUP_DIR,
   SESSION_PATHS_DIR,
   CAPTURE_LOG_PATH,
   LOG_MAX_AGE_DAYS,
+  SENDER_BACKOFF_PATH,
   captureLog,
   getServerUrl,
   getAuthToken,
   getGitIdentity,
   getGitMetadata,
   getMonitoredProjects,
+  isCodexEnabled,
 } from './config.js';
+import { isLockStale, isSenderBackoffActive } from './sender.js';
 // Soft import — redact.js may not exist on older client installs
 let redactObject = (o) => o;
 try {
@@ -619,7 +624,7 @@ export function normalizeEvent(event) {
 // Queue + Sender Spawn
 // =============================================================================
 
-function writeToSpool(unified) {
+export function writeToSpool(unified) {
   // Shallow copy before redaction — do not mutate the caller's object
   const toWrite = { ...unified };
   // Redact secrets from individual string values (not serialized JSON)
@@ -645,7 +650,14 @@ function writeToSpool(unified) {
 
 // Always try to spawn sender — renameSync in sender acts as the real mutex.
 // If sender is already running, the new one exits immediately (ENOENT on rename).
-function trySpawnSender() {
+export function shouldSpawnSender(lockPath = join(SENDING_DIR, '.sender.lock'), backoffPath = SENDER_BACKOFF_PATH, nowMs = Date.now()) {
+  if (isSenderBackoffActive(backoffPath, nowMs)) return false;
+  if (existsSync(lockPath) && !isLockStale(lockPath)) return false;
+  return true;
+}
+
+export function trySpawnSender() {
+  if (!shouldSpawnSender()) return;
   const senderPath = join(__dirname, 'sender.js');
   const child = spawn(process.execPath, [senderPath], {
     detached: true,
@@ -656,6 +668,35 @@ function trySpawnSender() {
   child.unref();
 }
 
+function hasLivePidLock(lockPath) {
+  try {
+    const pid = Number.parseInt(readFileSync(lockPath, 'utf-8').trim().split(/\r?\n/)[0], 10);
+    if (!pid) return false;
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err?.code === 'EPERM';
+  }
+}
+
+export function shouldSpawnCodexWatcher(lockPath = join(DATA_DIR, 'codex-watcher.lock')) {
+  return !hasLivePidLock(lockPath);
+}
+
+function trySpawnCodexWatcher() {
+  if (!isCodexEnabled()) return;
+  if (!shouldSpawnCodexWatcher()) return;
+  const watcherPath = join(__dirname, 'codex-watcher.js');
+  if (!existsSync(watcherPath)) return;
+  const child = spawn(process.execPath, [watcherPath], {
+    detached: true,
+    stdio: 'ignore',
+    windowsHide: true,
+  });
+  child.on('error', () => {});
+  child.unref();
+}
+
 // =============================================================================
 // Main
 // =============================================================================
@@ -770,6 +811,12 @@ async function main() {
     captureLog({ msg: 'sender-spawn-failed', error: err.message });
     // event is queued — sender will be spawned on next capture
   }
+
+  try {
+    trySpawnCodexWatcher();
+  } catch (err) {
+    captureLog({ msg: 'codex-watcher-spawn-failed', error: err.message });
+  }
 }
 
 // Only run main when executed directly (not when imported for testing).