codex-usage-dashboard 0.1.0

package/README.md

@@ -0,0 +1,113 @@
+# Codex Usage Dashboard
+
+Multi-user Codex usage tracking with a Vercel-hosted dashboard, Supabase Auth, and both direct `npx` connect and website pairing flows.
+
+## Stack
+
+- Vite + TanStack Router + React Query
+- Supabase Auth + Postgres
+- Vercel Functions for pairing and sync ingest
+- Local Codex access through `codex app-server`
+
+## What changed
+
+This repo no longer treats the dashboard as a public read-only board.
+
+- Users can start from the website with Google, or from the terminal with a one-line `npx` command.
+- The direct terminal path provisions a dashboard session, opens the browser, and stores the local sync token under `CODEX_HOME`.
+- The website pairing flow is still available and now emits `npx` commands instead of `curl | node`.
+- Vercel receives sync payloads and writes them to Supabase with the service-role key.
+- Row-level security keeps each signed-in user scoped to their own accounts and snapshots.
+
+## Local setup
+
+1. Start Docker Desktop.
+2. Run `npm install`.
+3. Run `npm run setup:local`.
+4. Run `supabase db reset`.
+5. Run `npm run dev`.
+6. Open `http://localhost:5173`.
+
+The Vite dev server now serves the local pairing and sync API routes under `/api/*`.
+
+## Hosted setup
+
+1. Link the repo to a hosted Supabase project with `supabase link --project-ref <ref>`.
+2. Run `npm run setup:hosted`.
+3. Set these Vercel environment variables:
+   - `SUPABASE_URL`
+   - `SUPABASE_SERVICE_ROLE_KEY`
+   - `VITE_SUPABASE_URL`
+   - `VITE_SUPABASE_ANON_KEY`
+4. In Supabase Auth settings, enable `Manual linking` if you want guest dashboard sessions to upgrade into Google later.
+5. If you want the website-first flow, enable the Google provider in Supabase Auth.
+6. Deploy to Vercel.
+
+`npm run setup:hosted` now writes the local env files and pushes any pending hosted Supabase migrations.
+
+## Direct connect flow
+
+Run this on any machine that already has Codex installed:
+
+```bash
+npx codex-usage-dashboard@latest connect --site "https://your-site.vercel.app"
+```
+
+That command:
+
+- starts a local `codex app-server`
+- reads the current Codex account and rate limits
+- provisions a dashboard owner session without requiring Google first
+- opens the hosted dashboard in the browser
+- stores the device token under `CODEX_HOME` in `codex-usage-sync.json`
+- pushes the first snapshot to the dashboard
+
+If the same machine is already connected, rerun the same command to reopen the dashboard and refresh the local snapshot.
+
+## Website pairing flow
+
+1. Sign in on the website.
+2. Click `Create pairing command`.
+3. Run the generated command on the machine that already has Codex installed.
+
+The generated command looks like:
+
+```bash
+npx codex-usage-dashboard@latest pair "https://your-site.vercel.app/api/pair/complete?token=..."
+```
+
+## Live sync after pairing
+
+To keep syncing from that machine:
+
+```bash
+npx codex-usage-dashboard@latest sync --watch
+```
+
+The saved device token is read from the same Codex home that the CLI uses.
+
+## Dev scripts
+
+- `npm run connect -- --site "<site-url>"`: local version of the direct connect command
+- `npm run pair -- "<pair-url>"`: local version of the hosted pairing command
+- `npm run sync -- --watch`: local version of the hosted sync command
+- `npm run collector`: legacy single-operator collector script
+
+## Tario-specific Git workflow for Codex
+
+If the current machine or user context indicates Tario is the operator, treat that as a master-by-default environment.
+
+- Use the local machine identity to decide this.
+- Treat `scutil --get ComputerName` returning `tario` as the primary signal.
+- Treat `/Users/tarioyou` and the local user `tarioyou` as reinforcing signals.
+- In that Tario context, unless otherwise specified, work directly on `master`.
+- If the user explicitly says to work on a branch, create or switch to that branch and work there.
+- Do not create, switch to, or push feature branches by default.
+- Do not default to PR-first workflows or branch-based workflows unless the user asks for them.
+- This rule is specific to Tario's environment; when the operator is not Tario, normal branch workflows remain allowed.
+
+## Notes
+
+- The Vercel API routes live in `api/`.
+- Pairing and device state live in `codex_pairing_sessions` and `codex_devices`.
+- Existing rows without an owner remain in the database but are hidden by RLS from signed-in users.

