@davidbrianethier/cc-usage 1.0.0

package/README.md

@@ -0,0 +1,51 @@
+# cc-usage
+
+Claude.ai usage monitor for macOS menubar. Shows your 5-hour and weekly usage limits as text in the menubar.
+
+## Installation
+
+```bash
+# From npm
+npm install -g @davidbrianethier/cc-usage
+
+# Or from GitHub
+npm install -g github:dbe/cc-usage
+```
+
+## Usage
+
+```bash
+# First run - will prompt for sessionKey
+cc-usage
+
+# Re-authenticate
+cc-usage --reauth
+
+# Show help
+cc-usage --help
+```
+
+## Getting Your Session Key
+
+1. Log into [claude.ai](https://claude.ai) in your browser
+2. Open DevTools: `Cmd+Option+I`
+3. Go to **Application** tab > **Cookies** > **claude.ai**
+4. Find `sessionKey` and copy its value
+5. Paste when prompted by cc-usage
+
+## Features
+
+- **Menubar display**: Shows `45%|72%` (5-hour | 7-day usage)
+- **Auto-refresh**: Updates every 10 seconds
+- **Power-aware**: Pauses during system sleep
+- **Auto-start**: Launches on login
+- **Context menu**: Click for Reauth/Quit options
+
+## Requirements
+
+- macOS 10.15+
+- Node.js 18+
+
+## License
+
+ISC

package/bin/cli.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+
+const { spawn, execSync } = require('child_process');
+const path = require('path');
+const readline = require('readline');
+const fs = require('fs');
+
+// Parse arguments
+const args = process.argv.slice(2);
+const showHelp = args.includes('--help') || args.includes('-h');
+const forceReauth = args.includes('--reauth');
+
+if (showHelp) {
+  console.log(`
+cc-usage - Claude.ai Usage Monitor
+
+Usage: cc-usage [options]
+
+Options:
+  --help, -h     Show this help message
+  --reauth       Clear stored session and re-authenticate
+
+First Run:
+  1. Log into claude.ai in your browser
+  2. Open DevTools (Cmd+Option+I) > Application > Cookies > claude.ai
+  3. Copy the value of 'sessionKey' cookie
+  4. Paste when prompted
+
+The app will appear in your menubar showing usage limits.
+  `);
+  process.exit(0);
+}
+
+async function main() {
+  // Dynamic import for ES modules compatibility with keytar
+  const auth = require('../src/auth.js');
+  
+  // Handle --reauth flag
+  if (forceReauth) {
+    await auth.clearSessionKey();
+    console.log('Session cleared. Please enter new session key.');
+  }
+  
+  // Check if we have a session key
+  let hasKey = await auth.hasSessionKey();
+  
+  if (!hasKey) {
+    console.log('\n=== cc-usage Setup ===\n');
+    console.log('To monitor your Claude.ai usage, you need to provide your session key.');
+    console.log('');
+    console.log('How to get your session key:');
+    console.log('  1. Open https://claude.ai in your browser and log in');
+    console.log('  2. Open DevTools: Cmd+Option+I (Mac) or F12 (Windows)');
+    console.log('  3. Go to Application tab > Cookies > claude.ai');
+    console.log('  4. Find "sessionKey" and copy its value');
+    console.log('');
+    
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+    
+    const sessionKey = await new Promise((resolve) => {
+      rl.question('Enter sessionKey: ', (answer) => {
+        rl.close();
+        resolve(answer.trim());
+      });
+    });
+    
+    if (!sessionKey) {
+      console.error('Error: Session key cannot be empty.');
+      process.exit(1);
+    }
+    
+    await auth.setSessionKey(sessionKey);
+    console.log('\nSession key saved to keychain.');
+    console.log('Starting cc-usage...');
+  }
+  
+  const electronPath = require('electron');
+  const appPath = path.join(__dirname, '..');
+  
+  // macOS: clear quarantine attribute from Electron binary to avoid Gatekeeper issues
+  if (process.platform === 'darwin') {
+    const electronApp = path.join(appPath, 'node_modules', 'electron', 'dist', 'Electron.app');
+    if (fs.existsSync(electronApp)) {
+      try {
+        execSync(`xattr -cr "${electronApp}"`, { stdio: 'ignore' });
+      } catch (e) {
+        // Ignore errors - xattr may not be needed
+      }
+    }
+  }
+  
+  const child = spawn(electronPath, [appPath], {
+    detached: true,
+    stdio: 'ignore'
+  });
+  
+  child.unref();
+  
+  console.log('cc-usage is now running in your menubar.');
+  process.exit(0);
+}
+
+main().catch((err) => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@davidbrianethier/cc-usage",
+  "version": "1.0.0",
+  "description": "Claude.ai usage monitor for macOS menubar - shows 5-hour and weekly limits",
+  "main": "src/main.js",
+  "bin": {
+    "cc-usage": "./bin/cli.js"
+  },
+  "scripts": {
+    "start": "electron .",
+    "test": "node --test src/*.test.js"
+  },
+  "keywords": [
+    "claude",
+    "anthropic",
+    "usage",
+    "menubar",
+    "macos",
+    "tray",
+    "monitor"
+  ],
+  "author": "Brian Ethier",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dbe/cc-usage"
+  },
+  "homepage": "https://github.com/dbe/cc-usage#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "os": [
+    "darwin"
+  ],
+  "dependencies": {
+    "keytar": "^7.9.0"
+  },
+  "devDependencies": {
+    "electron": "^33.0.0"
+  }
+}

