ai-lens 0.8.49 → 0.8.52

package/.commithash

@@ -1 +1 @@
-b5da117
+8553371

package/README.md

@@ -1,6 +1,8 @@
 # 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, Cursor,
+and Codex, normalizes them to a unified format, queues locally, and ships to a
+centralized server with a web dashboard and MCP integration.
 
 ```
 Hook fires → capture.js → normalize → queue.jsonl → sender.js → POST /api/events → server → dashboard
@@ -15,9 +17,11 @@ 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
+5. Register the MCP server for in-editor analytics (optional)
 
 Re-running is safe — it updates outdated hooks and skips current ones.
 
@@ -26,19 +30,38 @@ Re-running is safe — it updates outdated hooks and skips current ones.
 To write hooks into the project directory (`.cursor/hooks.json` and `.claude/settings.json`) instead of global `~/.cursor/` and `~/.claude/`, run from the project root:
 
 ```bash
-npx git+ssh://git@rantsports.gitlab.yandexcloud.net:ai-first-workspace/internal/analytics/ai-lens.git init --server https://ai-lens.rantsports.com --no-mcp --project-hooks
+npx -y ai-lens init --server https://ai-lens.rantsports.com --no-mcp --project-hooks
 ```
 
 Add `--use-repo-path` to run `capture.js` directly from the package (repo or npx cache) instead of copying to `~/.ai-lens/client/`. Useful when the repo is next to the workspace.
 
-Hooks use the path `~/.ai-lens/client/capture.js` by default (or the package path with `--use-repo-path`); the config can be committed to the repo.
+### CLI commands
 
-Configure the server URL and optionally filter projects:
+```bash
+npx ai-lens init       # Setup wizard — detect tools, install hooks, configure MCP
+npx ai-lens status     # Run health checks and generate a diagnostic report
+npx ai-lens remove     # Remove hooks, client files, and MCP config
+npx ai-lens version    # Show installed version
+```
+
+### CLI options
+
+| Flag | Description |
+|------|-------------|
+| `--server URL` | Server URL (default: `http://localhost:3000`) |
+| `--yes`, `-y` | Non-interactive mode, accept all defaults |
+| `--no-mcp` | Skip MCP server registration |
+| `--mcp-scope SCOPE` | MCP scope: `user` (default), `local`, or `project` |
+| `--projects LIST` | Comma-separated project paths to monitor (default: all) |
+| `--project-hooks` | Write hooks into project directory instead of global config |
+| `--use-repo-path` | Run capture.js from package path instead of copying to `~/.ai-lens/client/` |
+
+### Environment variables (client)
 
 ```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_SERVER_URL=https://ai-lens.rantsports.com
+export AI_LENS_PROJECTS="~/meta/, ~/meta-cursor/"   # optional, default: all
 ```
 
 <details>
@@ -76,6 +99,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
@@ -87,46 +118,94 @@ docker compose up -d
 ```
 
 Starts three containers:
-- **nginx** — reverse proxy with basic auth, port `13300`
-- **app** — Node.js Express server with dashboard
-- **postgres** — PostgreSQL 16 database
 
-Dashboard: `http://your-server:13300`
+| Container | Image | Purpose |
+|-----------|-------|---------|
+| **app** | `ai-lens/app` | API server + web dashboard (port 3000) |
+| **postgres** | `postgres:16-alpine` | PostgreSQL 16 database |
+| **analyzer** | `ai-lens/analyzer` | Background session analyzer (needs `claude login`) |
+
+Dashboard: https://ai-lens.rantsports.com
 
-Default credentials:
+Images are stored in ECR (`267996409571.dkr.ecr.eu-north-1.amazonaws.com/ai-lens/`) and mirrored to GHCR (`ghcr.io/r-ms/ai-lens/`) on every push to `main`.
 
-| User | Password | Purpose |
-|------|----------|---------|
-| `collector` | `secret-collector-token-2026-ai-lens` | Client sender (automatic via `AI_LENS_AUTH_TOKEN`) |
-| `meta` | `meta` | Browser / dashboard access |
+### Environment variables (server)
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | `3000` | Server port |
+| `DATABASE_URL` | _(required)_ | PostgreSQL connection string |
+| `POSTGRES_PASSWORD` | `ailens` | PostgreSQL password (docker compose) |
+| `ANALYSIS_INTERVAL` | `3600` | Seconds between analysis runs |
+| `AI_LENS_ADMIN_SECRET` | _(none)_ | Admin secret for auth token management |
+| `OPENAI_API_KEY` | _(none)_ | OpenAI API key for FAISS vector search; text search works without it |
+| `TEAMS_CONFIG` | _(none)_ | JSON config for team definitions |
+| `CORS_ALLOWED_ORIGINS` | _(none)_ | Allowed CORS origins |
+
+#### Auth0 SSO
+
+| Variable | Description |
+|----------|-------------|
+| `AUTH0_DOMAIN` | Auth0 tenant domain |
+| `AUTH0_CLIENT_ID` | Auth0 SPA client ID |
+| `AUTH0_AUDIENCE` | Auth0 API audience identifier |
+| `AUTH0_ALLOWED_DOMAIN` | Restrict login to a specific email domain |
+| `AUTH0_CLI_CLIENT_ID` | Auth0 Native app client ID for device code flow |
+| `MCP_SERVER_URL` | Public server URL for MCP OAuth callbacks |
+
+Without Auth0, the server uses git email headers for identity (personal mode).
 
 ### Local development
 
 ```bash
-npm install --prefix server   # Install server deps (auto-runs via prestart)
-npm start                     # Express on port 3000, SQLite at ~/.ai-lens-server/data.db
+docker compose up postgres -d
+npm install
+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://...`.
-
 ## Dashboard
 
