Claude Code is signed in to one account at a time. If you have a team seat and a personal plan, that means /login round trips, and you only find out an account is spent when it stops you mid-task. ccs keeps every login in the macOS Keychain, reads each account's usage, and swaps the active login in a second.
At a glance
| |
|---|
| 🖥 Terminal | ccs lists every account with its limits; ccs use 2 switches. |
| 📊 Menu bar | The active account's 42% · 63% at all times. Click for usage cards with pace markers, a 24-hour history chart and a Switch button per account. |
| ⚡ Auto-switch | Checks every 2 minutes. At 90% it asks, at 95% it moves you to the least-used account. |
| 📱 Telegram | Usage and switching from your phone. While you're away from the Mac, Claude's permission prompts and questions come to the phone with buttons. |
| 🔔 Alerts | A report with screenshots and files when a task finishes, a forecast before a limit runs out, and a warning when usage rises while nothing on your Mac is using Claude. |
| 🔒 Careful with secrets | Tokens live only in the Keychain. .env files, keys and the folders you list never leave the Mac. |
| 🪶 Small | One Python file with no dependencies, one SwiftUI file, and tests that never touch your real login. |
How it works
flowchart LR
T["ccs in the terminal"] --> C{{"ccs"}}
M["CCS Usage<br/>menu bar app"] -->|"ccs json · ccs use N"| C
A["auto agent<br/>launchd, every 2 min"] -->|"ccs auto --once"| C
H["Claude Code hooks"] -->|"ccs hook"| C
C <-->|"swaps the login"| L[("Claude Code login<br/>Keychain + ~/.claude.json")]
C <-->|"one item per account"| K[("Keychain<br/>ccs-account")]
C -->|"reads usage"| U["Anthropic usage endpoint"]
C <-->|"long polling, no server"| B["Telegram bot"]
B <--> P(["your phone"])
ccs is the only program that touches the Claude Code login. The menu bar app, the auto agent, the hooks and the bot all go through it.
Install
You need macOS 14 or later, the Claude Code CLI (claude), the Xcode command line tools (swiftc, for the menu bar app), and /usr/local/bin/python3 (python.org Python 3.9+). Run these commands from this folder.
- Install the script:
mkdir -p ~/.local/bin && cp ccs ~/.local/bin/ccs && chmod +x ~/.local/bin/ccs
- Build the menu bar app (into
~/Applications/CCS Usage.app):
menubar/build.sh
- Start it now and at every login:
sed "s|__HOME__|$HOME|g" uz.ccs.menubar.plist > ~/Library/LaunchAgents/uz.ccs.menubar.plist && launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/uz.ccs.menubar.plist
- Turn on the auto agent:
sed "s|__HOME__|$HOME|g" uz.ccs.auto.plist > ~/Library/LaunchAgents/uz.ccs.auto.plist && launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/uz.ccs.auto.plist
- Start the Telegram bot (it waits quietly until you connect it, see Telegram):
sed "s|__HOME__|$HOME|g" uz.ccs.telegram.plist > ~/Library/LaunchAgents/uz.ccs.telegram.plist && launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/uz.ccs.telegram.plist
launchd doesn't expand ~, so the .plist files say __HOME__ and the sed in each command fills in your home folder.
Adding an account
- Run
ccs to save the current account.
- In
claude, run /login and sign in with the other account.
- Run
ccs again to add the new account to the list.
Important: always run ccs before /login. Claude Code renews its tokens from time to time, and if ccs holds an outdated copy, you'll have to log in to that account again. The agent also saves the current account every 2 minutes.
Commands
| Command | What it does |
|---|
ccs | lists accounts with 5h / 7d usage and time until each resets (● = active account) |
ccs use 2 or ccs use gmail | switches to account 2 (or the account whose email contains "gmail") |
ccs rm 2 | removes an account from the list and the Keychain (won't remove the active one) |
ccs auto --once | checks once (this is what the agent runs) |
ccs auto | keeps checking (in a terminal) |
ccs json | accounts and usage as JSON (what the menu bar app reads) |
ccs tg setup / ccs tg | connect the Telegram bot / run it (the LaunchAgent does this) |
ccs hook | the Claude Code hook behind the phone alerts |
What ccs looks like (● = active account, ↻ = time until that limit resets):
The colors are the same everywhere: green below 70%, orange from 70%, red from 90%.
Auto-switching
| Active account usage (5h or 7d) | What happens |
|---|
| under 90% | nothing |
| 90–95% | a dialog with Switch / Not now buttons appears |
| — you click Switch | switches right away and shows a notification |
| — no answer (closes after 100 s) | stays, and asks again at the next check |
| — you click Not now | doesn't ask again until that 5h window resets |
| 95% or more | switches without asking |
It only switches to an account that is under 90%, and picks the least-used one. If no account qualifies, it stays and writes that to the log.
Changing the thresholds: add the options to ProgramArguments in ~/Library/LaunchAgents/uz.ccs.auto.plist, for example <string>--ask</string><string>85</string>. Then reload the agent:
launchctl bootout gui/$(id -u)/uz.ccs.auto; launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/uz.ccs.auto.plist
To follow the log:
tail -f ~/.claude-accounts.log
Menu bar app
CCS Usage is a small native app (SwiftUI) whose look follows Claude-Usage-Tracker (MIT). Its data and its switching come from ccs (ccs json, ccs use N), so ccs stays the only program that touches the Claude Code login.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
