TickrMeter AI Usage CLI

Privacy-preserving personal subscription monitoring for Codex / ChatGPT and Claude Code.

Customer flow

1. Open AI Usage in TickrMeter and choose Connect personal usage.

2. Copy the one-time command shown by TickrMeter.

3. Run it on the computer where Codex or Claude Code is installed:

   npx @tickrmeter/ai-usage connect ABCD-927F

4. The helper detects the Codex desktop app, Codex CLI, and Claude Code, uploads normalized limit metadata, and installs a user-scoped five-minute sync using Task Scheduler, launchd, or a systemd user timer (cron fallback).

The initial npx command installs a fixed copy under ~/.tickrmeter-ai/app. Scheduled runs invoke that fixed version, never npx ...@latest. On Windows, a standard per-user Startup entry starts the installed Node CLI once at sign-in. The CLI launches one background agent that performs the five-minute sync without recurring console windows. The helper does not install or execute hidden VBS, WScript, or PowerShell wrappers.

Commands

tickrmeter-ai connect <pairing-code> [--server URL]
tickrmeter-ai sync
tickrmeter-ai status
tickrmeter-ai doctor
tickrmeter-ai disconnect

For an unpublished local build:

cd tickrmeter-ai-usage
npm install
npm run build
node dist/cli.js connect ABCD-927F --server https://develop.tickrmeter.io

TICKRMETER_API_URL may be used instead of --server. The production default is https://api.tickrmeter.io.

Codex

Codex must already be installed and signed in. On Windows, the helper automatically uses the signed-in Codex desktop app when available and falls back to an installed Codex CLI. It starts codex app-server, performs the JSON-RPC initialization handshake, calls account/read with token refresh disabled, calls account/rateLimits/read, and optionally calls account/usage/read. It terminates the child process after each sync.

The helper does not read ~/.codex/auth.json, browser cookies, OAuth tokens, or private ChatGPT endpoints. If setup is incomplete, tickrmeter-ai doctor directs the user to codex login; it never asks for a token.

Claude Code

Claude Code 2.1.80 or newer is required. Claude supplies structured rate_limits.five_hour and rate_limits.seven_day values to its configured status-line command. TickrMeter stores only those percentages, reset timestamps, and capturedAt in ~/.tickrmeter-ai/claude-usage.json.

If a status line already exists, its complete configuration is backed up locally and wrapped. The same input is passed to the existing command and its stdout/stderr are preserved. Disconnect restores the exact prior statusLine value. Prompts, conversations, transcript paths, project paths, cookies, and OAuth credentials are neither stored nor uploaded.

Claude data older than 60 minutes is marked stale. The helper does not send dummy prompts to refresh usage.

Local files

Files live under ~/.tickrmeter-ai/ with restrictive permissions where supported:

config.json            TickrMeter bridge ID/token and server
state.json             scheduler and reversible Claude wrapper state
claude-usage.json      normalized Claude rate-limit snapshot only
app/                   fixed installed CLI version

The bridge token is scoped to AI usage upload/status/disconnect. It is not a TickrMeter user session and cannot access provider credentials.

API usage

OpenAI and Anthropic organization API monitoring does not run in this CLI. Admin keys are entered directly in TickrMeter, encrypted by the backend, and used only for official provider usage/cost APIs. They are never returned to this helper.