Push local coding-agent usage from ccusage to a personal Prometheus-compatible metrics endpoint every 12 hours using Raycast background refresh. Grafana Cloud can query it through a Prometheus data source.
Raycast background refresh is intentionally best-effort: macOS may delay a run, especially on battery. The first sync backfills every daily record available to ccusage. A local per-destination checkpoint makes later syncs incremental while still catching every day since the last successful push.
The extension runs ccusage daily --by-agent --json --offline and sends every numeric daily usage field returned by ccusage:
| Metric suffix | Meaning |
|---|---|
input_tokens |
Input tokens |
output_tokens |
Output tokens |
cache_creation_tokens |
Cache-creation input tokens |
cache_read_tokens |
Cache-read input tokens |
total_tokens |
Total tokens reported by ccusage |
cost_usd |
Calculated cost in US dollars |
Each suffix is exported as ccusage_daily_* for completed calendar days, timestamped at 00:00 UTC for the date reported by ccusage. The changing current day is deliberately excluded and appears as a completed historical day on the next sync after midnight.
Every family includes these dimensions:
agent="all", breakdown="total": total across all detected agents.agent="all", breakdown="model", model="…": total by model across agents.agent="codex|claude|…", breakdown="total": total for one agent.agent="codex|claude|…", breakdown="model", model="…": one agent and model.timezone: the timezone used for ccusage's calendar-day grouping.hostname: this Mac's hostname, or the configured device-name override.- Any optional static labels configured in Raycast, such as
machineorowner.
The checkpoint is advanced only after the Prometheus endpoint accepts the push. Because hostname is part of both the metric labels and checkpoint identity, every device performs its own full initial backfill and remains independently queryable.
Every successful attempt also writes:
ccusage_sync_timestamp_seconds: when the Prometheus endpoint accepted the latest sync.ccusage_sync_latest_completed_day_timestamp_seconds: newest completed usage day found locally.ccusage_sync_exported_samples: usage samples exported in that particular run.ccusage_sync_exported_days: completed days exported in that run.
Use the Prometheus remote-write endpoint for your deployment. Common compatible endpoint forms include:
- Single-node endpoint:
https://<host>/api/v1/write - Cluster:
https://<vminsert>/insert/<tenant>/prometheus/api/v1/write - Hosted services: use the remote-write URL shown with your access token.
The extension supports Bearer tokens and Basic authentication. Prefer HTTPS whenever credentials cross the network. In Grafana Cloud, configure the same endpoint as a Prometheus data source for querying.
Raycast does not support conditionally showing preferences based on the authentication dropdown. The first-run screen therefore shows both credential inputs. For Bearer authentication, leave Username (Basic Only) as not-used and enter the token in Bearer Token or Password. For Basic authentication, replace not-used with the username and enter the password.
Requirements for development: macOS, Raycast, and the current Node.js LTS release.
npm install
npm run devThe extension bundles ccusage 20.0.19's official open-source macOS executables for Apple Silicon and Intel. It selects the matching architecture at runtime and verifies both binaries against pinned SHA-256 checksums during development and production builds. The first time you invoke Sync CCUsage to Prometheus, Raycast asks for:
- Prometheus write URL
- Authentication method and credentials, if needed
- ccusage report timezone
- Optional device-name override; otherwise the hostname is detected automatically
- Optional static labels
Run the command once manually to backfill all available history and verify the configuration. After that, Raycast attempts an incremental sync every 12h. Change "interval": "12h" to "1d" in package.json if daily refresh is preferred.
Use Show Last CCUsage Sync in Raycast to see the last successful sync time, device, latest completed usage date, and exported sample count.
Open the Sync CCUsage to Prometheus command's Action Panel and activate background refresh. During development, use Run in Background to test the same launch path immediately. Raycast's Extension Diagnostics command shows the latest scheduled execution.
To verify that the endpoint accepted a recent push, query the latest sparse sync sample over a suitable lookback window:
time() - last_over_time(ccusage_sync_timestamp_seconds{hostname="$hostname"}[30d])
The result is the number of seconds since the latest successful sync. A direct instant query can appear empty after Prometheus's staleness window because sync-health metrics are emitted only when the command runs.
All processing happens locally. The extension reads the local coding-agent usage data supported by ccusage and sends the documented numeric metrics and configured labels only to the Prometheus remote-write endpoint you provide. It does not send prompts, responses, source code, file contents, or credentials as metrics, and it does not contact an extension-author-operated service.
Raycast stores password preferences in its encrypted local database. The configured credential is used only in the Authorization header sent to your endpoint and is never logged. Use HTTPS whenever the endpoint is not strictly local or otherwise protected by a trusted private network. Optional labels and the hostname are included in exported time-series labels, so avoid putting secrets into them.
The files in assets/ccusage-darwin-* come from the MIT-licensed @ccusage/ccusage-darwin-arm64 and @ccusage/ccusage-darwin-x64 packages at version 20.0.19. Their expected SHA-256 checksums are recorded in scripts/verify-ccusage-binaries.mjs. Update the version, both assets, and both checksums together. See THIRD_PARTY_NOTICES.md for attribution.
Completed daily cost across all agents:
ccusage_daily_cost_usd{agent="all", breakdown="total", hostname="$hostname"}
Completed daily cost by agent:
sum by (hostname, agent) (ccusage_daily_cost_usd{agent!="all", breakdown="total"})
Completed daily cost by model across all agents:
sum by (hostname, model) (ccusage_daily_cost_usd{agent="all", breakdown="model"})
Historical cache ratio by device:
ccusage_daily_cache_read_tokens{agent="all", breakdown="total"}
/
ccusage_daily_total_tokens{agent="all", breakdown="total"}
Last successful sync age in seconds:
time() - last_over_time(ccusage_sync_timestamp_seconds{hostname="$hostname"}[30d])
Newest completed usage day found on each device:
ccusage_sync_latest_completed_day_timestamp_seconds
npm run typecheck
npm test
npm run lint
npm run buildThe request uses Prometheus remote write v1 with protobuf encoding and Snappy compression. ccusage runs with --offline; the only background network request is the push to the configured Prometheus endpoint.