-React + TypeScript SPA with session timelines, tool breakdowns, adoption trends, and per-developer analytics.
+React + TypeScript SPA with:
+- Organization-wide KPIs and adoption trends
+- Team and developer breakdowns
+- Session timelines with tool usage
+- AI-generated session and team analyses
+- Token usage by model
+- MCP server and skill distribution
+- Knowledge base and recurring problems
 
 ```bash
 cd dashboard
 npm install
 npm run dev          # Vite dev server with HMR (proxies API to localhost:3000)
-```
-
-Production build (served by Express as static files):
-
-```bash
-npm run build:dashboard
+npm run build        # Production build (served by Express as static files)
 ```
 
 Tech: Vite, Tailwind CSS, Nivo charts, TanStack Query, react-router-dom.
 
+## MCP Tools
+
+When MCP is enabled during `npx ai-lens init`, these tools become available inside Claude Code and Cursor:
+
+| Tool | Description |
+|------|-------------|
+| `who_am_i` | Identify yourself by git email — returns your developer profile and team(s) |
+| `get_overview` | Organization-wide KPIs: active developers, adoption rate, AI hours, MCP and skill distribution |
+| `list_teams` | List all teams with member counts, adoption rate, and AI hours |
+| `get_team` | Team detail: KPIs, members, tasks, activity trend, MCP and skill distribution |
+| `get_team_analysis` | AI-generated team analysis: achievements, recurring problems, recommendations |
+| `get_developer` | Developer profile: sessions, AI hours, tasks, MCP and skill usage, team comparison |
+| `get_mcp_distribution` | MCP server usage across the organization |
+| `get_chain` | Session chain with compact event timeline, plan mode segments, and timing |
+| `get_events` | Full event data for specific event IDs |
+| `get_chain_analysis` | AI-generated chain analysis: tasks, problems, tool errors, unanswered questions |
+| `request_analysis` | Manually trigger analysis for a specific session chain |
+| `get_token_usage` | Token usage statistics grouped by model (input/output/cache tokens) |
+| `knowhow_search` | Search the team knowledge base built from session analyses |
+| `knowhow_update` | Add or update a knowledge base entry |
+| `export_developer_tips` | Export personalized tips as a Markdown document |
+| `search` | Natural language search across sessions, tasks, and projects |
+
 ## API
 
 ### `POST /api/events`
@@ -134,7 +213,7 @@ Tech: Vite, Tailwind CSS, Nivo charts, TanStack Query, react-router-dom.
 Batch insert events. Deduplicates by `event_id` (ON CONFLICT DO NOTHING) — safe to re-send.
 
 ```
-Headers: X-Developer-Git-Email, X-Developer-Name, Authorization: Basic <base64>
+Headers: X-Developer-Git-Email, X-Developer-Name, X-Auth-Token
 Body: [{ source, session_id, type, project_path, timestamp, data, raw, event_id }]
 Response: { received, skipped, deduplicated }
 ```
@@ -153,38 +232,36 @@ List all developers.
 
 ### `GET /api/dashboard/*`
 
-Aggregate endpoints for dashboard charts (stats, trends, tool usage, etc.).
+Aggregate endpoints for dashboard charts: overview, teams, developers, tokens, MCP distribution, developer activity, knowledge base, problems, company/team/developer analyses.
 
 ## Event Types
 
 | Type | Source | Description |
 |------|--------|-------------|
