CCS Bar for macOS
Relevant source files
The following files were used as context for generating this wiki page:
CCS Bar for macOS is a native SwiftUI menu bar application designed as a companion to the Claude Code Switch (CCS) ecosystem. It acts as a thin client for the CCS local web server, allowing users to monitor per-account quotas, costs, and tiers directly from the macOS menu bar. The application also provides account controls such as pausing/resuming accounts, setting defaults, and locking tiers without requiring the user to interact with the primary CLI or dashboard.
The system is designed with a "local-first" philosophy; the macOS application never communicates with AI providers directly. Instead, all requests are routed through the local CCS server at localhost, which performs provider-side fetches and refreshes data on a debounced schedule when the menu is opened.
Sources: macos-bar/README.md:3-8, src/commands/bar/install-subcommand.ts:13-18
Architecture and Components
The CCS Bar project is divided into logical modules that separate system logic from the user interface. It utilizes a Swift 5.9+ toolchain for the native component and TypeScript for the CLI-side installation and management logic.
Structural Overview
| Component | Responsibility |
|---|---|
| CCSBarCore | Pure Foundation logic: API client, discovery handshake, models, and formatting. |
| CCSBarApp | SwiftUI MenuBarExtra application containing ViewModels and Views. |
| CCSBarCheck | A runnable assertion harness used for logic testing without requiring full XCTest/Xcode. |
| CLI Management | TypeScript subcommands (install, launch, uninstall) within the main CCS CLI. |
Sources: macos-bar/README.md:11-15, src/commands/bar/install-subcommand.ts:50-84
Data Flow and Discovery
The application discovers the local CCS server by reading a configuration file located at ~/.ccs/bar.json. This file is written by the CLI during the ccs bar launch process and contains the necessary connection metadata.
The application supports authMode: "loopback" in its initial version, which facilitates secure local communication without full dashboard authentication.
Sources: macos-bar/README.md:24-30, src/commands/bar/launch-subcommand.ts:153-170
Lifecycle Management
The CCS CLI provides comprehensive lifecycle management for the macOS application, including installation, version pinning, and secure updates.
Installation Process
The installation is handled by ccs bar install. It follows a specific "stage-then-swap" pattern to ensure that existing installations are not corrupted by failed downloads.
Launch and Server Discovery
When the bar is launched, the CLI attempts to find a running CCS server before spawning a new one. It probes a set of candidate ports (3000, 3001, 3002, 8000, 8080) and validates them using an authentication handshake.
Security Implementation
Security is a primary concern given that the application handles sensitive quota and account data locally.
- Host Allowlist: The installer restricts downloads to
github.comandobjects.githubusercontent.com. - Integrity Verification: Every downloaded archive is verified against a SHA-256 digest before extraction.
- Zip-Slip Guard: The extraction process scans zip entries for path traversal components (e.g.,
..) and absolute paths to prevent unauthorized file writes. - Auth Proofs: Communication between the Bar app and the local server is secured via a loopback-gated handshake using
x-ccs-bar-tokenand nonce-based authentication proofs.
Sources: src/commands/bar/install-subcommand.ts:110-140, src/commands/bar/install-subcommand.ts:193-215, tests/unit/commands/bar-command.test.ts:1551-1580
Summary of CLI Commands
| Command | Description |
|---|---|
ccs bar install | Downloads and installs the native app to ~/Applications. |
ccs bar launch | Starts the local server and opens the macOS app. |
ccs bar uninstall | Removes the .app bundle and clears version pins. |
ccs bar version | Displays both the CLI version and the installed App version. |
ccs bar --help | Shows detailed usage information for bar subcommands. |
Sources: src/commands/bar/help-subcommand.ts:5-20, tests/unit/commands/bar-command.test.ts:100-130
The CCS Bar for macOS serves as a specialized monitoring tool that enhances the developer experience by providing ambient awareness of AI resource consumption. By leveraging native macOS capabilities and a secure local proxy architecture, it provides a performant and safe way to manage account profiles and usage metrics.