ai-native-profile 0.1.1 → 0.2.0

package/README.md

@@ -33,6 +33,14 @@ The command prints a short-lived verification URL and code. Open the URL, sign i
 npx --yes ai-native-profile@latest sync
 ```
 
+For the fastest setup, sign in on the website and choose **Power up with coding activity**. The site creates a one-time command like this:
+
+```bash
+npx --yes ai-native-profile@latest connect --code ABCD1234
+```
+
+That command is already associated with the signed-in profile. It detects sources, displays the privacy boundary, asks once before the first sync, and updates the open card without requiring the code to be entered again.
+
 To keep syncing every 15 minutes while the command is running:
 
 ```bash
@@ -46,7 +54,7 @@ npx --yes ai-native-profile@latest watch
 | Source | Collection path | Trust label |
 |---|---|---|
 | Codex | Official local App Server account usage | Official account source |
-| Claude Code | Local statistics cache | Local exact |
+| Claude Code | Deduplicated local session usage plus non-overlapping statistics-cache history | Local exact for retained records; partial lifetime coverage |
 | Cursor | Supported local database metadata | Estimated; excluded from rankings |
 | Gemini CLI | Locally retained CLI telemetry | Locally derived |
 | GitHub Copilot CLI | Locally retained CLI activity | Locally derived |
@@ -59,6 +67,7 @@ Normal synchronization may include:
 
 - Dates and provider/model identifiers
 - Token, session, turn, and tool-call counts
+- Input, output, cache-write, and cache-read token counts when a provider reports them
 - Duration, coverage, freshness, and provenance
 - Collector version and an anonymous device identifier
 
