CometAI

A terminal CLI tool that monitors your Claude AI token usage in real time — showing burn rate, cost, and remaining quota. Exports a live JSON snapshot every 5 seconds and can auto-start on macOS login.

Features

• Daily view — aggregated token usage, cost breakdown by model, 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
• CSSO authentication — Keycloak SSO login for company-wide deployment
• Extensible — designed to add Codex and Gemini support later

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, cost breakdown by model, and a 7-day history table.

Realtime view

cometai --view realtime

Refreshes every second. Press Ctrl+C to exit. Shows current session, burn rate (tokens/min), cost/hour, 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.totalCost'

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 | https://comet-ai-tracking-backend-production.up.railway.app/api/usage | POST payload to backend | | Custom API key | (none) | Bearer token for your API |

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

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 planned Codex and Gemini support.