Claude Usage Notch

English | 中文

A tiny macOS menu-bar/notch app that shows your Claude usage right in the MacBook notch — so you don't have to open Settings → Usage every time.

It has four modes. A ⚙ settings button lets you choose which ones are active, and a ⇄ button cycles through just those:

1. Subscription quota (default) — your Claude plan usage: 5-hour session % + weekly %, from the same endpoint the Claude desktop app uses.
2. Claude Code tokens — local token usage of the Claude Code CLI, read straight from ~/.claude/projects/**/*.jsonl (no credentials, no network). Pick a model in the card (e.g. glm-5, opus-4-8, or all) and a time window (today or the current 5-hour block); the pill then shows that model's tokens, like glm-5 116k.
3. Codex — your Codex plan usage: 5-hour % + weekly %, read from Codex's local rollout files (~/.codex/sessions/**/rollout-*.jsonl, no credentials, no network). Codex's own TUI shows this as remaining, but the files store used_percent, so it's displayed used-style to match Claude (green/yellow/red + reset times).
4. DeepSeek — your DeepSeek API balance (live, in RMB) and per-model token usage from local transcripts. The pill defaults to showing your current balance (deepseek ¥46.43); you can toggle it to show token counts instead. Balance comes from GET /user/balance, tokens are scanned from ~/.claude/projects/**/*.jsonl (filtered to DeepSeek models: deepseek-v4-pro, etc.). No pricing/currency computation — just the real balance from DeepSeek's API and raw token counts.

Why four modes? The Claude/Codex plan quotas only exist if you're signed into those subscriptions. Claude Code can also run against a proxy or an API key, where there is no subscription quota — but it still logs every message's token count locally, so the token mode works regardless of backend (similar to the ccusage tool). The DeepSeek mode is for users who run DeepSeek models through Claude Code and want to keep an eye on their API balance without opening platform.deepseek.com. You can enable only the modes you actually use via the ⚙ settings button — the ⇄ toggle then cycles through only those.

• Compact: a small pill to the left of the notch shows the current mode's headline number (74% in quota mode, glm-5 116k in token mode, 3% in Codex mode, deepseek ¥46.43 in DeepSeek mode).
• Hover: it expands into a card with the details, a ⚙ settings button, a ⇄ mode toggle, a refresh button, and a ✕ quit button.
• Move away: it collapses back to the pill.

Data is live (auto-refresh every 60s). Quota mode reuses the desktop app's session; token mode just re-reads the local transcripts; DeepSeek mode calls the balance API and scans local transcripts for DeepSeek model entries.

Requirements

• A notched MacBook (uses the notch geometry; on notchless Macs the pill just sits top-left).
• For quota mode: the Claude desktop app installed and logged in (the tool reuses its session). Token mode needs only the Claude Code CLI's local transcripts.
• Swift toolchain — the Xcode Command Line Tools are enough (xcode-select --install). Full Xcode is not required.

How it works

Subscription quota mode

There's no public usage API, so the app reads the value the Claude desktop app already fetches:

1. It decrypts the claude.ai session cookie stored locally by the Claude app (~/Library/Application Support/Claude/Cookies, Chromium AES-128-CBC, key from the Claude Safe Storage Keychain item — this triggers one macOS Keychain prompt).
2. It calls GET https://claude.ai/api/organizations/{id}/usage and reads five_hour.utilization / seven_day.utilization.

The session key and org id are cached in memory, so the Keychain is read at most once per launch.

Claude Code token mode

No credentials and no network at all. Claude Code logs every assistant message's token usage (input / output / cache) with a timestamp and model name into JSONL transcripts under ~/.claude/projects/. This holds for proxy/API models too — e.g. glm-5 responses record real usage. The app:

1. Scans the transcript files (only those recent enough to matter).
2. Sums input + output + cache_creation tokens per model, also grouping them into rolling 5-hour blocks (a new block starts past start + 5h or after a ≥5h gap — the same idea as ccusage).
3. Lets you pick which model (or all) and which window (today / current 5-hour block) to watch; the pill and card update to that choice.

This is keyed to the local logs, so it reflects whatever Claude Code actually ran — even against a third-party proxy or a direct API key, where no plan quota exists.

Note: Claude Code's ~/.claude/telemetry/1p_failed_events.*.json files are just failed-to-upload internal events — they carry no token or cost data, so they aren't used.

Codex mode