package/src/api.js

@@ -0,0 +1,104 @@
+const BASE_URL = 'https://claude.ai/api/organizations';
+
+let cachedOrgId = null;
+
+function buildHeaders(sessionKey) {
+  return {
+    'accept': '*/*',
+    'content-type': 'application/json',
+    'anthropic-client-platform': 'web_claude_ai',
+    'anthropic-client-version': '1.0.0',
+    'user-agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+    'origin': 'https://claude.ai',
+    'referer': 'https://claude.ai/settings/usage',
+    'Cookie': `sessionKey=${sessionKey}`
+  };
+}
+
+async function fetchOrganizationId(sessionKey) {
+  if (cachedOrgId) return cachedOrgId;
+  
+  try {
+    const response = await fetch(BASE_URL, {
+      method: 'GET',
+      headers: buildHeaders(sessionKey)
+    });
+    
+    if (!response.ok) {
+      return null;
+    }
+    
+    const orgs = await response.json();
+    if (orgs && orgs.length > 0) {
+      cachedOrgId = orgs[0].uuid;
+      return cachedOrgId;
+    }
+    return null;
+  } catch (error) {
+    return null;
+  }
+}
+
+async function fetchUsage(sessionKey) {
+  const errorResult = {
+    fiveHour: null,
+    sevenDay: null,
+    sevenDayOpus: null,
+    sevenDaySonnet: null,
+    error: null
+  };
+  
+  try {
+    const orgId = await fetchOrganizationId(sessionKey);
+    if (!orgId) {
+      return { ...errorResult, error: '401' };
+    }
+    
+    const response = await fetch(`${BASE_URL}/${orgId}/usage`, {
+      method: 'GET',
+      headers: buildHeaders(sessionKey)
+    });
+    
+    if (!response.ok) {
+      if (response.status === 401 || response.status === 403) {
+        cachedOrgId = null;
+        return { ...errorResult, error: '401' };
+      }
+      return { ...errorResult, error: `HTTP ${response.status}` };
+    }
+    
+    const data = await response.json();
+    
+    return {
+      fiveHour: data.five_hour ? {
+        percent: data.five_hour.utilization,
+        resetsAt: data.five_hour.resets_at ? new Date(data.five_hour.resets_at) : null
+      } : null,
+      sevenDay: data.seven_day ? {
+        percent: data.seven_day.utilization,
+        resetsAt: data.seven_day.resets_at ? new Date(data.seven_day.resets_at) : null
+      } : null,
+      sevenDayOpus: data.seven_day_opus ? {
+        percent: data.seven_day_opus.utilization,
+        resetsAt: data.seven_day_opus.resets_at ? new Date(data.seven_day_opus.resets_at) : null
+      } : null,
+      sevenDaySonnet: data.seven_day_sonnet ? {
+        percent: data.seven_day_sonnet.utilization,
+        resetsAt: data.seven_day_sonnet.resets_at ? new Date(data.seven_day_sonnet.resets_at) : null
+      } : null,
+      error: null
+    };
+  } catch (error) {
+    return { ...errorResult, error: `Network error: ${error.message}` };
+  }
+}
+
+function clearCache() {
+  cachedOrgId = null;
+}
+
+module.exports = {
+  fetchOrganizationId,
+  fetchUsage,
+  clearCache
+};

