CLI Pulse

Real-time usage, cost and quota tracking for AI coding tools — Claude Code, Codex, Gemini, Cursor, Copilot and 45 others — across a macOS menu bar app, iPhone, iPad, Apple Watch and Android, with a shared account so history follows you between devices.

This repository is PUBLIC, despite being named cli-pulse-private. Never commit a secret, credential, or internal document here. Internal material belongs in cli-pulse-internal. See AGENTS.md.

Site: https://cli-pulse.github.io/cli-pulse/ · Licence: closed-source, see LICENSE.md

Install

App Store — iPhone · iPad · Watch · Mac	search "CLI Pulse"
Homebrew (macOS)	see below
Developer ID DMG (macOS, notarized)	cli-pulse-distrib releases
Android	Google Play · or sideload the APK from releases
Windows · Linux	cli-pulse-desktop

brew tap cli-pulse/tap
brew trust cli-pulse/tap
brew install --cask cli-pulse

brew trust is not optional. Homebrew 6 refuses to load casks from a third-party tap until it is trusted, so without it the install stops silently after brew tap.

---

The rest of this file is for people working on the code.

This workspace contains the current CLI Pulse Bar app plus a small amount of legacy material kept for reference.

Platforms

CLI Pulse ships as one product across desktop, mobile, and wearable platforms, with a shared Supabase backend so usage history follows you between devices:

Platform	Source	Distribution
macOS · iOS · iPadOS · watchOS	this repo (CLI Pulse Bar/)	App Store
Android	this repo (android/)	Google Play
Windows · Linux	cli-pulse/cli-pulse-desktop (separate repo, Rust + Tauri 2)	GitHub Releases

The Windows / Linux build lives in its own repository because it shares no client code with the Apple/Android apps (Rust + Tauri vs Swift/Kotlin) and has a different CI matrix and release channel. Both desktop clients (macOS Swift and Windows/Linux Rust) implement the same on-device JSONL scanner with bit-exact parity, and every client authenticates against the same Supabase project.

🔒 Privacy

• Provider API keys & session cookies (OpenAI, Anthropic, Google, OpenRouter, ...) are stored only in macOS Keychain and never uploaded. They go directly from your device to the provider's own API.
• Session log contents under ~/.codex/sessions/ and ~/.claude/projects/ are scanned on-device via security-scoped bookmarks you grant in Settings. File contents never leave your Mac.
• Aggregated usage metrics (token counts, cost estimates, model names, dates) are synced to your CLI Pulse account so iPhone and Apple Watch show the same history. Linked to your user ID; no third-party analytics SDKs.
• Yield Score git tracking is opt-in. When on, only the commit hash, an HMAC of the project path, the commit timestamp, and a merge-commit flag upload. Messages, diffs, file paths, and author identity never upload.

Full data-by-data breakdown: PRIVACY.md.

Current Product Structure

• CLI Pulse Bar/
  • Current Xcode workspace and app targets for macOS, iOS, Watch, Widgets, and the shared CLIPulseCore package.
• helper/
  • Current helper CLI used for pairing, daemon sync, and local provider collection.
• backend/supabase/
  • Active SQL schema, migrations, and RPC definitions used by the app and helper when talking to Supabase.
• docs/
  • Published static site assets, including privacy.html, terms.html, and index.html, which are linked from the shipping app.

Current Development Commands

App

Open the current app workspace:

open "CLI Pulse Bar/CLI Pulse Bar.xcodeproj"

Helper

Run helper tests:

python3 -m pytest -q helper/test_system_collector.py

Inspect local collection output:

python3 helper/cli_pulse_helper.py inspect

Run one sync:

python3 helper/cli_pulse_helper.py sync

Shared Swift Package

Run the shared package tests:

swift test --package-path "CLI Pulse Bar/CLIPulseCore"

Android

Run Android unit tests (requires Java runtime):

cd android && ./gradlew testDebugUnitTest

Legacy or Reference Areas

• archive/
  • Archived drafts, old projects, and working notes that are no longer part of the active product path.
  • archive/backend-fastapi-legacy/ contains the older FastAPI runtime and its tests.

Notes

• If you are looking for the current shipping code, start in CLI Pulse Bar/.
• If you are looking for pairing or provider collection logic, start in helper/.
• If you are looking for the live backend contract, start in backend/supabase/.
• If you are preparing a release, read AGENTS.md and the appstore-submit skill. (RELEASE_WORKFLOW.md was referenced here for a long time and has never existed in this repo.)
• If you are starting a new task branch, read BRANCHING.md.
• If you are handing a new task to another AI, use TASK_START_PROMPT.md.
• If you are asking an AI to commit, merge, or decide whether public updates are needed, read MERGE_AND_PUBLISH_RULES.md.