@ai-adoption-score/ai-coding-usage 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AI Adoption Score
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,157 @@
-# Temporary Holding Version
+# @ai-adoption-score/ai-coding-usage
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The add-on behind [AI Coding Usage](https://ai-adoption-score.app/product/ai-coding-usage), a survey in AI Adoption
+Score. It counts how a person uses Claude Code and Codex on their Mac and, once connected, shares the numbers with their
+company's survey. Prompts, the AI's answers, code, file names, command text and session titles never leave the Mac.
+
+You don't install it yourself: your survey page shows one line with a code,
+`npx @ai-adoption-score/ai-coding-usage@1 connect <code>`, to paste into Claude Code, Codex or Terminal.
+
+Connected once, it shares by itself: a hook in Claude Code and Codex syncs after a session's replies, at most every 5
+minutes and always when a session ends, and an automatic ping-back, once an hour and without any numbers, tells the
+report "no AI use today" from "no signal".
+
+## How it works, step by step
+
+In short: connect, choose on the survey page, then share. Before the choice, only repository names leave the Mac.
+
+1. **The person pastes the line from their survey page** into Claude Code, Codex or Terminal. The code in it works
+   once, for 30 minutes; the server trades it for a token for this Mac.
+2. **The add-on puts its hooks and the ping-back in place** and copies itself to `~/.ai-adoption-score`. Why: the
+   survey gets the numbers after every session without anyone running a command again, and a hook can't run from
+   npx's temporary folder. The ping-back carries no numbers; it lets the report tell "no AI use today" from "no signal".
+3. **It sends the names of the repositories used in the last 30 days, and nothing else.** Why: the person chooses on
+   their survey page, and the page needs the names to list them. The choice isn't asked in the terminal, because the
+   line usually runs inside Claude Code or Codex, where the add-on can't ask questions. The server keeps the list for
+   an hour at most.
+4. **The person ticks what to share** on their survey page; everything is ticked to start with. When they press
+   Share, the list is deleted, and with it the names they didn't tick.
+5. **Only then do numbers leave the Mac:** the last 30 days of what they ticked, then the new numbers after each
+   session. Before every sync the add-on asks what they chose and keeps everything else on the Mac; the server checks
+   the same rule again.
+6. **It removes itself** when the Mac is disconnected on the survey page or the survey closes. `disconnect` does the
+   same from the Mac.
+
+The person makes their choice on the survey page, so the survey's server keeps it and the add-on follows the server's
+answer. It still checks what it's told:
+
+- It reads 30 days back at most, whatever the server asks for.
+- It shares nothing when the choice isn't one of the two kinds the server keeps: what the person ticked, or
+  `{ "all": true }` for links made before people could choose.
+- It sends the token over https only. Plain http works only for this Mac's own address (`localhost`), for testing.
+
+## Commands
+
+- `connect <code> [--server <url>]`: links this Mac to the survey with the code from the survey page and puts the
+  hooks and the ping-back in place. Then it sends the names of the repositories used in the last 30 days, and nothing
+  else, so the person can choose on their survey page which to share; a background wait shares the last 30 days of
+  those once they press Share. The server defaults to `https://app.ai-adoption-score.app`;
+  `AI_ADOPTION_SCORE_SERVER` or `--server http://localhost:3000` point it at a local app; any other server has to be
+  https. Run again on a Mac that is connected, it keeps that Mac's link on the same server (the survey page still
+  shows one Mac) and lets the person choose again; a link on another server is disconnected, and its token never goes
+  to the new one.
+- `sync`: shares now instead of after the next session. It counts the window again and sends the rows that changed
+  since the server last accepted them; the server replaces what it had, so nothing counts twice.
+- `status`: which survey this Mac shares with, what the person chose, the hooks and when they last ran, and when it
+  last shared.
+- `disconnect`: stops sharing from this Mac and removes everything it put in place.
+- `preview [--days 30] [--company github.com/acme] [--json]`: what would be shared, without sending.
+
+The hooks run `hook <tool>` and the ping-back runs `check-in`, its name inside the add-on; people don't.
+
+## What it puts in place
+
+- `~/.ai-adoption-score/`, readable only by the Mac's user: `config.json` with the device token, `state.json` with a
+  fingerprint of every row the server accepted and when each hook last ran, a short `log.txt`, a copy of the add-on in
+  `app/` (a hook can't depend on npx's temporary folder), and `run.sh`, which finds Node for the hooks, because desktop
+  apps don't load the shell's PATH.
+- A hook for `SessionStart`, `Stop` and `SessionEnd` in `~/.claude/settings.json` and `~/.codex/hooks.json`, added
+  after the hooks already there. The command never changes between versions, because Codex trusts a hook by its exact
+  text, its name and its place. Codex runs it only once the person trusts it: the Codex app lists it under Settings →
+  Hooks as "AI Adoption Score", a "New hook" with a Trust button, and Codex in Terminal asks when it starts.
+- `~/Library/LaunchAgents/app.ai-adoption-score.check-in.plist`, the ping-back, once an hour at low priority.
+
+The settings files are written in their own style (indent, last newline, `\u` escapes), through a link when the file
+is one, so taking the hook out leaves them byte for byte as they were.
+
+A hook prints nothing (a `SessionStart` hook's output would go into the conversation, and Codex refuses text from a
+`Stop` hook), returns in about 40 ms and starts the sync in its own low-priority process. One sync runs at a time. A
+sync that can't reach the server keeps the rows changed, so the next one sends them: the Mac is the queue.
+
+**Each tool pauses on its own.** After the first sync, a tool's rows go out only while its hook is in place and has
+run since connecting. Declining the Codex hook, or deleting either hook, pauses that tool; when the hook is back, the
+waiting days go out, within the 30 days the records last.
+
+**It removes itself** when the survey page disconnects the Mac or the survey closes: the next sync or ping-back hears
+it and takes away the hooks, the ping-back and the folder. If someone deletes the folder by hand, the leftover hooks do
+nothing, and `disconnect` still takes them away.
+
+For testing, `AI_ADOPTION_SCORE_HOME`, `AI_ADOPTION_SCORE_CLAUDE_SETTINGS`, `AI_ADOPTION_SCORE_CODEX_HOOKS` and
+`AI_ADOPTION_SCORE_LAUNCH_AGENTS` move each of these elsewhere, and `AI_ADOPTION_SCORE_SKIP_LAUNCHCTL=1` leaves launchd
+alone. `AI_ADOPTION_SCORE_NODE` names a Node for `run.sh` to try.
+
+## Try it
+
+Count this Mac's last 30 days and see what would be shared, without connecting and without sending anything:
+
+```bash
+npx @ai-adoption-score/ai-coding-usage@1 preview
+```
+
+Add `--json` to see the exact rows, or `--days 7` for a shorter window. It needs Node.js 18.17 or newer and git, and
+runs on macOS only for now.
+
+## What it reads
+
+- **Claude Code:** `~/.claude/projects/**/*.jsonl`, or `$CLAUDE_CONFIG_DIR/projects`. For each line: its kind, time,
+  session, folder and branch, the model and token counts of the AI's replies, and the names of the tools it used.
+  For the AI's edits, the diff Claude Code stores with each result. Lines that hold prompt text or titles
+  (`last-prompt`, `custom-title`, `ai-title`) are skipped.
+- **Codex:** `~/.codex/sessions/**/rollout-*.jsonl`, or `$CODEX_HOME/sessions`. For each line: its kind, time, thread,
+  folder, repository and branch, the model, per-reply token records, and tool and connector names.
+  `session_index.jsonl`, which holds thread names, is never opened.
+- **The Claude desktop app's connector names:** only `remoteMcpServersConfig` in its session files, so claude.ai
+  connectors show as "Notion" rather than an id. Everything else in those files is skipped.
+- **git, in each session's folder:** the remote's address, which branches exist on a remote, and the person's own
+  commits by time. No file is opened and nothing is fetched.
+
+Text is looked at only to tell a prompt from a tool result and to count changed lines. An edited file's path is
+used only to check that the edit is inside the session's project. Neither is ever kept.
+
+## Which repositories
+
+Nothing from the sessions leaves the Mac before the person chooses. The page lists the repositories the add-on found,
+by owner, all ticked to start with; the names of the ones they untick are deleted when they press Share, and sessions
+already shared from them are deleted too. Before every sync the add-on asks what they chose (`GET
+/api/usage/repositories`) and sends only those sessions (`src/choice.mjs`); the server checks the same rule again.
+
+A repository that shows up later is shared when its owner (`github.com/acme`) was ticked in full, and so is a new
+folder without a remote when every such folder was ticked. Anything else stays on the Mac until the person runs the line
+again and ticks it. Work outside any repository is one more box.
+
+## What a row holds
+
+One row per session, day, repository and branch: the tool, a hash of the session id, the day and the first and last
+moment, the repository and branch and whether the branch is pushed, active minutes, prompts, stops, rejected actions,
+commands, file edits, lines added and removed, connector calls by name, skills, helper agents, commits and pushed
+commits, and per model its replies and tokens. `npx @ai-adoption-score/ai-coding-usage@1 preview --json` prints the exact rows this Mac
+would send.
+
+Never shared: prompts, AI answers, code, file names and paths, command text, session titles.
+
+## How it counts
+
+- Each Claude Code reply is written as several lines that repeat its usage, so it counts once, by message id and
+  request id. A resumed session copies earlier lines into a new file, so each line counts once, by its id.
+- A helper agent's file carries its parent's session id: its tokens and tool calls count in the parent session.
+- A Codex thread that Codex starts itself, such as its automatic reviewer, counts in the session that started it,
+  with no session or prompts of its own.
+- Codex's input count includes the cached part; rows keep them apart, as Claude Code does.
+- Connectors are tools someone connected: GitHub, Linear, Notion. The apps' own tools (the desktop app's browser,
+  terminal and session tools, Codex's code runners) aren't counted.
+- A removed folder, such as a deleted worktree, counts under the repository around it, when that still exists.
+- An edit counts once Claude Code reports it done, and only inside the session's project: its repository, or its
+  folder outside git. Its lines come from the diff Claude Code stores with the result, and a new file counts all its
+  lines as added. A failed or turned-down edit, or a scratch file elsewhere, doesn't count.
+- Active minutes add up the gaps under five minutes. A commit counts for the session whose window holds it, from its
+  first moment to an hour after its last; each commit counts once.