package/src/api.test.js

@@ -0,0 +1,143 @@
+const { describe, it, mock, beforeEach } = require('node:test');
+const assert = require('node:assert');
+
+describe('api', () => {
+  let api;
+  let mockFetch;
+
+  beforeEach(() => {
+    // Reset module cache to allow fresh mocking
+    delete require.cache[require.resolve('./api.js')];
+    
+    mockFetch = mock.fn();
+    global.fetch = mockFetch;
+  });
+
+  describe('fetchOrganizationId', () => {
+    it('returns organization ID on success', async () => {
+      mockFetch.mock.mockImplementation(() => Promise.resolve({
+        ok: true,
+        status: 200,
+        json: () => Promise.resolve([{ uuid: 'org-123', name: 'Personal' }])
+      }));
+      
+      api = require('./api.js');
+      const result = await api.fetchOrganizationId('sk-ant-test');
+      
+      assert.strictEqual(result, 'org-123');
+    });
+
+    it('returns null on 401', async () => {
+      mockFetch.mock.mockImplementation(() => Promise.resolve({
+        ok: false,
+        status: 401
+      }));
+      
+      api = require('./api.js');
+      const result = await api.fetchOrganizationId('bad-key');
+      
+      assert.strictEqual(result, null);
+    });
+  });
+
+  describe('fetchUsage', () => {
+    it('returns usage data on success', async () => {
+      // First call for org ID, second for usage
+      let callCount = 0;
+      mockFetch.mock.mockImplementation(() => {
+        callCount++;
+        if (callCount === 1) {
+          return Promise.resolve({
+            ok: true,
+            status: 200,
+            json: () => Promise.resolve([{ uuid: 'org-123' }])
+          });
+        }
+        return Promise.resolve({
+          ok: true,
+          status: 200,
+          json: () => Promise.resolve({
+            five_hour: { utilization: 45.5, resets_at: '2026-01-31T00:00:00Z' },
+            seven_day: { utilization: 68.2, resets_at: '2026-02-05T00:00:00Z' },
+            seven_day_opus: { utilization: 77.0, resets_at: '2026-02-05T00:00:00Z' },
+            seven_day_sonnet: { utilization: 30.0, resets_at: '2026-02-05T00:00:00Z' }
+          })
+        });
+      });
+      
+      api = require('./api.js');
+      const result = await api.fetchUsage('sk-ant-test');
+      
+      assert.strictEqual(result.error, null);
+      assert.strictEqual(result.fiveHour.percent, 45.5);
+      assert.strictEqual(result.sevenDay.percent, 68.2);
+      assert.strictEqual(result.sevenDayOpus.percent, 77.0);
+      assert.strictEqual(result.sevenDaySonnet.percent, 30.0);
+    });
+
+    it('returns error object on 401', async () => {
+      mockFetch.mock.mockImplementation(() => Promise.resolve({
+        ok: false,
+        status: 401
+      }));
+      
+      api = require('./api.js');
+      const result = await api.fetchUsage('bad-key');
+      
+      assert.strictEqual(result.error, '401');
+      assert.strictEqual(result.fiveHour, null);
+    });
+
+    it('returns error object on network error', async () => {
+      let callCount = 0;
+      mockFetch.mock.mockImplementation(() => {
+        callCount++;
+        if (callCount === 1) {
+          return Promise.resolve({
+            ok: true,
+            status: 200,
+            json: () => Promise.resolve([{ uuid: 'org-123' }])
+          });
+        }
+        return Promise.reject(new Error('Network error'));
+      });
+      
+      api = require('./api.js');
+      const result = await api.fetchUsage('sk-ant-test');
+      
+      assert.ok(result.error.includes('Network'));
+      assert.strictEqual(result.fiveHour, null);
+    });
+
+    it('handles missing optional fields gracefully', async () => {
+      let callCount = 0;
+      mockFetch.mock.mockImplementation(() => {
+        callCount++;
+        if (callCount === 1) {
+          return Promise.resolve({
+            ok: true,
+            status: 200,
+            json: () => Promise.resolve([{ uuid: 'org-123' }])
+          });
+        }
+        return Promise.resolve({
+          ok: true,
+          status: 200,
+          json: () => Promise.resolve({
+            five_hour: { utilization: 50, resets_at: null },
+            seven_day: { utilization: 60, resets_at: null }
+            // No opus or sonnet fields
+          })
+        });
+      });
+      
+      api = require('./api.js');
+      const result = await api.fetchUsage('sk-ant-test');
+      
+      assert.strictEqual(result.error, null);
+      assert.strictEqual(result.fiveHour.percent, 50);
+      assert.strictEqual(result.sevenDayOpus, null);
+      assert.strictEqual(result.sevenDaySonnet, null);
+    });
+  });
+});