@@ -96,6 +105,16 @@ Use a self-hosted deployment instead of the managed service:
 npx --yes ai-native-profile@latest connect --api-url https://your-domain.example
 ```
 
+## Troubleshooting Codex discovery
+
+The collector checks the shell `PATH` and the standard macOS ChatGPT/Codex app-bundle locations for the Codex App Server executable. If yours lives elsewhere, provide its exact path:
+
+```bash
+ANP_CODEX_PATH=/path/to/codex npx --yes ai-native-profile@latest preview
+```
+
+If the App Server is unavailable, the collector reports that Codex was skipped and continues collecting other detected sources instead of failing the entire sync.
+
 ## What the evidence means
 
 Every metric carries its source, coverage dates, freshness, and provenance. A device signature protects integrity in transit; it does not make a user-controlled computer tamper-proof. Activity demonstrates workflow adoption, not developer skill, productivity, code quality, or AI authorship.

package/bin/anp.mjs

@@ -1,12 +1,14 @@
 #!/usr/bin/env node
 import { createHmac, randomUUID } from 'node:crypto';
 import { spawn } from 'node:child_process';
-import { existsSync, readFileSync, mkdirSync, writeFileSync, rmSync, readdirSync, statSync } from 'node:fs';
+import { createReadStream, existsSync, readFileSync, mkdirSync, writeFileSync, rmSync, readdirSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { createInterface } from 'node:readline';
+import { resolveCodexExecutable } from '../src/codex-executable.mjs';
+import { addClaudeSessionEvent, createClaudeSessionAccumulator, finalizeClaudeSessionUsage, mergeClaudeUsage, parseClaudeStatsCache } from '../src/claude-usage.mjs';
 
-const VERSION = '0.1.1';
+const VERSION = '0.2.0';
 const DEFAULT_API_URL = 'https://ai-native-profile.vercel.app';
 const configDir = join(homedir(), '.config', 'ai-native-profile');
 const configFile = join(configDir, 'config.json');
@@ -19,7 +21,15 @@ const paths = {
 };
 
 const sourceNames = { codex: 'Codex', claude_code: 'Claude Code', cursor: 'Cursor', gemini_cli: 'Gemini CLI', copilot_cli: 'GitHub Copilot CLI' };
-const detectedSources = () => Object.entries(paths).map(([source, candidates]) => ({ source, detected: candidates.some(existsSync) }));
+const detectedSources = () => Object.entries(paths).map(([source, candidates]) => {
+  if (source !== 'codex') {
+    const detected = candidates.some(existsSync);
+    return { source, detected, detail:detected ? 'detected' : 'not detected' };
+  }
+  const executable = resolveCodexExecutable();
+  const localData = candidates.some(existsSync);
+  return { source, detected:Boolean(executable), detail:executable ? 'detected' : localData ? 'local data found; App Server unavailable' : 'not detected' };
+});
 const loadConfig = () => { try { return JSON.parse(readFileSync(configFile, 'utf8')); } catch { return {}; } };
 const saveConfig = (value) => { mkdirSync(configDir, { recursive: true, mode: 0o700 }); writeFileSync(configFile, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 }); };
 
@@ -32,19 +42,32 @@ function canonicalJson(value) {
   return JSON.stringify(value);
 }
 
-function claudeAggregate() {
+async function claudeAggregate() {
   const file = paths.claude_code.find((path) => path.endsWith('stats-cache.json') && existsSync(path));
-  if (!file) return null;
-  try {
-    const stats = JSON.parse(readFileSync(file, 'utf8'));
-    const tokenRows = new Map((stats.dailyModelTokens ?? []).map((row) => [row.date, Object.values(row.tokensByModel ?? {}).reduce((sum, value) => sum + Number(value || 0), 0)]));
-    return (stats.dailyActivity ?? []).filter((row) => /^\d{4}-\d{2}-\d{2}$/.test(row.date ?? '')).map((row) => ({
-      date: row.date, source: 'claude_code', category: 'coding',
-      metrics: [
-        ['sessions', row.sessionCount ?? 0], ['turns', row.messageCount ?? 0], ['tool_calls', row.toolCallCount ?? 0], ['tokens', tokenRows.get(row.date) ?? 0],
-      ].filter(([, value]) => Number(value) > 0).map(([name, value]) => ({ name, value:Number(value), unit:'count', provenance:'local_exact', source:'claude_code', coverageStart:row.date, coverageEnd:row.date, competitiveEligible:true })),
-    }));
-  } catch { return null; }
+  let legacy = { daily: [], undatedCacheTokens:0 };
+  if (file) try { legacy = parseClaudeStatsCache(JSON.parse(readFileSync(file, 'utf8'))); } catch {}
+
+  const accumulator = createClaudeSessionAccumulator();
+  let malformedLines = 0;
+  const projectRoots = paths.claude_code.filter((path) => !path.endsWith('stats-cache.json'));
+  for (const sessionFile of localFiles(projectRoots).filter((path) => /\.jsonl$/i.test(path))) {
+    try {
+      const lines = createInterface({ input:createReadStream(sessionFile, { encoding:'utf8' }), crlfDelay:Infinity });
+      for await (const line of lines) {
+        if (!line.trim()) continue;
+        try { addClaudeSessionEvent(accumulator, JSON.parse(line)); }
+        catch { malformedLines += 1; }
+      }
+    } catch { malformedLines += 1; }
+  }
+  const session = finalizeClaudeSessionUsage(accumulator);
+  const daily = mergeClaudeUsage(session.daily, legacy.daily);
+  if (!daily.length) return null;
+  const notes = ['Exact retained session records include input, output, cache-write, and cache-read tokens; local retention cannot prove complete lifetime coverage.'];
+  if (legacy.daily.length) notes.push('Older stats-cache days include combined base input/output tokens only.');
+  if (legacy.undatedCacheTokens) notes.push(`${Math.round(legacy.undatedCacheTokens)} older cache tokens lack day-level attribution and are excluded from dated totals.`);
+  if (malformedLines) notes.push(`${malformedLines} malformed local record${malformedLines === 1 ? ' was' : 's were'} skipped.`);
+  return { daily, completeness:'partial', note:notes.join(' ') };
 }
 
 function localFiles(candidates, limit = 300) {
@@ -100,7 +123,13 @@ async function cursorAggregate() {
 }
 
 async function codexAggregate() {
-  const child = spawn('codex', ['app-server'], { stdio: ['pipe', 'pipe', process.env.ANP_DEBUG === '1' ? 'inherit' : 'ignore'] });
+  const executable = resolveCodexExecutable();
+  if (!executable) throw new Error('Codex App Server is unavailable. Install the Codex CLI or set ANP_CODEX_PATH to its executable.');
+  const child = spawn(executable, ['app-server'], { stdio: ['pipe', 'pipe', process.env.ANP_DEBUG === '1' ? 'inherit' : 'ignore'] });
+  const started = new Promise((resolve, reject) => {
+    child.once('spawn', resolve);
+    child.once('error', (error) => reject(new Error(`Could not start Codex App Server: ${error.message}`)));
+  });
   const lines = createInterface({ input: child.stdout });
   const pending = new Map();
   lines.on('line', (line) => { try { const message = JSON.parse(line); if (typeof message.id === 'number') pending.get(message.id)?.(message); } catch {} });
@@ -110,6 +139,7 @@ async function codexAggregate() {
     child.stdin.write(`${JSON.stringify({ id, method, params })}\n`);
   });
   try {
+    await started;
     await request(1, 'initialize', { clientInfo: { name:'ai_native_profile', title:'AI Native Profile', version:VERSION } });
     child.stdin.write(`${JSON.stringify({ method:'initialized', params:{} })}\n`);
     const usage = await request(2, 'account/usage/read');
@@ -125,14 +155,19 @@ async function codexAggregate() {
 
 async function createBatch() {
   let codexDaily = [];
-  try { codexDaily = await codexAggregate(); } catch (error) { if (process.env.ANP_DEBUG === '1') console.error(`Codex usage unavailable: ${error instanceof Error ? error.message : String(error)}`); }
-  const daily = [...codexDaily, ...(claudeAggregate() ?? []), ...(await cursorAggregate()), ...genericLocalAggregate('gemini_cli', paths.gemini_cli), ...genericLocalAggregate('copilot_cli', paths.copilot_cli)];
+  const hasCodexState = paths.codex.some(existsSync);
+  if (hasCodexState || resolveCodexExecutable()) {
+    try { codexDaily = await codexAggregate(); }
+    catch (error) { console.error(`Codex skipped: ${error instanceof Error ? error.message : String(error)}`); }
+  }
+  const claude = await claudeAggregate();
+  const daily = [...codexDaily, ...(claude?.daily ?? []), ...(await cursorAggregate()), ...genericLocalAggregate('gemini_cli', paths.gemini_cli), ...genericLocalAggregate('copilot_cli', paths.copilot_cli)];
   const dates = daily.map((day) => day.date).sort();
   const sources = [...new Set(daily.map((day) => day.source))];
   const batch = {
     schemaVersion:'anp.activity.v1', batchId:randomUUID(), deviceId:loadConfig().deviceId ?? randomUUID(), generatedAt:new Date().toISOString(), collectorVersion:VERSION,
     daily,
-    coverage: sources.map((source) => { const sourceDays = daily.filter((day) => day.source === source); const sourceDates = sourceDays.map((day) => day.date).sort(); const competitiveEligible = sourceDays.some((day) => day.metrics.some((metric) => metric.competitiveEligible)); return { source, coverageStart:sourceDates[0] ?? dates[0], coverageEnd:sourceDates.at(-1) ?? dates.at(-1), lastSyncedAt:new Date().toISOString(), completeness:source === 'codex' || source === 'claude_code' ? 'full' : 'partial', competitiveEligible, note:source === 'cursor' ? 'Estimated from supported local database metadata; excluded from rankings.' : source === 'gemini_cli' || source === 'copilot_cli' ? 'Derived from locally retained CLI telemetry; prompt content is never emitted.' : undefined }; }),
+    coverage: sources.map((source) => { const sourceDays = daily.filter((day) => day.source === source); const sourceDates = sourceDays.map((day) => day.date).sort(); const competitiveEligible = sourceDays.some((day) => day.metrics.some((metric) => metric.competitiveEligible)); return { source, coverageStart:sourceDates[0] ?? dates[0], coverageEnd:sourceDates.at(-1) ?? dates.at(-1), lastSyncedAt:new Date().toISOString(), completeness:source === 'codex' ? 'full' : source === 'claude_code' ? claude?.completeness ?? 'unknown' : 'partial', competitiveEligible, note:source === 'claude_code' ? claude?.note : source === 'cursor' ? 'Estimated from supported local database metadata; excluded from rankings.' : source === 'gemini_cli' || source === 'copilot_cli' ? 'Derived from locally retained CLI telemetry; prompt content is never emitted.' : undefined }; }),
     signature:'pending',
   };
   const secret = loadConfig().deviceToken ?? 'preview-only';
@@ -142,13 +177,53 @@ async function createBatch() {
 
 function printSources() {
   console.log('AI Native Profile source check\n');
-  for (const item of detectedSources()) console.log(`${item.detected ? '●' : '○'} ${sourceNames[item.source].padEnd(20)} ${item.detected ? 'detected' : 'not detected'}`);
+  for (const item of detectedSources()) console.log(`${item.detected ? '●' : '○'} ${sourceNames[item.source].padEnd(20)} ${item.detail}`);
   console.log('\nOnly aggregate activity leaves this device. Run `anp preview` to inspect it.');
 }
 
+function confirmFirstSync() {
+  if (process.argv.includes('--yes')) return Promise.resolve(true);
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return Promise.resolve(false);
+  const prompt = createInterface({ input:process.stdin, output:process.stdout });
+  return new Promise((resolve) => prompt.question('\nSync these aggregate activity counts now? [Y/n] ', (answer) => {
+    prompt.close();
+    resolve(!/^n(?:o)?$/i.test(answer.trim()));
+  }));
+}
+
+function printPrivacyPreview() {
+  console.log('\nMay sync: dates, provider/model IDs, token and activity counts, duration, coverage, and collector version.');
+  console.log('Never syncs: prompts, responses, source code, commands, paths, repositories, credentials, or environment variables.');
+}
+
+async function claimWebConnection(apiUrl, userCode) {
+  const response = await fetch(`${apiUrl.replace(/\/$/, '')}/api/v1/device/claim`, {
+    method:'POST',
+    headers:{ 'content-type':'application/json' },
+    body:JSON.stringify({ userCode, deviceName:process.env.USER ?? 'Developer device', collectorVersion:VERSION }),
+  });
+  const body = await response.json().catch(() => ({}));
+  if (!response.ok || !body.deviceToken || !body.deviceId) throw new Error(body.error ?? `Connection failed (${response.status}).`);
+  saveConfig({ apiUrl, deviceId:body.deviceId, deviceToken:body.deviceToken });
+  console.log('Connected to your AI Native Profile.');
+  printSources();
+  printPrivacyPreview();
+  if (await confirmFirstSync()) {
+    await sync();
+    console.log('Your card is updated. Return to the browser to see it.');
+  } else {
+    console.log('\nConnected without syncing. Run `anp preview` to inspect the payload, then `anp sync` when ready.');
+  }
+}
+
 async function connect() {
   const apiUrl = option('api-url') ?? process.env.ANP_API_URL ?? DEFAULT_API_URL;
   if (!/^https?:\/\//.test(apiUrl)) throw new Error('The API URL must start with https:// or http://.');
+  const connectionCode = option('code');
+  if (connectionCode) {
+    await claimWebConnection(apiUrl, connectionCode);
+    return;
+  }
   const response = await fetch(`${apiUrl.replace(/\/$/, '')}/api/v1/device/pair`, { method:'POST', headers:{ 'content-type':'application/json' }, body:JSON.stringify({ deviceName:process.env.USER ?? 'Developer device', collectorVersion:VERSION }) });
   if (!response.ok) throw new Error(`Pairing failed (${response.status}).`);
   const pair = await response.json();
@@ -181,7 +256,7 @@ async function sync() {
 }
 
 function help() {
-  console.log(`AI Native Profile collector ${VERSION}\n\nUsage: anp <command> [options]\n\n  connect      Pair this device with the cloud dashboard\n               --api-url <url> overrides the hosted dashboard\n  sources      Detect supported coding tools\n  preview      Print the exact aggregate payload\n  sync         Send one aggregate batch\n  watch        Sync every 15 minutes until stopped\n  doctor       Check configuration and sources\n  sessions     Explain selected-session sharing\n  share        Publish a selected sanitized session\n  unshare      Revoke a shared session\n  export       Alias for preview\n  disconnect   Remove the local platform pairing\n`);
+  console.log(`AI Native Profile collector ${VERSION}\n\nUsage: anp <command> [options]\n\n  connect      Pair this device with the cloud dashboard\n               --code <code> claims a command created by the signed-in website\n               --api-url <url> overrides the hosted dashboard\n               --yes approves the first aggregate sync without prompting\n  sources      Detect supported coding tools\n  preview      Print the exact aggregate payload\n  sync         Send one aggregate batch\n  watch        Sync every 15 minutes until stopped\n  doctor       Check configuration and sources\n  sessions     Explain selected-session sharing\n  share        Publish a selected sanitized session\n  unshare      Revoke a shared session\n  export       Alias for preview\n  disconnect   Remove the local platform pairing\n`);
 }
 
 function option(name) { const index = process.argv.indexOf(`--${name}`); return index >= 0 ? process.argv[index + 1] : undefined; }

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "ai-native-profile",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Privacy-first collector for AI Native Profile",
   "license": "MIT",
   "type": "module",
   "bin": { "anp": "bin/anp.mjs", "ai-native-profile": "bin/anp.mjs" },
-  "files": ["bin", "src", "README.md"],
+  "files": ["bin", "src/codex-app-server.ts", "src/codex-executable.mjs", "src/claude-usage.mjs", "README.md"],
   "engines": { "node": ">=22.13.0" },
   "repository": {
     "type": "git",
@@ -14,6 +14,6 @@
   },
   "homepage": "https://ai-native-profile.vercel.app",
   "bugs": { "url": "https://github.com/Gaurav890/ai-native-profile/issues" },
-  "publishConfig": { "access": "public", "provenance": true },
+  "publishConfig": { "access": "public" },
   "keywords": ["developer-tools", "analytics", "activity", "profile", "privacy"]
 }

package/src/claude-usage.mjs

@@ -0,0 +1,139 @@
+const datePattern = /^\d{4}-\d{2}-\d{2}$/;
+
+function safeCount(value) {
+  const count = Number(value ?? 0);
+  return Number.isFinite(count) && count >= 0 ? count : 0;
+}
+
+function metric(name, value, date) {
+  return {
+    name,
+    value,
+    unit: 'count',
+    provenance: 'local_exact',
+    source: 'claude_code',
+    coverageStart: date,
+    coverageEnd: date,
+    competitiveEligible: true,
+  };
+}
+
+function usageTotal(usage) {
+  return safeCount(usage.inputTokens)
+    + safeCount(usage.outputTokens)
+    + safeCount(usage.cacheCreationInputTokens)
+    + safeCount(usage.cacheReadInputTokens);
+}
+
+export function createClaudeSessionAccumulator() {
+  return { messages: new Map(), sessionStarts: new Map(), warnings: [] };
+}
+
+export function addClaudeSessionEvent(accumulator, event) {
+  if (!event || typeof event !== 'object') return;
+  const sessionId = String(event.sessionId ?? event.session_id ?? '');
+  const timestamp = typeof event.timestamp === 'string' ? event.timestamp : '';
+  const date = timestamp.slice(0, 10);
+  if (sessionId && datePattern.test(date)) {
+    const existing = accumulator.sessionStarts.get(sessionId);
+    if (!existing || date < existing) accumulator.sessionStarts.set(sessionId, date);
+  }
+
+  const message = event.message;
+  const rawUsage = message?.usage;
+  if (!message || !rawUsage || !sessionId || !datePattern.test(date)) return;
+  const messageId = String(message.id ?? event.requestId ?? '');
+  if (!messageId) return;
+
+  const usage = {
+    inputTokens: safeCount(rawUsage.input_tokens),
+    outputTokens: safeCount(rawUsage.output_tokens),
+    cacheCreationInputTokens: safeCount(rawUsage.cache_creation_input_tokens),
+    cacheReadInputTokens: safeCount(rawUsage.cache_read_input_tokens),
+  };
+  const candidate = {
+    date,
+    timestamp,
+    model: typeof message.model === 'string' && message.model ? message.model : 'unknown',
+    toolCalls: Array.isArray(message.content) ? message.content.filter((block) => block?.type === 'tool_use').length : 0,
+    usage,
+  };
+  const key = `${sessionId}:${messageId}`;
+  const existing = accumulator.messages.get(key);
+  const candidateTotal = usageTotal(candidate.usage);
+  const existingTotal = existing ? usageTotal(existing.usage) : -1;
+  if (!existing || candidate.timestamp > existing.timestamp || (candidate.timestamp === existing.timestamp && candidateTotal > existingTotal)) {
+    accumulator.messages.set(key, candidate);
+  }
+}
+
+export function finalizeClaudeSessionUsage(accumulator) {
+  const rows = new Map();
+  const row = (date) => {
+    const existing = rows.get(date);
+    if (existing) return existing;
+    const created = { sessions: 0, turns: 0, toolCalls: 0, inputTokens: 0, outputTokens: 0, cacheCreationInputTokens: 0, cacheReadInputTokens: 0, models: {} };
+    rows.set(date, created);
+    return created;
+  };
+
+  for (const date of accumulator.sessionStarts.values()) row(date).sessions += 1;
+  for (const message of accumulator.messages.values()) {
+    const current = row(message.date);
+    current.turns += 1;
+    current.toolCalls += message.toolCalls;
+    current.inputTokens += message.usage.inputTokens;
+    current.outputTokens += message.usage.outputTokens;
+    current.cacheCreationInputTokens += message.usage.cacheCreationInputTokens;
+    current.cacheReadInputTokens += message.usage.cacheReadInputTokens;
+    current.models[message.model] = (current.models[message.model] ?? 0) + usageTotal(message.usage);
+  }
+
+  const daily = [...rows.entries()].sort(([left], [right]) => left.localeCompare(right)).map(([date, current]) => {
+    const tokens = current.inputTokens + current.outputTokens + current.cacheCreationInputTokens + current.cacheReadInputTokens;
+    const values = [
+      ['sessions', current.sessions],
+      ['turns', current.turns],
+      ['tool_calls', current.toolCalls],
+      ['tokens', tokens],
+      ['input_tokens', current.inputTokens],
+      ['output_tokens', current.outputTokens],
+      ['cache_creation_input_tokens', current.cacheCreationInputTokens],
+      ['cache_read_input_tokens', current.cacheReadInputTokens],
+    ];
+    return {
+      date,
+      source: 'claude_code',
+      category: 'coding',
+      metrics: values.filter(([, value]) => value > 0).map(([name, value]) => metric(name, value, date)),
+      models: current.models,
+    };
+  });
+  return { daily, messageCount: accumulator.messages.size, warnings: accumulator.warnings };
+}
+
+export function parseClaudeStatsCache(stats) {
+  if (!stats || typeof stats !== 'object') return { daily: [], undatedCacheTokens: 0 };
+  const activityByDate = new Map((stats.dailyActivity ?? []).filter((item) => datePattern.test(item?.date ?? '')).map((item) => [item.date, item]));
+  const tokensByDate = new Map((stats.dailyModelTokens ?? []).filter((item) => datePattern.test(item?.date ?? '')).map((item) => [item.date, Object.values(item.tokensByModel ?? {}).reduce((sum, value) => sum + safeCount(value), 0)]));
+  const dates = [...new Set([...activityByDate.keys(), ...tokensByDate.keys()])].sort();
+  const daily = dates.map((date) => {
+    const activity = activityByDate.get(date) ?? {};
+    const values = [
+      ['sessions', safeCount(activity.sessionCount)],
+      ['turns', safeCount(activity.messageCount)],
+      ['tool_calls', safeCount(activity.toolCallCount)],
+      ['tokens', safeCount(tokensByDate.get(date))],
+    ];
+    return { date, source: 'claude_code', category: 'coding', metrics: values.filter(([, value]) => value > 0).map(([name, value]) => metric(name, value, date)) };
+  });
+  const modelUsage = Object.values(stats.modelUsage ?? {});
+  const undatedCacheTokens = modelUsage.reduce((sum, usage) => sum + safeCount(usage?.cacheReadInputTokens) + safeCount(usage?.cacheCreationInputTokens), 0);
+  return { daily, undatedCacheTokens };
+}
+
+export function mergeClaudeUsage(sessionDaily, legacyDaily) {
+  const merged = new Map(legacyDaily.map((day) => [day.date, day]));
+  for (const day of sessionDaily) merged.set(day.date, day);
+  return [...merged.values()].sort((left, right) => left.date.localeCompare(right.date));
+}

package/src/codex-app-server.ts

@@ -1,10 +1,16 @@
 import { spawn } from 'node:child_process';
 import { createInterface } from 'node:readline';
+import { resolveCodexExecutable } from './codex-executable.mjs';
 
 type RpcResponse = { id?: number; result?: unknown; error?: { message?: string } };
 
-export async function readCodexAccountUsage(timeoutMs = 8_000): Promise<unknown> {
-  const child = spawn('codex', ['app-server'], { stdio: ['pipe', 'pipe', 'pipe'] });
+export async function readCodexAccountUsage(timeoutMs = 8_000, executable = resolveCodexExecutable()): Promise<unknown> {
+  if (!executable) throw new Error('Codex App Server is unavailable. Install the Codex CLI or set ANP_CODEX_PATH to its executable.');
+  const child = spawn(executable, ['app-server'], { stdio: ['pipe', 'pipe', 'pipe'] });
+  const started = new Promise<void>((resolve, reject) => {
+    child.once('spawn', resolve);
+    child.once('error', (error) => reject(new Error(`Could not start Codex App Server: ${error.message}`)));
+  });
   const lines = createInterface({ input: child.stdout });
   const pending = new Map<number, (response: RpcResponse) => void>();
   lines.on('line', (line) => {
@@ -24,7 +30,8 @@ export async function readCodexAccountUsage(timeoutMs = 8_000): Promise<unknown>
     child.stdin.write(`${JSON.stringify({ id, method, params })}\n`);
   });
   try {
-    await request(1, 'initialize', { clientInfo: { name: 'ai_native_profile', title: 'AI Native Profile', version: '0.1.0' } });
+    await started;
+    await request(1, 'initialize', { clientInfo: { name: 'ai_native_profile', title: 'AI Native Profile', version: '0.2.0' } });
     child.stdin.write(`${JSON.stringify({ method: 'initialized', params: {} })}\n`);
     return await request(2, 'account/usage/read');
   } finally {

package/src/codex-executable.mjs

@@ -0,0 +1,34 @@
+import { accessSync, constants } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, join } from 'node:path';
+
+/**
+ * @param {{ env?: Record<string, string | undefined>; platform?: NodeJS.Platform; home?: string }} [options]
+ */
+export function codexExecutableCandidates({ env = process.env, platform = process.platform, home = homedir() } = {}) {
+  const names = platform === 'win32' ? ['codex.exe', 'codex.cmd', 'codex.bat', 'codex'] : ['codex'];
+  const pathCandidates = String(env.PATH ?? '').split(delimiter).filter(Boolean).flatMap((directory) => names.map((name) => join(directory, name)));
+  const appCandidates = platform === 'darwin' ? [
+    '/Applications/ChatGPT.app/Contents/Resources/codex',
+    '/Applications/Codex.app/Contents/Resources/codex',
+    join(home, 'Applications', 'ChatGPT.app', 'Contents', 'Resources', 'codex'),
+    join(home, 'Applications', 'Codex.app', 'Contents', 'Resources', 'codex'),
+  ] : [];
+  return [...new Set([env.ANP_CODEX_PATH, ...pathCandidates, ...appCandidates].filter(Boolean))];
+}
+
+/**
+ * @param {{ env?: Record<string, string | undefined>; platform?: NodeJS.Platform; home?: string; canExecute?: (candidate: string) => boolean }} [options]
+ */
+export function resolveCodexExecutable(options = {}) {
+  const platform = options.platform ?? process.platform;
+  const canExecute = options.canExecute ?? ((candidate) => {
+    try {
+      accessSync(candidate, platform === 'win32' ? constants.F_OK : constants.X_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+  return codexExecutableCandidates(options).find(canExecute) ?? null;
+}