CometAI

A terminal CLI tool that monitors your Claude Code and Codex token usage in real time. Exports a live JSON snapshot every 5 seconds and can auto-start on macOS login.

Features

• Daily view — input, output, cache-write, and cache-read token usage with 7-day history
• Realtime view — live-updating terminal UI with burn rate and time-to-limit
• Team view — snapshot of all team members' usage pulled from the backend
• Team live view — auto-refreshing team table (15s) with color-coded status
• JSON export — writes ~/.cometai/data/latest.json every 5 seconds
• Auto-start — installs as a macOS LaunchAgent to run silently on login
• Custom API push — POSTs the JSON payload to your backend automatically
• Chat sync upload — POSTs Claude chat history rows to /api/chat-sync with checkpointed retries
• CSSO authentication — Keycloak SSO login for company-wide deployment
• Codex support — reads local Codex session rollouts; no API key required

Requirements

• Node.js 18+ (node --version)
• npm 8+ (npm --version)
• Claude Code installed and used (data lives in ~/.claude/projects/)

Installation

1. Clone or download the project

git clone https://github.com/YOUR_USERNAME/cometai.git
cd cometai

2. Install dependencies

npm install

3. Install globally

npm install -g .

This makes the cometai command available everywhere in your terminal.

Verify installation

cometai --version

Update

Once installed, you can update from anywhere — no need to keep the source repo:

cometai --update

This will:

1. Clone the repo into ~/.cometai/src/ (first run only)
2. Pull the latest changes from GitHub
3. Reinstall the CLI globally
4. Restart the LaunchAgent automatically (if installed)

To check if an update is available without applying it:

cometai --check-update

Usage

Quick overview

cometai

Prints your current version, today's snapshot, and all available commands.

Daily summary

cometai --view daily

Shows today's token usage by consumption type and a 7-day history table:

• Input — your prompt and context sent to the model
• Output — the model's generated response
• Cache write — new context saved to the prompt cache
• Cache read — previously cached context reused for the request

Total tokens is the sum of these categories. Cache entries remain visible so you can see how much context is newly stored versus reused.

Realtime view

cometai --view realtime

Refreshes every second. Press Ctrl+C to exit. Shows current-session and daily input, output, cache-write, and cache-read tokens, plus burn rate and remaining quota.

Team view

cometai --view team

Fetches all team members' current usage from the backend and displays it as a table. Columns are color-coded:

• Tokens / Messages — green <50%, yellow 50–80%, red >80%
• Last Activity — green <8h, yellow 8–24h, red >24h

Team live view

cometai --view team-live

Same as team view but auto-refreshes every 15 seconds and clears the screen on each update. Press Ctrl+C to exit.

Export JSON once

cometai --export-once

Writes a snapshot to ~/.cometai/data/latest.json and exits.

Print JSON to stdout

cometai --status

Outputs the full JSON payload — useful for piping into other tools:

cometai --status | jq '.today.totalTokens'

All options

cometai -h

CSSO Login (Company SSO)

Each team member must log in before using the service:

cometai --login

Prompts for your Comet SSO email and password. Credentials are saved locally at ~/.cometai/auth.json and used to identify you in every export.

cometai --logout   # remove saved credentials

How it works

• CSSO (Comet SSO) — Your company identity from Keycloak (auth.comet.la, realm comet). Included in every export so the backend knows which seat generated the usage.
• CCSM (Current Claude Subscription eMail) — The Claude account info read from ~/.claude.json. Shows which Claude subscription is active.

Both are included in latest.json. CSSO is optional — if not logged in, exports continue without it. The token auto-refreshes using saved credentials.

Auto-start on login (macOS)

Requires login first (cometai --login).

cometai --install-service

Creates ~/Library/LaunchAgents/com.cometai.plist and loads it immediately. The exporter runs silently in the background and starts automatically every time you log in.

# Check if running
launchctl list | grep cometai

