ai-lens 0.8.51 → 0.8.53

package/.commithash

@@ -1 +1 @@
-7c4d056
+c830ed5

package/README.md

@@ -1,6 +1,8 @@
 # AI Lens
 
-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.
+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
@@ -19,6 +21,7 @@ This will:
 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.
 
@@ -27,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; nested repos under these roots are included
+export AI_LENS_SERVER_URL=https://ai-lens.rantsports.com
+export AI_LENS_PROJECTS="~/meta/, ~/meta-cursor/"   # optional, default: all
 ```
 
 <details>
@@ -96,47 +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
 docker compose up postgres -d
-npm install --prefix server   # Install server deps (auto-runs via prestart)
+npm install
 DATABASE_URL=postgresql://ailens:ailens@localhost:5432/ailens npm start
 ```
 
-The server now requires PostgreSQL via `DATABASE_URL`. The old SQLite fallback is no longer supported.
-
 ## 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`
@@ -144,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 }
 ```
@@ -163,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` | _(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) |
+| 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
 
@@ -203,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/bin/ai-lens.js

@@ -15,7 +15,7 @@ switch (command) {
   }
   case 'status': {
     const { default: status } = await import('../cli/status.js');
-    await status();
+    await status({ report: process.argv.includes('--report') });
     break;
   }
   case 'version':

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', 'codex.js', 'codex-watcher.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));
   }
 
@@ -165,11 +174,12 @@ export function installClientFiles() {
     '{"type":"module"}\n',
   );
 
-  // Write version.json so installed capture.js can identify itself
+  // Write version.json so installed capture.js can identify itself.
+  // packageRoot lets sender.js find bin/ai-lens.js for background status reports.
   const { version, commit } = getVersionInfo();
   writeFileSync(
     join(CLIENT_INSTALL_DIR, 'version.json'),
-    JSON.stringify({ version, commit }) + '\n',
+    JSON.stringify({ version, commit, packageRoot: PKG_ROOT }) + '\n',
   );
 }
 

package/cli/init.js

@@ -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,26 @@ 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;
@@ -219,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;
     }