-| `SessionStart` | Both | Session opened |
-| `SessionEnd` | Both | Session closed |
-| `UserPromptSubmit` | Both | User sent a prompt |
-| `PostToolUse` | Both | Tool execution completed |
-| `PostToolUseFailure` | Both | Tool execution failed |
-| `Stop` | Both | Agent stopped |
-| `PreCompact` | Both | Context compaction triggered |
+| `SessionStart` | All | Session opened |
+| `SessionEnd` | All | Session closed |
+| `UserPromptSubmit` | All | User sent a prompt |
+| `PostToolUse` | All | Tool execution completed |
+| `PostToolUseFailure` | All | Tool execution failed |
+| `Stop` | All | Agent stopped |
+| `PreCompact` | All | Context compaction triggered |
 | `PlanModeStart` | Claude Code | Entered plan mode |
 | `PlanModeEnd` | Claude Code | Exited plan mode (plan content in raw payload) |
-| `SubagentStart` | Both | Subagent spawned |
-| `SubagentStop` | Both | Subagent finished |
+| `SubagentStart` | All | Subagent spawned |
+| `SubagentStop` | All | Subagent finished |
 | `FileEdit` | Cursor | File edited |
 | `ShellExecution` | Cursor | Shell command executed |
 | `MCPExecution` | Cursor | MCP tool executed |
-| `AgentResponse` | Cursor | Agent response |
+| `AgentResponse` | Cursor | Agent response (includes token usage in raw payload) |
 | `AgentThought` | Cursor | Agent reasoning |
 
-## Environment Variables
+## Supported Tools
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `PORT` | `3000` (local), `13300` (Docker) | Server port |
-| `DATABASE_URL` | _(unset = SQLite)_ | 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) |
+| Tool | Hook mechanism |
+|------|---------------|
+| **Claude Code** | Hooks via `~/.claude/settings.json` |
+| **Cursor** | Hooks via `~/.cursor/hooks.json` |
+| **Codex** | File watcher on `~/.codex` and project-local `.codex` directories |
 
 ## Client Data
 
@@ -193,41 +270,35 @@ Stored in `~/.ai-lens/`:
 | File | Purpose |
 |------|---------|
 | `client/` | Installed client files (capture.js, sender.js, config.js) |
+| `config.json` | Server URL, auth token, project list |
 | `queue.jsonl` | Pending events |
 | `queue.sending.jsonl` | Events being sent (atomic rename as mutex) |
 | `sender.log` | Sender activity log |
+| `capture.log` | Capture drop log (normalization failures, write errors) |
 | `session-paths.json` | Session-to-project path cache |
 
 ## Development
 
 ```bash
-npm test               # Run all tests (vitest, 204 tests)
+npm test               # Run all tests (vitest, 683 tests)
 npm run test:watch     # Watch mode
 npm run dev:dashboard  # Dashboard dev server
 ```
 
-Tests use in-memory SQLite via `initTestDb()`.
+Tests require PostgreSQL — set `DATABASE_URL` or use `docker compose up postgres -d` (test DB `ailens_test` is created automatically).
 
 ## Deployment
 
 GitLab CI (`.gitlab-ci.yml`) on push to `main`:
 
-1. `rsync` to deploy host
-2. `docker compose down && docker compose up -d --build`
-3. Health check
-
-## Data Migration
-
-Sync local SQLite data to a remote PostgreSQL server:
-
-```bash
-node scripts/sync-to-remote.js                       # Default remote
-node scripts/sync-to-remote.js http://custom:13300   # Custom URL
-```
+1. **build-app** — builds `ai-lens/app` Docker image, pushes to ECR + GHCR
+2. **build-analyzer** — builds `ai-lens/analyzer` Docker image, pushes to ECR + GHCR
+3. **deploy** — zero-downtime rolling deploy to production (scale up new container, health check, remove old)
 