package/bin/ai-coding-usage.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// @ts-check
+import { runCli } from '../src/cli.mjs'
+
+runCli(process.argv.slice(2)).then(
+  (code) => {
+    process.exitCode = code
+  },
+  (error) => {
+    process.stderr.write(`Something went wrong: ${error instanceof Error ? error.message : String(error)}\n`)
+    process.exitCode = 1
+  }
+)

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@ai-adoption-score/ai-coding-usage",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "Shares how you use Claude Code and Codex with your company's AI Adoption Score survey. Never prompts, AI answers, code or file names.",
+  "homepage": "https://ai-adoption-score.app/product/ai-coding-usage",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ai-adoption-score/ai-coding-usage.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ai-adoption-score/ai-coding-usage/issues",
+    "email": "support@ai-adoption-score.app"
+  },
+  "author": "AI Adoption Score <support@ai-adoption-score.app> (https://ai-adoption-score.app)",
+  "keywords": [
+    "ai-adoption-score",
+    "claude-code",
+    "codex",
+    "ai-coding",
+    "usage"
+  ],
+  "type": "module",
+  "bin": {
+    "ai-coding-usage": "bin/ai-coding-usage.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/api.mjs

@@ -0,0 +1,70 @@
+// @ts-check
+import { readFileSync } from 'node:fs'
+
+/** Talking to the survey's server. Only JSON with numbers and names goes out; the device token goes in a header. */
+
+const TIMEOUT_MS = 20_000
+
+export const CLIENT_VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version
+
+/** Plain http goes only to this Mac itself, for testing; the device token goes anywhere else over https. */
+const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]'])
+
+/** Why the add-on won't talk to `server`, or null when it will. @param {string} server */
+export function serverProblem(server) {
+  let url
+  try {
+    url = new URL(server)
+  } catch {
+    return `"${server}" isn't a web address.`
+  }
+  if (url.protocol === 'https:') return null
+  if (url.protocol === 'http:' && LOCAL_HOSTS.has(url.hostname)) return null
+  return `"${server}" isn't https. Plain http works only for this Mac's own address (localhost), for testing.`
+}
+
+/**
+ * @param {string} server @param {string} path @param {unknown} body @param {string} [token]
+ * @returns {Promise<{ status: number, body: any, retryAfterSeconds: number | null }>}
+ */
+export async function post(server, path, body, token) {
+  return request(server, path, 'POST', body, token)
+}
+
+/**
+ * @param {string} server @param {string} path @param {string} [token]
+ * @returns {Promise<{ status: number, body: any, retryAfterSeconds: number | null }>}
+ */
+export async function get(server, path, token) {
+  return request(server, path, 'GET', undefined, token)
+}
+
+/** @param {string} server @param {string} path @param {'GET' | 'POST'} method @param {unknown} body @param {string} [token] */
+async function request(server, path, method, body, token) {
+  const problem = serverProblem(server)
+  if (problem) throw new Error(problem)
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS)
+  try {
+    const response = await fetch(new URL(path, server), {
+      method,
+      headers: {
+        ...(method === 'POST' ? { 'content-type': 'application/json' } : {}),
+        'user-agent': `ai-coding-usage/${CLIENT_VERSION}`,
+        ...(token ? { authorization: `Bearer ${token}` } : {}),
+      },
+      ...(method === 'POST' ? { body: JSON.stringify(body) } : {}),
+      signal: controller.signal,
+    })
+    let parsed = null
+    try {
+      parsed = await response.json()
+    } catch {
+      parsed = null
+    }
+    const retryAfter = Number(response.headers.get('retry-after'))
+    return { status: response.status, body: parsed, retryAfterSeconds: Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter : null }
+  } finally {
+    clearTimeout(timer)
+  }
+}