@@ -510,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`);
       }
     }

package/cli/status.js

@@ -5,7 +5,7 @@ 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, getMonitoredProjects } from '../client/config.js';
+import { DATA_DIR, PENDING_DIR, SENDING_DIR, SESSION_PATHS_DIR, LOG_PATH, CAPTURE_LOG_PATH, LAST_STATUS_REPORT_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';
@@ -92,6 +92,42 @@ function expandTilde(pathStr) {
   return pathStr;
 }
 
+/**
+ * Detect install mode from the capture.js path in hook commands.
+ * Returns { ok, summary, detail } for the status output.
+ */
+function detectInstallMode(tools) {
+  const copyDir = join(homedir(), '.ai-lens', 'client') + '/';
+  const paths = [];
+  for (const tool of tools) {
+    const cmd = extractHookCommand(tool);
+    if (!cmd) continue;
+    const m = cmd.match(/["']([^"']*capture\.js)["']|(\S*capture\.js)/);
+    if (m) paths.push({ tool: tool.name, raw: m[1] || m[2], resolved: expandTilde(m[1] || m[2]) });
+  }
+  if (paths.length === 0) {
+    return { ok: null, summary: 'unknown', detail: 'No hook commands found — cannot determine install mode' };
+  }
+  const modes = paths.map(p => {
+    if (p.resolved.startsWith(copyDir)) return 'copy';
+    return 'repo-path';
+  });
+  const unique = [...new Set(modes)];
+  const mode = unique.length === 1 ? unique[0] : 'mixed';
+  const detail = paths.map(p => {
+    const m = p.resolved.startsWith(copyDir) ? 'copy' : 'repo-path';
+    return `  ${p.tool}: ${m} (${p.raw})`;
+  }).join('\n');
+
+  if (mode === 'copy') {
+    return { ok: true, summary: 'copy (~/.ai-lens/client/)', detail: `Client files copied to ~/.ai-lens/client/\nUpdate: npx -y ai-lens init --yes\n${detail}` };
+  }
+  if (mode === 'repo-path') {
+    return { ok: true, summary: 'repo-path (auto-update on git pull)', detail: `Hooks point directly to repo/package source\nUpdate: git pull (or npx cache refresh)\n${detail}` };
+  }
+  return { ok: null, summary: `mixed (${unique.join(' + ')})`, detail: `Different tools use different install modes:\n${detail}` };
+}
+
 function validateHookCommandPaths(tool) {
   const command = extractHookCommand(tool);
   if (!command) return null;
@@ -1059,43 +1095,83 @@ function buildReport(results, timestamp, warnings = [], allTools = TOOL_CONFIGS)
   return lines.join('\n');
 }
 
+// ---------------------------------------------------------------------------
+// Report mode: POST structured status to server
+// ---------------------------------------------------------------------------
+
+async function sendStatusReport(results, warnings, clientVersion, clientCommit, serverUrl, authToken) {
+  if (!serverUrl || !authToken) return;
+
+  const payload = {
+    timestamp: new Date().toISOString(),
+    client_version: clientVersion,
+    client_commit: clientCommit,
+    node_version: process.version,
+    os: `${process.platform} ${osRelease()} ${osArch()}`,
+    checks: results.map(({ label, ok, summary, detail }) => ({ label, ok, summary, detail })),
+    warnings: warnings.map(({ msg, action }) => ({ msg, action })),
+  };
+
+  try {
+    const res = await fetch(`${serverUrl}/api/client-reports`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Auth-Token': authToken,
+        'X-Client-Version': `${clientVersion}+${clientCommit}`,
+      },
+      body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(15_000),
+    });
+    if (res.ok) {
+      try { writeFileSync(LAST_STATUS_REPORT_PATH, new Date().toISOString()); } catch {}
+    }
+  } catch {
+    // Silent — report is best-effort
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
 
-export default async function status() {
+export default async function status({ report = false } = {}) {
   const versionResult = checkVersion();
-  initLogger(versionResult.summary);
+  if (!report) initLogger(versionResult.summary);
 
   const { version, commit } = getVersionInfo();
-  blank();
-  info(`${BOLD}AI Lens Status v${version} (${commit})${RESET}`);
-  info('='.repeat(40));
-  blank();
+  if (!report) {
+    blank();
+    info(`${BOLD}AI Lens Status v${version} (${commit})${RESET}`);
+    info('='.repeat(40));
+    blank();
+  }
 
   const results = [];
 
   function printLine(label, result) {
-    const icon = result.ok === true ? CHECK : result.ok === false ? CROSS : `${DIM}-${RESET}`;
-    const pad = ' '.repeat(Math.max(1, 17 - label.length));
-    info(`${label}:${pad}${icon} ${result.summary}`);
+    if (!report) {
+      const icon = result.ok === true ? CHECK : result.ok === false ? CROSS : `${DIM}-${RESET}`;
+      const pad = ' '.repeat(Math.max(1, 17 - label.length));
+      info(`${label}:${pad}${icon} ${result.summary}`);
+    }
     results.push({ label, ...result });
   }
 
   // 1. System info
   const sys = checkSystem();
-  info(`${'System:'}          ${sys.summary}`);
+  if (!report) info(`${'System:'}          ${sys.summary}`);
   results.push({ label: 'System', ...sys });
 
   // 2. Tool versions
   const claude = checkToolVersion('Claude');
   const cursor = checkToolVersion('Cursor');
   if (claude.ok !== null) {
-    info(`${'Claude Code:'}     ${claude.summary}`);
+    if (!report) info(`${'Claude Code:'}     ${claude.summary}`);
     results.push({ label: 'Claude Code version', ...claude });
   }
   if (cursor.ok !== null) {
-    info(`${'Cursor:'}          ${cursor.summary}`);
+    if (!report) info(`${'Cursor:'}          ${cursor.summary}`);
     results.push({ label: 'Cursor version', ...cursor });
   }
 
@@ -1155,6 +1231,10 @@ export default async function status() {
     detail: `Global hooks active: ${hasGlobalHooks}\nProject hooks active: ${hasProjectHooks}${hasGlobalHooks && hasProjectHooks ? '\nWarning: both global and project hooks are active — events may be captured twice. Run init with --project-hooks to consolidate.' : ''}`,
   });
 
+  // 6c. Install mode: detect how capture.js is referenced in hooks
+  const installMode = detectInstallMode(toolsWithProject);
+  printLine('Install mode', installMode);
+
   // 7. Queue (before capture test so test event doesn't show as pending)
   const queueResult = checkQueue();
   printLine('Queue', queueResult);
@@ -1200,7 +1280,7 @@ export default async function status() {
     serverReachable: serverResult.ok === true,
   });
 
-  if (warnings.length > 0) {
+  if (!report && warnings.length > 0) {
     blank();
     info('='.repeat(40));
     info(`${BOLD}Warnings${RESET}`);
@@ -1211,19 +1291,23 @@ export default async function status() {
     }
   }
 
-  // Write report file
-  const timestamp = new Date().toISOString();
-  // Merge global TOOL_CONFIGS (always listed, even if not installed) with project tools
-  const allToolsForReport = [...TOOL_CONFIGS, ...toolsWithProject.filter(t => !TOOL_CONFIGS.includes(t))];
-  const report = buildReport(results, timestamp, warnings, allToolsForReport);
-  try {
-    writeFileSync(REPORT_PATH, report);
-    blank();
-    info(`${DIM}Full report \u2192 ${REPORT_PATH}${RESET}`);
-  } catch (err) {
+  if (report) {
+    // --report mode: POST structured JSON to server, update marker file
+    await sendStatusReport(results, warnings, version, commit, serverUrl, authToken);
+  } else {
+    // Normal mode: write text report file
+    const timestamp = new Date().toISOString();
+    // Merge global TOOL_CONFIGS (always listed, even if not installed) with project tools
+    const allToolsForReport = [...TOOL_CONFIGS, ...toolsWithProject.filter(t => !TOOL_CONFIGS.includes(t))];
+    const reportText = buildReport(results, timestamp, warnings, allToolsForReport);
+    try {
+      writeFileSync(REPORT_PATH, reportText);
+      blank();
+      info(`${DIM}Full report \u2192 ${REPORT_PATH}${RESET}`);
+    } catch (err) {
+      blank();
+      error(`Could not write report: ${err.message}`);
+    }
     blank();
-    error(`Could not write report: ${err.message}`);
   }
-
-  blank();
 }