-Safe to re-run — deduplicates by `event_id`.
+Build jobs trigger only when relevant files change (Dockerfile, server/**, dashboard/**, etc.).
 
 ## Requirements
 
 - Node.js 20+
 - Docker + Docker Compose (for production deployment)
+- PostgreSQL 16 (for local development without Docker)

package/cli/hooks.js

@@ -1,4 +1,4 @@
-import { existsSync, lstatSync, readFileSync, writeFileSync, copyFileSync, renameSync, mkdirSync, rmSync, unlinkSync, chmodSync } from 'node:fs';
+import { existsSync, lstatSync, readFileSync, writeFileSync, copyFileSync, renameSync, mkdirSync, rmSync, unlinkSync, chmodSync, readdirSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
@@ -145,7 +145,16 @@ export function cursorCaptureCommand(useTilde = false, customPath = null) {
 // Client file installation
 // ---------------------------------------------------------------------------
 
-const CLIENT_FILES = ['capture.js', 'sender.js', 'config.js', 'redact.js'];
+/**
+ * Enumerate every .js file that ships with the package's client/ directory.
+ * Dynamic discovery (rather than a hardcoded CLIENT_FILES list) guarantees
+ * that any new client/*.js file added to the repo is automatically installed,
+ * so a forgotten list entry can never produce a broken install that crashes
+ * every hook with ERR_MODULE_NOT_FOUND on a missing sibling import.
+ */
+export function listClientFiles(sourceDir = join(__dirname, '..', 'client')) {
+  return readdirSync(sourceDir).filter(f => f.endsWith('.js')).sort();
+}
 
 /**
  * Copy client/ files from the package source to ~/.ai-lens/client/.
@@ -155,7 +164,7 @@ export function installClientFiles() {
   const sourceDir = join(__dirname, '..', 'client');
   mkdirSync(CLIENT_INSTALL_DIR, { recursive: true });
 
-  for (const file of CLIENT_FILES) {
+  for (const file of listClientFiles(sourceDir)) {
     copyFileSync(join(sourceDir, file), join(CLIENT_INSTALL_DIR, file));
   }
 

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';
@@ -67,7 +67,7 @@ function getJson(url) {
   });
 }
 
-function postJson(url, body) {
+function postJson(url, body, timeoutMs = 15_000) {
   return new Promise((resolve, reject) => {
     const parsed = new URL(url);
     const isHttps = parsed.protocol === 'https:';
@@ -82,7 +82,7 @@ function postJson(url, body) {
         'Content-Type': 'application/json',
         'Content-Length': Buffer.byteLength(data),
       },
-      timeout: 15_000,
+      timeout: timeoutMs,
     };
     const req = requestFn(options, (res) => {
       let buf = '';
@@ -107,7 +107,7 @@ function postJson(url, body) {
   });
 }
 
-function postForm(url, params) {
+function postForm(url, params, timeoutMs = 15_000) {
   return new Promise((resolve, reject) => {
     const parsed = new URL(url);
     const isHttps = parsed.protocol === 'https:';
@@ -122,7 +122,7 @@ function postForm(url, params) {
         'Content-Type': 'application/x-www-form-urlencoded',
         'Content-Length': Buffer.byteLength(data),
       },
-      timeout: 15_000,
+      timeout: timeoutMs,
     };
     const req = requestFn(options, (res) => {
       let buf = '';
@@ -146,6 +146,39 @@ function sleep(ms) {
   return new Promise(resolve => setTimeout(resolve, ms));
 }
 
+function isTransientNetError(err) {
+  const msg = `${err && err.code ? err.code : ''} ${err && err.message ? err.message : err}`;
+  return /ECONNRESET|EPIPE|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|ECONNREFUSED|socket hang up/i.test(String(msg));
+}
+
+/** Retry fn on flaky TLS/proxy resets (common during long Auth0 device polls). */
+async function withRetries(fn, { attempts = 5, baseDelayMs = 2000 } = {}) {
+  let lastErr;
+  for (let i = 1; i <= attempts; i++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastErr = err;
+      if (!isTransientNetError(err) || i === attempts) throw err;
+      await sleep(baseDelayMs * i);
+    }
+  }
+  throw lastErr;
+}
+
+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;
@@ -206,17 +239,24 @@ async function deviceCodeAuth(serverUrl) {
   while (Date.now() < deadline) {
     await sleep(interval * 1000);
 
-    const tokenResp = await postForm(`https://${domain}/oauth/token`, {
-      grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
-      client_id: cliClientId,
-      device_code,
-    });
+    // Auth0 may keep this request open longer than a typical HTTP call; 15s caused false "Request timed out".
+    const tokenResp = await withRetries(
+      () => postForm(`https://${domain}/oauth/token`, {
+        grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+        client_id: cliClientId,
+        device_code,
+      }, 120_000),
+      { attempts: 6, baseDelayMs: 2000 },
+    );
 
     if (tokenResp.status === 200 && tokenResp.data.id_token) {
       // 5. Exchange JWT for personal token
-      const result = await postJson(`${serverUrl}/api/auth/device-token`, {
-        jwt: tokenResp.data.id_token,
-      });
+      const result = await withRetries(
+        () => postJson(`${serverUrl}/api/auth/device-token`, {
+          jwt: tokenResp.data.id_token,
+        }, 120_000),
+        { attempts: 5, baseDelayMs: 2000 },
+      );
       if (!result?.token) throw new Error('Server returned no token — contact your admin');
       return result;
     }
@@ -386,14 +426,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 +457,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') {
@@ -498,10 +537,11 @@ export default async function init() {
     try {
       authResult = await deviceCodeAuth(serverUrl);
     } catch (err) {
-      if (err.message.includes('not configured')) {
+      const msg = (err && err.message) ? err.message : String(err);
+      if (msg.includes('not configured')) {
         warn(`  Auth not configured on server — personal mode (events sent via git identity)`);
       } else {
-        warn(`  Authentication failed: ${err.message}`);
+        warn(`  Authentication failed: ${msg}`);
         warn(`  Run "npx -y ai-lens init" again later to authenticate`);
       }
     }
@@ -530,8 +570,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 +771,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...');