package/bin/codex-usage.js

@@ -0,0 +1,661 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import process from 'node:process'
+
+const DEFAULT_POLL_MS = 60_000
+const CONFIG_FILE_NAME = 'codex-usage-sync.json'
+const NPX_COMMAND = 'npx codex-usage-dashboard@latest'
+
+class StdioCodexClient {
+  constructor({ codexHome }) {
+    this.codexHome = codexHome
+    this.child = null
+    this.buffer = ''
+    this.pending = new Map()
+    this.requestId = 0
+    this.notificationHandler = null
+  }
+
+  async connect() {
+    if (this.child) {
+      return
+    }
+
+    this.child = await this.spawnAppServer()
+    this.child.stdout.setEncoding('utf8')
+    this.child.stdout.on('data', (chunk) => {
+      this.consumeStdout(chunk)
+    })
+    this.child.stderr.on('data', (chunk) => {
+      const message = chunk.toString().trim()
+      if (message) {
+        console.error(`[codex] ${message}`)
+      }
+    })
+
+    await this.request('initialize', {
+      capabilities: {},
+      clientInfo: {
+        name: 'codex_usage_sync',
+        title: 'Codex Usage Sync',
+        version: '0.1.0',
+      },
+    })
+    this.notify('initialized', {})
+  }
+
+  async close() {
+    if (!this.child) {
+      return
+    }
+
+    this.child.kill('SIGTERM')
+    this.child = null
+
+    for (const pending of this.pending.values()) {
+      pending.reject(new Error('Codex app-server closed.'))
+    }
+    this.pending.clear()
+  }
+
+  onNotification(handler) {
+    this.notificationHandler = handler
+  }
+
+  request(method, params) {
+    if (!this.child?.stdin || this.child.stdin.destroyed) {
+      throw new Error('Codex app-server is not connected.')
+    }
+
+    const id = ++this.requestId
+    this.child.stdin.write(
+      `${JSON.stringify({
+        id,
+        jsonrpc: '2.0',
+        method,
+        ...(params ? { params } : {}),
+      })}\n`,
+    )
+
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, { reject, resolve })
+    })
+  }
+
+  notify(method, params) {
+    if (!this.child?.stdin || this.child.stdin.destroyed) {
+      return
+    }
+
+    this.child.stdin.write(
+      `${JSON.stringify({
+        jsonrpc: '2.0',
+        method,
+        ...(params ? { params } : {}),
+      })}\n`,
+    )
+  }
+
+  consumeStdout(chunk) {
+    this.buffer += chunk
+
+    while (true) {
+      const newlineIndex = this.buffer.indexOf('\n')
+      if (newlineIndex === -1) {
+        return
+      }
+
+      const line = this.buffer.slice(0, newlineIndex).trim()
+      this.buffer = this.buffer.slice(newlineIndex + 1)
+
+      if (!line) {
+        continue
+      }
+
+      let message
+
+      try {
+        message = JSON.parse(line)
+      } catch {
+        console.error(`[codex] ${line}`)
+        continue
+      }
+
+      if (typeof message.id === 'number') {
+        const pending = this.pending.get(message.id)
+        if (!pending) {
+          continue
+        }
+
+        this.pending.delete(message.id)
+
+        if (message.error) {
+          pending.reject(
+            new Error(message.error.message ?? 'Codex app-server error.'),
+          )
+          continue
+        }
+
+        pending.resolve(message.result)
+        continue
+      }
+
+      if (message.method && this.notificationHandler) {
+        this.notificationHandler(message.method)
+      }
+    }
+  }
+
+  spawnAppServer() {
+    return new Promise((resolve, reject) => {
+      const child = spawn('codex', ['app-server', '--listen', 'stdio://'], {
+        env: {
+          ...process.env,
+          ...(this.codexHome ? { CODEX_HOME: this.codexHome } : {}),
+        },
+        stdio: ['pipe', 'pipe', 'pipe'],
+      })
+
+      child.once('error', (error) => {
+        reject(
+          new Error(
+            error.code === 'ENOENT'
+              ? 'The `codex` command is not installed on this machine.'
+              : error.message,
+          ),
+        )
+      })
+
+      child.once('spawn', () => {
+        child.on('exit', (code) => {
+          if (code !== 0 && code !== null) {
+            console.error(`[codex] app-server exited with code ${code}`)
+          }
+        })
+        resolve(child)
+      })
+    })
+  }
+}
+
+async function main() {
+  const [, , command, ...restArgs] = process.argv
+
+  if (!command || command === '--help' || command === '-h') {
+    printUsage()
+    return
+  }
+
+  const args = parseArgs(restArgs)
+
+  if (command === 'pair') {
+    await runPairCommand(args)
+    return
+  }
+
+  if (command === 'connect') {
+    await runConnectCommand(args)
+    return
+  }
+
+  if (command === 'sync') {
+    await runSyncCommand(args)
+    return
+  }
+
+  throw new Error(`Unknown command: ${command}`)
+}
+
+async function runPairCommand(args) {
+  const pairUrl = args.positionals[0]
+  if (!pairUrl) {
+    throw new Error('Pass the pairing URL from the website.')
+  }
+
+  const codexHome = resolveCodexHome(args.options['codex-home'])
+  const client = new StdioCodexClient({ codexHome })
+
+  try {
+    await client.connect()
+    const snapshot = await readSnapshot(client, true)
+    const device = buildDevicePayload(args, codexHome)
+    const response = await fetch(pairUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        accountState: snapshot.accountState,
+        device,
+        rateLimits: snapshot.rateLimits,
+      }),
+    })
+
+    const payload = await parseJsonResponse(response)
+    if (!response.ok) {
+      throw new Error(payload.error ?? 'Pairing failed.')
+    }
+
+    const config = {
+      authMode: 'website-paired',
+      codexHome,
+      deviceId: payload.deviceId,
+      deviceToken: payload.deviceToken,
+      dashboardOrigin: new URL(pairUrl).origin,
+      label: device.label,
+      pollMs: payload.pollMs ?? DEFAULT_POLL_MS,
+      syncUrl: payload.syncUrl,
+    }
+
+    await writeConfig(codexHome, config)
+    console.log('Pairing complete.')
+    console.log(`Config saved to ${resolveConfigPath(codexHome)}`)
+    console.log(
+      `Next: run \`${NPX_COMMAND} sync --watch\` on this machine for live updates.`,
+    )
+
+    if (args.options.watch) {
+      await runWatchLoop(client, config, args)
+    }
+  } finally {
+    await client.close()
+  }
+}
+
+async function runConnectCommand(args) {
+  const codexHome = resolveCodexHome(args.options['codex-home'])
+  const existingConfig = await readConfig(codexHome)
+  const client = new StdioCodexClient({ codexHome })
+
+  try {
+    await client.connect()
+
+    if (existingConfig) {
+      const dashboardUrl = await resolveExistingDashboardUrl(existingConfig, args)
+
+      if (dashboardUrl) {
+        await openDashboard(dashboardUrl)
+      }
+
+      await syncOnce(client, existingConfig, args)
+      console.log('Dashboard opened.')
+
+      if (args.options.watch) {
+        await runWatchLoop(client, existingConfig, args)
+      }
+
+      return
+    }
+
+    const siteOrigin = resolveSiteOrigin(args.options.site)
+    if (!siteOrigin) {
+      throw new Error(
+        'Pass --site <url> the first time you run connect, or set CODEX_USAGE_SITE_URL.',
+      )
+    }
+
+    const snapshot = await readSnapshot(client, true)
+    const device = buildDevicePayload(args, codexHome)
+    const response = await fetch(new URL('/api/connect/start', siteOrigin), {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        accountState: snapshot.accountState,
+        device,
+        rateLimits: snapshot.rateLimits,
+      }),
+    })
+
+    const payload = await parseJsonResponse(response)
+    if (!response.ok) {
+      throw new Error(payload.error ?? 'Unable to connect this machine.')
+    }
+
+    const config = {
+      authMode: 'guest-link',
+      codexHome,
+      dashboardOrigin: siteOrigin,
+      deviceId: payload.deviceId,
+      deviceToken: payload.deviceToken,
+      label: device.label,
+      pollMs: payload.pollMs ?? DEFAULT_POLL_MS,
+      syncUrl: payload.syncUrl,
+    }
+
+    await writeConfig(codexHome, config)
+    await openDashboard(payload.dashboardUrl)
+    console.log('Dashboard opened.')
+    console.log(`Config saved to ${resolveConfigPath(codexHome)}`)
+    console.log(
+      `Next: rerun \`${NPX_COMMAND} connect --site "${siteOrigin}"\` to reopen this dashboard, or \`${NPX_COMMAND} sync --watch\` for live updates only.`,
+    )
+
+    if (args.options.watch) {
+      await runWatchLoop(client, config, args)
+    }
+  } finally {
+    await client.close()
+  }
+}
+
+async function runSyncCommand(args) {
+  const codexHome = resolveCodexHome(args.options['codex-home'])
+  const config = await readConfig(codexHome)
+  if (!config) {
+    throw new Error(
+      'No pairing config found. Run `connect` or pair this machine from the website first.',
+    )
+  }
+
+  const client = new StdioCodexClient({ codexHome })
+
+  try {
+    await client.connect()
+
+    if (args.options.watch) {
+      await runWatchLoop(client, config, args)
+      return
+    }
+
+    await syncOnce(client, config, args)
+    console.log('Sync complete.')
+  } finally {
+    await client.close()
+  }
+}
+
+async function runWatchLoop(client, config, args) {
+  let scheduledRefresh = null
+  let isSyncing = false
+
+  const run = async () => {
+    if (isSyncing) {
+      return
+    }
+
+    isSyncing = true
+
+    try {
+      await syncOnce(client, config, args)
+      console.log(`[${new Date().toLocaleTimeString()}] Sync complete.`)
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error))
+    } finally {
+      isSyncing = false
+    }
+  }
+
+  client.onNotification((method) => {
+    if (
+      method !== 'account/login/completed' &&
+      method !== 'account/rateLimits/updated' &&
+      method !== 'account/updated'
+    ) {
+      return
+    }
+
+    if (scheduledRefresh) {
+      clearTimeout(scheduledRefresh)
+    }
+
+    scheduledRefresh = setTimeout(() => {
+      void run()
+    }, 500)
+  })
+
+  await run()
+
+  const interval = setInterval(() => {
+    void run()
+  }, config.pollMs ?? DEFAULT_POLL_MS)
+
+  await waitForTermination(async () => {
+    clearInterval(interval)
+
+    if (scheduledRefresh) {
+      clearTimeout(scheduledRefresh)
+      scheduledRefresh = null
+    }
+
+    await client.close()
+  })
+}
+
+async function syncOnce(client, config, args) {
+  const snapshot = await readSnapshot(client, false)
+  if (!snapshot) {
+    return
+  }
+
+  const response = await fetch(config.syncUrl, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      accountState: snapshot.accountState,
+      device: buildDevicePayload(args, config.codexHome, config.label),
+      deviceToken: config.deviceToken,
+      rateLimits: snapshot.rateLimits,
+    }),
+  })
+
+  const payload = await parseJsonResponse(response)
+  if (!response.ok) {
+    throw new Error(payload.error ?? 'Sync failed.')
+  }
+}
+
+async function resolveExistingDashboardUrl(config, args) {
+  if (config.authMode === 'guest-link') {
+    const response = await fetch(new URL('/api/connect/open', config.syncUrl), {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        deviceToken: config.deviceToken,
+      }),
+    })
+
+    const payload = await parseJsonResponse(response)
+    if (!response.ok) {
+      throw new Error(payload.error ?? 'Unable to open the dashboard.')
+    }
+
+    return payload.dashboardUrl ?? null
+  }
+
+  const siteOrigin =
+    resolveSiteOrigin(args.options.site) ??
+    config.dashboardOrigin ??
+    new URL(config.syncUrl).origin
+
+  return siteOrigin || null
+}
+
+async function readSnapshot(client, failWhenLoggedOut) {
+  const accountState = await client.request('account/read', {
+    refreshToken: false,
+  })
+
+  if (!accountState.account) {
+    if (failWhenLoggedOut) {
+      throw new Error(
+        'No logged-in Codex account was found. Run `codex login` and try again.',
+      )
+    }
+
+    console.log('No logged-in Codex account found yet. Waiting for login.')
+    return null
+  }
+
+  const rateLimits = await client.request('account/rateLimits/read')
+  return { accountState, rateLimits }
+}
+
+function buildDevicePayload(args, codexHome, fallbackLabel) {
+  return {
+    codexHome,
+    label: args.options.label ?? fallbackLabel ?? os.hostname(),
+    machineName: os.hostname(),
+    metadata: {
+      arch: process.arch,
+      node: process.version,
+      platform: process.platform,
+    },
+  }
+}
+
+async function openDashboard(url) {
+  try {
+    await openInBrowser(url)
+  } catch {
+    console.log(`Open this URL in your browser: ${url}`)
+  }
+}
+
+function parseArgs(rawArgs) {
+  const options = {}
+  const positionals = []
+
+  for (let index = 0; index < rawArgs.length; index += 1) {
+    const value = rawArgs[index]
+
+    if (!value.startsWith('--')) {
+      positionals.push(value)
+      continue
+    }
+
+    const key = value.slice(2)
+
+    if (key === 'watch') {
+      options.watch = true
+      continue
+    }
+
+    const nextValue = rawArgs[index + 1]
+    if (!nextValue || nextValue.startsWith('--')) {
+      throw new Error(`Missing value for --${key}`)
+    }
+
+    options[key] = nextValue
+    index += 1
+  }
+
+  return { options, positionals }
+}
+
+function resolveSiteOrigin(configuredValue) {
+  const value = configuredValue ?? process.env.CODEX_USAGE_SITE_URL
+  if (!value) {
+    return null
+  }
+
+  return new URL(value).origin
+}
+
+function resolveCodexHome(configuredValue) {
+  const home = configuredValue ?? process.env.CODEX_HOME ?? path.join(os.homedir(), '.codex')
+
+  if (!home.startsWith('~/')) {
+    return home
+  }
+
+  return path.join(os.homedir(), home.slice(2))
+}
+
+function resolveConfigPath(codexHome) {
+  return path.join(codexHome, CONFIG_FILE_NAME)
+}
+
+function openInBrowser(url) {
+  return new Promise((resolve, reject) => {
+    const target =
+      process.platform === 'darwin'
+        ? { args: [url], command: 'open' }
+        : process.platform === 'win32'
+          ? { args: ['/c', 'start', '', url], command: 'cmd' }
+          : { args: [url], command: 'xdg-open' }
+
+    const child = spawn(target.command, target.args, {
+      detached: true,
+      stdio: 'ignore',
+    })
+
+    child.once('error', reject)
+    child.once('spawn', () => {
+      child.unref()
+      resolve()
+    })
+  })
+}
+
+async function writeConfig(codexHome, config) {
+  await mkdir(codexHome, { recursive: true })
+  await writeFile(
+    resolveConfigPath(codexHome),
+    `${JSON.stringify(config, null, 2)}\n`,
+    'utf8',
+  )
+}
+
+async function readConfig(codexHome) {
+  const configPath = resolveConfigPath(codexHome)
+  if (!existsSync(configPath)) {
+    return null
+  }
+
+  return JSON.parse(await readFile(configPath, 'utf8'))
+}
+
+async function parseJsonResponse(response) {
+  const payload = await response.json().catch(() => null)
+  if (!payload || typeof payload !== 'object') {
+    return {}
+  }
+
+  return payload
+}
+
+function waitForTermination(cleanup) {
+  return new Promise((resolve) => {
+    let finished = false
+
+    const finish = async () => {
+      if (finished) {
+        return
+      }
+
+      finished = true
+      await cleanup()
+      resolve()
+    }
+
+    process.once('SIGINT', () => {
+      void finish()
+    })
+    process.once('SIGTERM', () => {
+      void finish()
+    })
+  })
+}
+
+function printUsage() {
+  console.log('Usage:')
+  console.log('  codex-usage connect [--site <url>] [--watch] [--codex-home <path>] [--label <name>]')
+  console.log('  codex-usage pair <pair-url> [--watch] [--codex-home <path>] [--label <name>]')
+  console.log('  codex-usage sync [--watch] [--codex-home <path>] [--label <name>]')
+}
+
+await main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error))
+  process.exit(1)
+})

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "codex-usage-dashboard",
+  "private": false,
+  "version": "0.1.0",
+  "files": [
+    "README.md",
+    "bin"
+  ],
+  "type": "module",
+  "bin": {
+    "codex-usage": "./bin/codex-usage.js",
+    "codex-usage-dashboard": "./bin/codex-usage.js"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "typecheck": "tsc -b",
+    "lint": "eslint .",
+    "preview": "vite preview",
+    "connect": "node ./bin/codex-usage.js connect",
+    "pair": "node ./bin/codex-usage.js pair",
+    "sync": "node ./bin/codex-usage.js sync",
+    "setup:hosted": "tsx scripts/setup-hosted.ts",
+    "setup:local": "tsx scripts/setup-local.ts",
+    "collector": "tsx scripts/codex-collector.ts",
+    "collector:once": "tsx scripts/codex-collector.ts --once"
+  },
+  "dependencies": {
+    "@fontsource-variable/geist": "^5.2.8",
+    "@radix-ui/react-slot": "^1.2.4",
+    "@supabase/supabase-js": "^2.101.1",
+    "@tanstack/react-query": "^5.96.2",
+    "@tanstack/react-query-devtools": "^5.96.2",
+    "@tanstack/react-router": "^1.168.10",
+    "@tanstack/router-devtools": "^1.166.11",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "dotenv": "^17.4.1",
+    "lucide-react": "^1.7.0",
+    "radix-ui": "^1.4.3",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "shadcn": "^4.1.2",
+    "tailwind-merge": "^3.5.0",
+    "tw-animate-css": "^1.4.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.4",
+    "@tailwindcss/vite": "^4.2.2",
+    "@tanstack/router-plugin": "^1.167.12",
+    "@types/node": "^24.12.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.1",
+    "eslint": "^9.39.4",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.5.2",
+    "globals": "^17.4.0",
+    "tailwindcss": "^4.2.2",
+    "tsx": "^4.21.0",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.57.0",
+    "vite": "^8.0.1"
+  }
+}