# View logs
tail -f ~/.cometai/logs/stdout.log

# Remove
cometai --uninstall-service

Configure settings

cometai --config

| Setting | Default | Description | |---|---|---| | Daily token limit | 1,000,000 | Track usage against a budget | | Monthly budget (USD) | $100 | Used for spend tracking | | Export path | ~/.cometai/data/latest.json | JSON output file | | Export interval | 5 seconds | How often to write JSON | | Custom API endpoint | (not configured) | POST payload to backend | | Custom API key | (none) | Bearer token for your API | | Chat sync endpoint | (not configured) | POST chat history entries to backend | | Chat sync API key | (none) | Bearer token for /api/chat-sync | | Chat sync interval | 3600 seconds | How often to upload new chat rows |

Config is stored in ~/.cometai/config.json.

JSON export format

~/.cometai/data/latest.json is updated every 5 seconds:

{
  "timestampUTC": "2026-03-05T01:00:00.000Z",
  "timestampLocal": "3/5/2026, 8:00:00 AM",
  "provider": "claude",
  "lastActivityUTC": "2026-03-05T00:55:00.000Z",
  "lastActivityLocal": "3/5/2026, 7:55:00 AM",
  "resetTimeUTC": "2026-03-05T06:00:00.000Z",
  "resetTimeLocal": "3/5/2026, 1:00:00 PM",
  "csso": { "sub": "uuid", "name": "Santi", "email": "[email protected]" },
  "ccsm": { "displayName": "Santi", "email": "[email protected]", "organizationName": "Comet" },
  "today": {
    "date": "2026-03-05",
    "totalTokens": 85000,
    "totalCost": 0.4521,
    "messages": 45,
    "sessions": 2,
    "byModel": { "claude-sonnet-4-6": { "totalTokens": 85000, "cost": 0.4521, "messages": 45 } }
  },
  "currentSession": {
    "sessionId": "53fbf669-...",
    "model": "claude-sonnet-4-6",
    "totalTokens": 85000,
    "cost": 0.4521,
    "burnRate": { "tokensPerMin": 1300, "costPerHour": 0.42 }
  },
  "currentBlock": {
    "blockStart": "2026-03-04T20:00:00.000Z",
    "blockEnd": "2026-03-05T01:00:00.000Z",
    "totalTokens": 5000000,
    "tokenLimit": 39000000,
    "tokenUsagePercent": 12.8,
    "messages": 100,
    "messageLimit": 420,
    "messageUsagePercent": 23.8,
    "cost": 2.50,
    "burnRate": { "tokensPerMin": 950, "messagesPerMin": 0.18, "costPerHour": 1.20, "remainingMin": 142.5 }
  }
}

Uninstall

npm uninstall -g cometai
cometai --uninstall-service  # if LaunchAgent was installed
rm -rf ~/.cometai            # remove all data, config, and cached source

Data source

Token usage is read from Claude Code's local session files:

~/.claude/projects/**/*.jsonl

Codex usage is also read locally, from:

~/.codex/sessions/**/*.jsonl

Codex cached input is reported separately and does not increase the total a second time. Local Codex subscription sessions do not include billable API pricing, so their exported cost is 0 rather than an estimate.

Only files modified within the last 14 days are read for performance. No data is sent anywhere unless a custom API endpoint is configured.

Token pricing

| Model | Input | Output | Cache Write | Cache Read | |---|---|---|---|---| | claude-opus-4-6 | $15/MTok | $75/MTok | $18.75/MTok | $1.50/MTok | | claude-sonnet-4-6 | $3/MTok | $15/MTok | $3.75/MTok | $0.30/MTok | | claude-haiku-4-5 | $0.80/MTok | $4/MTok | $1.00/MTok | $0.08/MTok |

Unknown models fall back to Sonnet pricing. Update src/pricing.js to add new models.

Future providers

See docs/FUTURE_PROVIDERS.md for Gemini and other planned provider support.