package/src/auth.js

@@ -0,0 +1,56 @@
+/**
+ * Auth module - Keychain-based session key storage
+ */
+
+let keytar = require('keytar');
+
+const SERVICE = 'cc-usage';
+const ACCOUNT = 'sessionKey';
+
+/**
+ * For testing: inject mock keytar
+ * @param {object} mock - Mock keytar object
+ */
+function _setKeytar(mock) {
+  keytar = mock;
+}
+
+/**
+ * Get session key from keychain
+ * @returns {Promise<string|null>} Session key or null if not found
+ */
+async function getSessionKey() {
+  return await keytar.getPassword(SERVICE, ACCOUNT);
+}
+
+/**
+ * Store session key in keychain
+ * @param {string} key - Session key to store
+ */
+async function setSessionKey(key) {
+  await keytar.setPassword(SERVICE, ACCOUNT, key);
+}
+
+/**
+ * Remove session key from keychain
+ */
+async function clearSessionKey() {
+  await keytar.deletePassword(SERVICE, ACCOUNT);
+}
+
+/**
+ * Check if session key exists in keychain
+ * @returns {Promise<boolean>} True if key exists
+ */
+async function hasSessionKey() {
+  const key = await getSessionKey();
+  return key !== null;
+}
+
+module.exports = {
+  getSessionKey,
+  setSessionKey,
+  clearSessionKey,
+  hasSessionKey,
+  _setKeytar
+};

package/src/auth.test.js

@@ -0,0 +1,78 @@
+const { describe, it, mock, beforeEach } = require('node:test');
+const assert = require('node:assert');
+
+// Mock keytar before requiring auth
+const mockKeytar = {
+  getPassword: mock.fn(),
+  setPassword: mock.fn(),
+  deletePassword: mock.fn()
+};
+
+// Use dynamic import pattern to allow mocking
+let auth;
+
+describe('auth', () => {
+  beforeEach(() => {
+    mockKeytar.getPassword.mock.resetCalls();
+    mockKeytar.setPassword.mock.resetCalls();
+    mockKeytar.deletePassword.mock.resetCalls();
+  });
+
+  describe('getSessionKey', () => {
+    it('returns null when no key stored', async () => {
+      mockKeytar.getPassword.mock.mockImplementation(() => Promise.resolve(null));
+      const auth = require('./auth.js');
+      // Inject mock
+      auth._setKeytar(mockKeytar);
+      const result = await auth.getSessionKey();
+      assert.strictEqual(result, null);
+    });
+
+    it('returns stored key when present', async () => {
+      mockKeytar.getPassword.mock.mockImplementation(() => Promise.resolve('sk-ant-123'));
+      const auth = require('./auth.js');
+      auth._setKeytar(mockKeytar);
+      const result = await auth.getSessionKey();
+      assert.strictEqual(result, 'sk-ant-123');
+    });
+  });
+
+  describe('setSessionKey', () => {
+    it('stores key in keychain', async () => {
+      mockKeytar.setPassword.mock.mockImplementation(() => Promise.resolve());
+      const auth = require('./auth.js');
+      auth._setKeytar(mockKeytar);
+      await auth.setSessionKey('sk-ant-456');
+      assert.strictEqual(mockKeytar.setPassword.mock.calls.length, 1);
+      assert.deepStrictEqual(mockKeytar.setPassword.mock.calls[0].arguments, ['cc-usage', 'sessionKey', 'sk-ant-456']);
+    });
+  });
+
+  describe('clearSessionKey', () => {
+    it('removes key from keychain', async () => {
+      mockKeytar.deletePassword.mock.mockImplementation(() => Promise.resolve(true));
+      const auth = require('./auth.js');
+      auth._setKeytar(mockKeytar);
+      await auth.clearSessionKey();
+      assert.strictEqual(mockKeytar.deletePassword.mock.calls.length, 1);
+    });
+  });
+
+  describe('hasSessionKey', () => {
+    it('returns true when key exists', async () => {
+      mockKeytar.getPassword.mock.mockImplementation(() => Promise.resolve('sk-ant-789'));
+      const auth = require('./auth.js');
+      auth._setKeytar(mockKeytar);
+      const result = await auth.hasSessionKey();
+      assert.strictEqual(result, true);
+    });
+
+    it('returns false when no key', async () => {
+      mockKeytar.getPassword.mock.mockImplementation(() => Promise.resolve(null));
+      const auth = require('./auth.js');
+      auth._setKeytar(mockKeytar);
+      const result = await auth.hasSessionKey();
+      assert.strictEqual(result, false);
+    });
+  });
+});