package/src/checkin.mjs

@@ -0,0 +1,96 @@
+// @ts-check
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { CLIENT_VERSION, post } from './api.mjs'
+import { isCurrentConfig, readConfig } from './config.mjs'
+import { hookState, uninstallAll } from './install.mjs'
+import { log } from './log.mjs'
+import { paths } from './paths.mjs'
+import { localDay } from './rows.mjs'
+import { readState, updateState } from './state.mjs'
+
+/**
+ * The hourly check-in (a launchd agent): tells the survey this Mac is there, and whether each tool's hook is still in
+ * place and running. It sends no usage numbers. A day with a check-in and no use is a real zero in the report; a day
+ * without one is a gap.
+ */
+
+const NOT_APPROVED_GRACE_MS = 15 * 60_000
+
+/** Whether any of a tool's records changed since a moment: only file dates are read, never their contents. */
+function recordsChangedSince(dir, since) {
+  if (!existsSync(dir)) return false
+  const stack = [dir]
+  while (stack.length > 0) {
+    const current = /** @type {string} */ (stack.pop())
+    let entries
+    try {
+      entries = readdirSync(current, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const entry of entries) {
+      const path = join(current, entry.name)
+      if (entry.isDirectory()) stack.push(path)
+      else if (entry.name.endsWith('.jsonl')) {
+        try {
+          if (statSync(path).mtimeMs > since) return true
+        } catch {
+          // Gone between listing and reading.
+        }
+      }
+    }
+  }
+  return false
+}
+
+/**
+ * A tool's hook as the check-in reports it: `not-approved` when it is in place but hasn't run since connecting although
+ * the tool was used, as with a Codex hook nobody approved yet.
+ * @param {'claude-code' | 'codex'} tool
+ */
+export function reportedHookState(tool, config, state, env = process.env) {
+  const present = hookState(tool, env)
+  if (present !== 'installed') return present
+  const ran = state.hookRuns?.[tool]
+  const connected = Date.parse(config.connectedAt)
+  if (ran && Date.parse(ran) >= connected) return 'installed'
+  // A session open while connecting keeps writing before its hook first runs: only use well after connecting counts.
+  const records = tool === 'claude-code' ? paths(env).claudeRecords : paths(env).codexRecords
+  return recordsChangedSince(records, connected + NOT_APPROVED_GRACE_MS) ? 'not-approved' : 'installed'
+}
+
+export async function runCheckIn(env = process.env) {
+  const config = readConfig(env)
+  if (!config) {
+    // Settings gone but the check-in left behind: take it away too.
+    uninstallAll(env)
+    return 0
+  }
+  const state = readState(env)
+  const checkIn = {
+    day: localDay(Date.now()),
+    claudeHook: reportedHookState('claude-code', config, state, env),
+    codexHook: reportedHookState('codex', config, state, env),
+  }
+  try {
+    const response = await post(config.server, '/api/usage/sync', { schemaVersion: 1, clientVersion: CLIENT_VERSION, rows: [], checkIn }, config.token)
+    const status = response.body?.status
+    if ((status === 'revoked' || status === 'closed') && !isCurrentConfig(config, env)) {
+      log(`check-in: ${status} for an earlier connection; this Mac connected again, so nothing is removed`, env)
+      return 0
+    }
+    if (status === 'revoked' || status === 'closed') {
+      log(`check-in: ${status}, removing the add-on`, env)
+      uninstallAll(env)
+      return 0
+    }
+    updateState((current) => {
+      current.lastCheckInAt = new Date().toISOString()
+    }, env)
+    log(`check-in: ${response.status} ${status ?? ''} claude=${checkIn.claudeHook} codex=${checkIn.codexHook}`, env)
+  } catch (error) {
+    log(`check-in failed: ${error instanceof Error ? error.message : String(error)}`, env)
+  }
+  return 0
+}

package/src/choice.mjs

@@ -0,0 +1,92 @@
+// @ts-check
+
+/**
+ * Which repositories the person shares. They choose on their survey page when this Mac connects: the add-on sends the
+ * names of the repositories it found, nothing else, and every sync sends only the sessions of what they chose. A new
+ * repository is shared when its owner was ticked in full; otherwise it stays on this Mac until they run the line again.
+ * The server applies the same rule.
+ *
+ * @typedef {{ repositories: string[], owners: string[], outsideGit: boolean, localFolders: boolean } | { all: true }} RepositoryChoice
+ */
+
+/** A git repository without a remote, named after its folder. */
+export const LOCAL_PREFIX = 'local:'
+
+/** The owner of `github.com/acme/app`: `github.com/acme`. None for a folder without a remote. @param {string} repository */
+export function repositoryOwner(repository) {
+  if (!repository || repository.startsWith(LOCAL_PREFIX)) return null
+  const parts = repository.split('/')
+  return parts.length >= 3 ? `${parts[0]}/${parts[1]}`.toLowerCase() : null
+}
+
+/**
+ * The choice in the server's answer, taken only in one of the two shapes the server keeps: what the person ticked, or
+ * `{ all: true }` for links made before people could choose. Anything else shares nothing.
+ * @param {unknown} value @returns {RepositoryChoice | null}
+ */
+export function readChoice(value) {
+  if (!value || typeof value !== 'object') return null
+  const choice = /** @type {Record<string, unknown>} */ (value)
+  if ('all' in choice) return choice.all === true ? { all: true } : null
+  const names = (list) => Array.isArray(list) && list.every((name) => typeof name === 'string')
+  if (!names(choice.repositories) || !names(choice.owners)) return null
+  if (typeof choice.outsideGit !== 'boolean' || typeof choice.localFolders !== 'boolean') return null
+  return {
+    repositories: /** @type {string[]} */ (choice.repositories),
+    owners: /** @type {string[]} */ (choice.owners),
+    outsideGit: choice.outsideGit,
+    localFolders: choice.localFolders,
+  }
+}
+
+/**
+ * Whether a session in `repository` (null outside any repository) is shared. Nothing is, before the person chooses.
+ * @param {RepositoryChoice | null} choice @param {string | null} repository
+ */
+export function isShared(choice, repository) {
+  if (!choice) return false
+  if ('all' in choice) return choice.all === true
+  if (!repository) return choice.outsideGit
+  if (choice.repositories.includes(repository)) return true
+  if (repository.startsWith(LOCAL_PREFIX)) return choice.localFolders
+  const owner = repositoryOwner(repository)
+  return owner !== null && choice.owners.some((ticked) => ticked.toLowerCase() === owner)
+}
+
+/** At most this many names go to the page: the most recently used, if there are more. */
+const MAX_REPOSITORIES = 500
+
+/**
+ * What the person chooses from: the names of the repositories the rows ran in, and whether any work ran outside a
+ * repository. Nothing about the sessions themselves.
+ * @param {Array<{ repository: string | null, lastEventAt: string }>} rows
+ */
+export function repositoryList(rows) {
+  /** @type {Map<string, string>} */
+  const lastUse = new Map()
+  let outsideGit = false
+  for (const row of rows) {
+    if (!row.repository) {
+      outsideGit = true
+      continue
+    }
+    const seen = lastUse.get(row.repository)
+    if (!seen || row.lastEventAt > seen) lastUse.set(row.repository, row.lastEventAt)
+  }
+  const repositories = [...lastUse.entries()]
+    .sort((left, right) => right[1].localeCompare(left[1]))
+    .slice(0, MAX_REPOSITORIES)
+    .map(([name]) => name)
+    .sort((left, right) => left.localeCompare(right))
+  return { schemaVersion: /** @type {const} */ (1), repositories, outsideGit }
+}
+
+/** What this Mac shares, in a line for `status`. @param {RepositoryChoice | null} choice */
+export function describeChoice(choice) {
+  if (!choice) return 'nothing yet: choose your repositories on your survey page'
+  if ('all' in choice) return choice.all === true ? 'every repository' : 'nothing'
+  const parts = [`${choice.repositories.length} ${choice.repositories.length === 1 ? 'repository' : 'repositories'}`]
+  if (choice.owners.length > 0) parts.push(`new ones from ${choice.owners.join(', ')}`)
+  if (choice.outsideGit) parts.push('work outside a repository')
+  return parts.join(', ')
+}