No credentials and no network. Codex appends a token_count event to each rollout file (~/.codex/sessions/**/rollout-*.jsonl) whose rate_limits block carries two windows:

• primary — window_minutes: 300 (5-hour), with used_percent and resets_at
• secondary — window_minutes: 10080 (weekly)

Rate limits are account-global, so the app reads the last rate_limits line from the most recently written rollout. The files record used_percent directly (even though Codex's TUI phrases it as "remaining"), so it's shown used-style — the exact same UsageRow UI as the Claude subscription mode.

DeepSeek mode

No official usage/cost API exists (the /v1/usage endpoint is not publicly available), so this mode takes a dual approach:

1. Balance: calls GET https://api.deepseek.com/user/balance with your API key — the same data shown on platform.deepseek.com. Displayed in RMB (¥).
2. Token usage: scans ~/.claude/projects/**/*.jsonl for assistant messages whose model name contains "deepseek" (e.g. deepseek-v4-pro). Per-model token counts are shown with model selection and today/5h toggle, exactly like the Claude Code token mode.

The pill defaults to showing your balance. Use the 余额/用量 toggle in the card to switch between balance and token display.

Configuring the API key

DeepSeek mode needs your DeepSeek API key. Create ~/.deepseek/config.json:

{"api_key":"sk-your-key-here"}

Set permissions so only you can read it:

chmod 600 ~/.deepseek/config.json

If the file is missing, the app falls back to the DEEPSEEK_API_KEY environment variable. Without a key the balance section will show zero, but token usage from local transcripts still works.

The config file lives in your home directory, outside this repository. Your API key will never be committed.

Why are the token counts so large?

Token totals are much bigger than "how many questions you asked", and that's expected:

• One question ≠ one API call. Claude Code is agentic: it reads files, runs tools, reads the results, and calls the model again — each step is a full API call.
• Every call re-sends the whole context. LLMs are stateless, so each request ships the entire system prompt + tool definitions + CLAUDE.md + open file contents + conversation history. The input dwarfs the output.
• Input ≫ output. In a real sample, 2 questions became 4 API calls totalling ~116k tokens — of which 115,462 were input and only 581 were output.

So the token number is a faithful, slightly conservative measure of total tokens processed (cache reads are excluded so the headline isn't inflated).

Privacy: everything stays on your machine. Your cookie/token is never written to disk or sent anywhere except claude.ai (your own session). Nothing sensitive is stored in this repo.

Build & run

The build is plain Swift Package Manager plus a script that assembles the .app bundle.

1. (Recommended) Create a stable self-signed signing cert

Signing with a stable identity means the Keychain "Always Allow" sticks across rebuilds, so you're prompted only once, ever. Skip this and it still works, but ad-hoc rebuilds re-prompt.

In Keychain Access → Certificate Assistant → Create a Certificate…:

• Name: ClaudeUsageNotch
• Identity Type: Self-Signed Root
• Certificate Type: Code Signing

2. Build the app

# with the stable cert:
CODESIGN_IDENTITY=ClaudeUsageNotch ./scripts/build_app.sh release

# or ad-hoc (no cert):
./scripts/build_app.sh release

This produces build/ClaudeUsageNotch.app. Copy it wherever you like and run it:

cp -R build/ClaudeUsageNotch.app ~/Desktop/     # cp -R preserves the signature
open ~/Desktop/ClaudeUsageNotch.app

On first launch, click Always Allow on the Claude Safe Storage Keychain prompt (quota mode only).

Regenerating the icon (optional)

swift scripts/generate_icon.swift Resources/AppIcon.iconset
iconutil -c icns Resources/AppIcon.iconset -o Resources/AppIcon.icns

Usage

• Open: double-click ClaudeUsageNotch.app. It starts in subscription quota mode.
• See details: hover the pill.
• Choose which modes are active: the ⚙ settings button opens a checklist of the four modes. Tick the ones you want; the ⇄ toggle then cycles through only those (one ticked = no cycling). Your choice is remembered across launches.
• Switch mode: the ⇄ button cycles through the enabled modes.
• Pick a model (token / DeepSeek mode): tap a model in the card list (or all); the pill then shows that model, e.g. glm-5 116k or deepseek-v4-pro 204k.
• Pick a window (token / DeepSeek mode): the 今日 / 5 小时 toggle switches between today's total and the current 5-hour block.
• Toggle pill display (DeepSeek mode): use the 余额 / 用量 switch to show balance or token counts in the pill.
• Refresh: the 🔄 button (or wait for the 60s auto-refresh).
• Quit: the ✕ button.

Project layout

Package.swift                         SwiftPM manifest (no external deps)
Sources/ClaudeUsageNotch/
  main.swift / AppDelegate.swift      app entry (LSUIElement background agent)
  NotchController.swift               the notch NSPanel + hover handling + mode state
  Views.swift                         SwiftUI pill + expanded card (all four modes + settings)
  NotchGeometry.swift                 notch size / position helpers
  UsageStore.swift                    subscription state + 60s auto-refresh
  UsageProvider.swift                 org discovery + usage fetch + session cache
  CookieStore.swift                   reads & decrypts the Claude session cookie
  TokenUsageStore.swift               Claude Code token mode (reads ~/.claude transcripts)
  CodexStore.swift                    Codex mode (reads ~/.codex rollout rate limits)
  DeepSeekStore.swift                 DeepSeek mode (balance API + transcript token scan)
  Log.swift                           ~/Library/Logs/ClaudeUsageNotch.log
Resources/Info.plist, AppIcon.icns
scripts/build_app.sh                  assembles the .app bundle
scripts/generate_icon.swift           generates the app icon

Notes / limitations

• Unofficial: quota mode depends on the Claude desktop app's local cookie store and an internal endpoint; token mode depends on Claude Code's transcript format. Both could change.
• Logs (no secrets) go to ~/Library/Logs/ClaudeUsageNotch.log for debugging.

---

中文

English | 中文

一个极小的 macOS 菜单栏/刘海屏小工具，把你的 Claude 用量直接显示在 MacBook 刘海旁边 ——不用每次都点开 设置 → Usage。

它有四种模式。用 ⚙ 设置按钮勾选启用哪几种，⇄ 按钮只在启用的模式间循环切换：

1. 订阅配额（默认）—— 你的 Claude 套餐用量：5 小时会话 % + 本周 %，数据来自 Claude 桌面端用的同一个接口。
2. Claude Code token —— Claude Code 命令行的本地 token 用量，直接读 ~/.claude/projects/**/*.jsonl（不需要任何密钥、不联网）。可以在卡片里选模型 （如 glm-5、opus-4-8，或全部）以及时间窗口（今日 或当前 5 小时块）， 刘海上就显示该模型对应的 token，比如 glm-5 116k。
3. Codex —— 你的 Codex 套餐用量：5 小时 % + 本周 %，读自 Codex 本地 rollout 文件 （~/.codex/sessions/**/rollout-*.jsonl，不需要密钥、不联网）。Codex 自己的界面显示的是 剩余用量，但文件里存的是 used_percent，所以这里统一成 Claude 的已用量风格显示 （绿/黄/红 + 重置时间）。
4. DeepSeek —— DeepSeek API 余额（实时人民币）和按模型的 token 用量。 刘海默认显示余额（deepseek ¥46.43），可切换为显示 token 数。余额来自 GET /user/balance 接口，token 从 ~/.claude/projects/**/*.jsonl 扫描 （筛选含 "deepseek" 的模型，如 deepseek-v4-pro）。不自己做金额换算—— 只展示 DeepSeek API 返回的真实余额和本地原始 token 数。

为什么要四种模式？只有登录了 Claude / Codex 订阅才有对应的"套餐配额"。而 Claude Code 还可能 走代理或自带 API key，这种情况下根本没有订阅配额——但它仍会把每条消息的 token 记在本地， 所以 token 模式不管后端是什么都能用（思路和 ccusage 一样）。DeepSeek 模式面向通过 Claude Code 使用 DeepSeek 模型的用户，不用每次都打开 platform.deepseek.com 看余额。你可以用 ⚙ 设置按钮只启用自己实际在用的模式，⇄ 就只在这几种之间循环。

• 常态：刘海左侧一个小药丸，显示当前模式的主数字（配额模式 74%，token 模式 glm-5 116k，Codex 模式 3%，DeepSeek 模式 deepseek ¥46.43）。
• 悬停：展开成卡片，含详情、⚙ 设置、⇄ 模式切换、刷新、✕ 退出。
• 移开：收回成药丸。

数据是实时的（每 60 秒自动刷新）。配额模式复用桌面端登录态；token 模式只是重新读本地记录； DeepSeek 模式调用余额 API + 扫描本地 transcript 中 DeepSeek 模型的记录。

环境要求

• 带刘海的 MacBook（用到刘海几何信息；无刘海的 Mac 上药丸就贴在左上角）。
• 配额模式需要安装并登录 Claude 桌面端（复用它的会话）；token 模式只需要 Claude Code 命令行的本地记录。
• Swift 工具链 —— 装 Xcode 的 Command Line Tools 就够了（xcode-select --install）， 不需要完整 Xcode。

工作原理

订阅配额模式

没有公开的用量 API，所以直接读 Claude 桌面端已经拉取的值：

1. 解密 Claude 桌面端本地存的 claude.ai 会话 cookie （~/Library/Application Support/Claude/Cookies，Chromium AES-128-CBC，密钥取自 Claude Safe Storage 钥匙串项——会触发一次 macOS 钥匙串授权）。
2. 调用 GET https://claude.ai/api/organizations/{id}/usage，读取 five_hour.utilization / seven_day.utilization。

会话 key 和 org id 会缓存在内存里，所以每次启动最多读一次钥匙串。

Claude Code token 模式

完全不需要密钥、不联网。Claude Code 会把每条 assistant 消息的 token usage （输入/输出/缓存）连同时间戳和模型名写进 ~/.claude/projects/ 下的 JSONL 记录里。 代理/API 模型也一样——比如 glm-5 的响应里就有真实 usage。本工具：

1. 扫描这些记录文件（只读近期可能相关的）。
2. 按模型累加 输入 + 输出 + cache_creation，并按滚动的 5 小时块归集 （超过 起点+5h 或间隔 ≥5h 就开新块——和 ccusage 思路一致）。
3. 让你选看哪个模型（或全部）以及哪个窗口（今日 / 当前 5 小时块），刘海和卡片都随选择更新。

它只认本地记录，所以反映的就是 Claude Code 实际跑了什么——哪怕是第三方代理或自带 API key、 压根没有套餐配额的情况。

注：Claude Code 的 ~/.claude/telemetry/1p_failed_events.*.json 只是上传失败的内部事件， 不含任何 token 或费用数据，因此没有使用它。

Codex 模式

不需要密钥、不联网。Codex 每一轮都会往 rollout 文件 （~/.codex/sessions/**/rollout-*.jsonl）追加一个 token_count 事件，其中的 rate_limits 带两个窗口：

• primary —— window_minutes: 300（5 小时），含 used_percent 和 resets_at
• secondary —— window_minutes: 10080（每周）

用量是账号全局的，所以本工具读取最近写入的 rollout 里最后一条 rate_limits。文件里 直接存的就是 used_percent（尽管 Codex 界面把它说成"剩余"），因此以已用量风格显示—— 和 Claude 订阅配额模式用的是同一套 UsageRow 界面。

DeepSeek 模式

DeepSeek 官方没有公开的用量/消费 API（/v1/usage 端点不存在），因此本模式采用双数据源：

1. 余额：调用 GET https://api.deepseek.com/user/balance（需要 API key）， 展示和 platform.deepseek.com 一致的余额数据（人民币）。
2. Token 用量：扫描 ~/.claude/projects/**/*.jsonl，筛选模型名包含 "deepseek" 的 assistant 消息（如 deepseek-v4-pro），按模型汇总 token 数。支持模型选择 和今日/5 小时窗口切换，体验和 Claude Code token 模式一致。

刘海默认显示余额。在卡片中使用 余额 / 用量 切换来改变刘海显示内容。

配置 API Key

DeepSeek 模式需要 DeepSeek API key。 创建 ~/.deepseek/config.json：

{"api_key":"sk-你的密钥"}

设置权限：

chmod 600 ~/.deepseek/config.json

配置文件在用户主目录下，不在本仓库内，API key 不会被提交。如果文件不存在， 会回退到 DEEPSEEK_API_KEY 环境变量。没有 key 时余额显示为 0，但本地 token 统计仍可正常使用。

为什么 token 数看起来这么多？

token 总量会远大于"你问了几个问题"，这是正常的：

• 一个问题 ≠ 一次 API 调用。 Claude Code 是 agent：读文件、跑工具、看结果、再请求模型 ——每一步都是一次完整的 API 调用。
• 每次调用都要把整段上下文重发一遍。 大模型是无状态的，每次请求都得带上完整的系统提示词
  • 工具定义 + CLAUDE.md + 打开过的文件内容 + 全部对话历史。输入远大于输出。
• 输入 ≫ 输出。 真实样本里，2 个问题变成 4 次 API 调用、共约 11.6 万 token——其中 输入 115,462，输出仅 581。

所以这个 token 数是对"处理总量"忠实、且偏保守的度量（缓存读取没算进去，避免数字虚高）。

隐私：一切都在你本机。你的 cookie/token 不会写入磁盘，也不会发往 claude.ai （你自己的会话）以外的任何地方。本仓库不含任何敏感信息。

构建与运行

构建就是普通的 Swift Package Manager，加一个把 .app 打包好的脚本。

1.（推荐）创建一个稳定的自签名签名证书

用稳定身份签名，钥匙串的"始终允许"就能跨重新构建保持有效，从而永远只提示一次。 跳过也能用，但临时（ad-hoc）签名每次重建都会重新提示。

在 钥匙串访问 → 证书助理 → 创建证书…：

• 名称：ClaudeUsageNotch
• 身份类型：自签名根证书（Self-Signed Root）
• 证书类型：代码签名（Code Signing）

2. 构建

# 用稳定证书：
CODESIGN_IDENTITY=ClaudeUsageNotch ./scripts/build_app.sh release

# 或临时签名（无证书）：
./scripts/build_app.sh release

会生成 build/ClaudeUsageNotch.app。复制到任意位置运行：

cp -R build/ClaudeUsageNotch.app ~/Desktop/     # cp -R 会保留签名
open ~/Desktop/ClaudeUsageNotch.app

首次启动时，在 Claude Safe Storage 钥匙串提示上点始终允许（仅配额模式需要）。

重新生成图标（可选）

swift scripts/generate_icon.swift Resources/AppIcon.iconset
iconutil -c icns Resources/AppIcon.iconset -o Resources/AppIcon.icns

使用

• 打开：双击 ClaudeUsageNotch.app，默认进入订阅配额模式。
• 看详情：鼠标悬停到药丸上。
• 选择启用哪些模式：⚙ 设置按钮打开四种模式的勾选列表。勾选你要的，⇄ 就只在这几种之间 循环（只勾一个就不循环）。选择会跨启动记住。
• 切换模式：⇄ 按钮在已启用的模式之间循环切换。
• 选模型（token / DeepSeek 模式）：在卡片列表里点某个模型（或全部），药丸随即显示该 模型，比如 glm-5 116k 或 deepseek-v4-pro 204k。
• 选窗口（token / DeepSeek 模式）：用 今日 / 5 小时 切换条在"今日总量"和 "当前 5 小时块"之间切换。
• 切换刘海显示（DeepSeek 模式）：用 余额 / 用量 切换刘海显示余额还是 token 数。
• 刷新：🔄 按钮（或等 60 秒自动刷新）。
• 退出：✕ 按钮。

目录结构

Package.swift                         SwiftPM 清单（无外部依赖）
Sources/ClaudeUsageNotch/
  main.swift / AppDelegate.swift      程序入口（LSUIElement 后台 agent）
  NotchController.swift               刘海 NSPanel + 悬停处理 + 模式状态
  Views.swift                         SwiftUI 药丸 + 展开卡片（四种模式 + 设置）
  NotchGeometry.swift                 刘海尺寸/位置辅助
  UsageStore.swift                    订阅状态 + 60 秒自动刷新
  UsageProvider.swift                 org 发现 + 用量拉取 + 会话缓存
  CookieStore.swift                   读取并解密 Claude 会话 cookie
  TokenUsageStore.swift               Claude Code token 模式（读 ~/.claude 记录）
  CodexStore.swift                    Codex 模式（读 ~/.codex rollout 用量）
  DeepSeekStore.swift                 DeepSeek 模式（余额 API + transcript token 扫描）
  Log.swift                           ~/Library/Logs/ClaudeUsageNotch.log
Resources/Info.plist, AppIcon.icns
scripts/build_app.sh                  打包 .app
scripts/generate_icon.swift           生成应用图标

说明 / 局限

• 非官方：配额模式依赖 Claude 桌面端的本地 cookie 和一个内部接口；token 模式依赖 Claude Code 的记录格式。两者都可能变动。
• 日志（不含任何密钥）写在 ~/Library/Logs/ClaudeUsageNotch.log 便于排查。