package/src/main.js

@@ -0,0 +1,97 @@
+const { app, Menu, Tray, powerMonitor, nativeImage } = require('electron');
+const { getSessionKey, clearSessionKey } = require('./auth.js');
+const { fetchUsage, clearCache } = require('./api.js');
+
+const POLL_INTERVAL = 10 * 1000;
+const BACKOFF_DELAYS = [5000, 10000, 30000];
+
+let tray = null;
+let pollingInterval = null;
+let retryCount = 0;
+let isPaused = false;
+
+function formatTitle(usage) {
+  if (!usage || usage.error) {
+    return usage?.error === '401' ? '⚠️ Auth' : '...';
+  }
+  const h5 = Math.round(usage.fiveHour?.percent ?? 0);
+  const d7 = Math.round(usage.sevenDay?.percent ?? 0);
+  return `${h5}%|${d7}%`;
+}
+
+async function updateUsage() {
+  if (isPaused) return;
+  
+  const sessionKey = await getSessionKey();
+  if (!sessionKey) {
+    tray.setTitle(formatTitle({ error: '401' }));
+    return;
+  }
+  
+  const usage = await fetchUsage(sessionKey);
+  
+  if (usage.error === '401') {
+    await clearSessionKey();
+    clearCache();
+    tray.setTitle(formatTitle(usage));
+    stopPolling();
+    return;
+  }
+  
+  if (usage.error) {
+    retryCount = Math.min(retryCount + 1, BACKOFF_DELAYS.length - 1);
+    tray.setTitle(formatTitle(usage));
+    setTimeout(updateUsage, BACKOFF_DELAYS[retryCount]);
+    return;
+  }
+  
+  retryCount = 0;
+  tray.setTitle(formatTitle(usage));
+}
+
+function startPolling() {
+  if (pollingInterval) return;
+  isPaused = false;
+  updateUsage();
+  pollingInterval = setInterval(updateUsage, POLL_INTERVAL);
+}
+
+function stopPolling() {
+  if (pollingInterval) {
+    clearInterval(pollingInterval);
+    pollingInterval = null;
+  }
+}
+
+function createContextMenu() {
+  return Menu.buildFromTemplate([
+    {
+      label: 'Reauth',
+      click: async () => {
+        await clearSessionKey();
+        clearCache();
+        app.quit();
+      }
+    },
+    { type: 'separator' },
+    { label: 'Quit', click: () => app.quit() }
+  ]);
+}
+
+app.whenReady().then(() => {
+  // 1x1 transparent PNG to hide icon, show only title text
+  const emptyIcon = nativeImage.createFromDataURL('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==');
+  
+  tray = new Tray(emptyIcon);
+  tray.setTitle('...');
+  tray.setContextMenu(createContextMenu());
+  
+  powerMonitor.on('suspend', () => { isPaused = true; });
+  powerMonitor.on('resume', () => { isPaused = false; updateUsage(); });
+  
+  app.setLoginItemSettings({ openAtLogin: true, openAsHidden: true });
+  
+  startPolling();
+});
+
+app.on('window-all-closed', (e) => e.preventDefault());