rename usag → usage and add v0.1.x → v0.2.0 migration (v0.2.0)

The app has always been called "usage" publicly, but every internal
identifier — bundle id, filenames, launchctl label, ~/.claude/ paths —
spelled it "usag" (missing the trailing e). This unifies all of those
on "usage" and adds automatic migration so v0.1.x installs upgrade
cleanly:

- setup_hook clears legacy ~/.claude/usag-statusline.py and
  usag-status.json, moves the "usag" backup key under settings to
  "usage", and removes a statusLine command still pointing at the old
  hook.
- install-launchagent / uninstall-launchagent bootout the old
  com.lollapalooza.usag label and delete its plist before installing
  the new one.
- usage_client reads usage-status.json first, falls back to the legacy
  usag-status.json, then tt-status.json, so users running the new app
  before Claude Code refreshes still see numbers.

Bumps to v0.2.0 as a breaking change. Users who only download the
.app will hit the in-app "立即安裝 hook" button on first launch and
not notice anything.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: aqua5230

.github/workflows/release.yml

@@ -48,10 +48,10 @@ jobs:
 
       - name: Zip .app
         run: |
-          if [[ -d dist/main.app && ! -d dist/usag.app ]]; then
-            mv dist/main.app dist/usag.app
+          if [[ -d dist/main.app && ! -d dist/usage.app ]]; then
+            mv dist/main.app dist/usage.app
           fi
-          cd dist && zip -r usag.app.zip usag.app
+          cd dist && zip -r usage.app.zip usage.app
 
       - name: Ensure release exists
         env:
@@ -68,4 +68,4 @@ jobs:
       - name: Upload to release
         env:
           GH_TOKEN: ${{ github.token }}
-        run: gh release upload "${{ steps.ref.outputs.tag }}" dist/usag.app.zip --clobber
+        run: gh release upload "${{ steps.ref.outputs.tag }}" dist/usage.app.zip --clobber

.gitignore

@@ -5,8 +5,8 @@ __pycache__/
 .claude/settings.local.json
 *.log
 pricing_cache.json
-usag.log
-usag.err.log
+usage.log
+usage.err.log
 .DS_Store
 build/
 dist/

CHANGELOG.en.md

@@ -5,6 +5,19 @@
 All notable changes to usage are documented here.
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## 0.2.0 — 2026-05-18
+
+### Breaking Changes
+- Internal app identifiers changed from `usag` to `usage`: bundle id, filenames, launchctl label, and `~/.claude/` paths were renamed.
+
+### Added
+- `setup_hook.py` now detects and clears old v0.1.x `usag` leftovers: hook script, settings statusLine, backup key, and status file.
+- `install-launchagent.sh` / `uninstall-launchagent.sh` now clean the old LaunchAgent plist and label automatically.
+- `usage_client.py` now falls back to the old `usag-status.json` path for upgrade compatibility.
+
+### Fixed
+- Public app naming and internal bundle identifiers are now consistently `usage`.
+
 ## 0.1.11 — 2026-05-18
 
 ### Fixed

CHANGELOG.md

@@ -4,6 +4,19 @@
 
 本檔記錄 usage 所有重要變更。格式參考 [Keep a Changelog](https://keepachangelog.com/)。
 
+## 0.2.0 — 2026-05-18
+
+### 破壞性變更
+- app 內部識別從 `usag` 改成 `usage`：bundle id、檔名、launchctl label、`~/.claude/` 路徑全數改名。
+
+### 新增
+- `setup_hook.py` 自動偵測並清除舊 v0.1.x `usag` 殘留：hook 腳本、settings 內 statusLine、備份 key 與 status 檔。
+- `install-launchagent.sh` / `uninstall-launchagent.sh` 會自動清掉舊 LaunchAgent plist 與 label。
+- `usage_client.py` 讀檔加入舊 `usag-status.json` fallback，提供升級過渡相容。
+
+### 修正
+- app 對外名稱與內部 bundle 識別統一為 `usage`。
+
 ## 0.1.11 — 2026-05-18
 
 ### 修正

CONTRIBUTING.en.md

@@ -23,7 +23,7 @@ All three must be green to merge. CI runs the same three (`.github/workflows/che
 ## Code change guidelines
 
 - **When changing prod modules, add tests alongside.** Pick the closest existing file under `tests/` as a style reference. Tests must never touch real `~/.claude/` or `~/.codex/` — use `monkeypatch` to redirect path constants.
-- **Do not rename the technical short name `usag`.** All file paths, settings keys, binary names, environment variables, and the LaunchAgent label keep the `usag` prefix (it is a hook contract; renaming would break existing installs). The public-facing name is `usage`.
+- **Keep internal and public naming unified as `usage`.** File paths, settings keys, binary names, environment variables, and the LaunchAgent label all use the `usage` prefix.
 - **Be deliberate with `menubar.py` UI constants** (`CARD_HEIGHT`, `CARD_RADIUS`, `SECTION_GAP`, etc.); they are part of the popover's visual design.
 
 ## CHANGELOG and releases

CONTRIBUTING.md

@@ -23,7 +23,7 @@ uv run pytest -v
 ## 改 code 的方針
 
 - **改 prod 模組請順手補測試**：`tests/` 底下挑風格最接近的檔案模仿。新增測試禁止碰 `~/.claude/` 跟 `~/.codex/` 真實檔案，請用 `monkeypatch` 改路徑常數。
-- **不要改技術短名 `usag`**：所有檔案路徑、設定 key、binary、env var、LaunchAgent label 都保留 `usag` 前綴（hook contract，改了會打到已安裝的使用者）。對外名稱用 `usage`。
+- **內外名稱統一為 `usage`**：檔案路徑、設定 key、binary、env var、LaunchAgent label 都使用 `usage` 前綴。
 - **menubar.py 的 UI 常數**（`CARD_HEIGHT`、`CARD_RADIUS`、`SECTION_GAP` 等）動之前先想清楚，那是 popover 視覺設計的一部分。
 
 ## CHANGELOG 與發版

README.en.md

@@ -26,15 +26,15 @@ usage installs a small **statusLine hook** — a script that Claude Code automat
 
 1. Claude Code refreshes the status line and packages usage info (5-hour percentage, 7-day percentage, etc.) as JSON.
 2. It pipes that JSON to the hook via stdin.
-3. The hook writes the JSON to `~/.claude/usag-status.json`.
+3. The hook writes the JSON to `~/.claude/usage-status.json`.
 4. The usage UI reads that file.
 
 Since both sides look at the same source data, **the numbers match exactly what Claude Code itself shows**.
 
 ```mermaid
 flowchart LR
-    A[Claude Code main process] -->|pipes JSON to stdin<br/>on every statusLine refresh| B[usag-statusline.py<br/>hook script]
-    B -->|writes| C[(~/.claude/<br/>usag-status.json)]
+    A[Claude Code main process] -->|pipes JSON to stdin<br/>on every statusLine refresh| B[usage-statusline.py<br/>hook script]
+    B -->|writes| C[(~/.claude/<br/>usage-status.json)]
     D[usage menu bar / TUI] -->|reads| C
     D -->|renders| E[macOS menu bar]
     F((Anthropic API)) -.x.- D
@@ -43,7 +43,7 @@ flowchart LR
 
 Read priority:
 
-1. `~/.claude/usag-status.json` — written by the hook usage installs.
+1. `~/.claude/usage-status.json` — written by the hook usage installs.
 2. `~/.claude/tt-status.json` — fallback. If you also use [token-tracker](https://github.com/stormzhang/token-tracker), usage will share its status file.
 
 ### Codex usage
@@ -68,16 +68,16 @@ If Codex isn't installed or the directory doesn't exist, that part of the UI hid
 
 ## Download the app
 
-Go to the [GitHub Releases page](https://github.com/aqua5230/usage/releases/latest) and download the latest `usag.app.zip`. Unzip it and move `usag.app` wherever you like (e.g. `/Applications`).
+Go to the [GitHub Releases page](https://github.com/aqua5230/usage/releases/latest) and download the latest `usage.app.zip`. Unzip it and move `usage.app` wherever you like (e.g. `/Applications`).
 
 ⚠️ Because this app is not signed with an Apple Developer certificate, **macOS Gatekeeper will block the first launch**.
-To open it: find `usag.app` in Finder → right-click → Open → confirm Open. After that, double-clicking works normally.
+To open it: find `usage.app` in Finder → right-click → Open → confirm Open. After that, double-clicking works normally.
 
 ### First launch: install the hook
 
-The first time you open usag, if Claude Code has never been wired up yet, the popover will detect the missing status file and **show an extra "立即安裝 hook" (Install hook now) button at the bottom**. Click it once — it installs the hook for you. Then **fully quit Claude Code (Cmd+Q) and re-open it**, click "Refresh now" in usag, and the numbers will appear.
+The first time you open usage, if Claude Code has never been wired up yet, the popover will detect the missing status file and **show an extra "立即安裝 hook" (Install hook now) button at the bottom**. Click it once — it installs the hook for you. Then **fully quit Claude Code (Cmd+Q) and re-open it**, click "Refresh now" in usage, and the numbers will appear.
 
-If the button doesn't show, usag is already reading data (e.g. you previously installed [token-tracker](https://github.com/stormzhang/token-tracker) and its status file works as a fallback) — nothing else to do.
+If the button doesn't show, usage is already reading data (e.g. you previously installed [token-tracker](https://github.com/stormzhang/token-tracker) and its status file works as a fallback) — nothing else to do.
 
 > **Fallback: install via curl**
 > If the in-app button doesn't work or you prefer the command line, paste this in Terminal:
@@ -107,7 +107,7 @@ This creates an isolated Python environment (`.venv`) for the project, activates
 
 ## First install (wire up the Claude Code hook — source mode only)
 
-> Using the .app? Just click the "立即安裝 hook" button in the popover on first launch instead — you don't need this section. The steps below are for developers running usag from source.
+> Using the .app? Just click the "立即安裝 hook" button in the popover on first launch instead — you don't need this section. The steps below are for developers running usage from source.
 
 This single command does two things: copies the hook script into `~/.claude/`, and updates your Claude Code settings to point at it.
 
@@ -120,17 +120,17 @@ python3 main.py --setup
 
 What `--setup` does in detail:
 
-- Copies `usag_statusline.py` to `~/.claude/usag-statusline.py`.
+- Copies `usage_statusline.py` to `~/.claude/usage-statusline.py`.
 - Points `statusLine` in `~/.claude/settings.json` at that hook.
-- If you already had a custom `statusLine`, it is backed up to `settings.usag.previousStatusLine` so nothing is overwritten.
+- If you already had a custom `statusLine`, it is backed up to `settings.usage.previousStatusLine` so nothing is overwritten.
 
 To uninstall:
 
 ```bash
 python3 main.py --unsetup
 ```
 
-`--unsetup` restores your original statusLine and removes the hook and `~/.claude/usag-status.json`.
+`--unsetup` restores your original statusLine and removes the hook and `~/.claude/usage-status.json`.
 
 ## Run modes
 
@@ -180,12 +180,12 @@ A LaunchAgent (the macOS service that handles "what should start when this user
 
 2. **Manual start (for testing):**
    ```bash
-   launchctl start com.lollapalooza.usag
+   launchctl start com.lollapalooza.usage
    ```
 
 3. **Logs:**
-   - stdout: `~/Library/Logs/usag/usag.log`
-   - stderr: `~/Library/Logs/usag/usag.err.log`
+   - stdout: `~/Library/Logs/usage/usage.log`
+   - stderr: `~/Library/Logs/usage/usage.err.log`
 
 4. **Uninstall:**
    ```bash
@@ -222,7 +222,7 @@ USAG_DEBUG=1 python3 main.py
 
 ## Behaviour notes
 
-- usage only reads `~/.claude/usag-status.json`, `~/.claude/tt-status.json`, and Codex's session files. It does not call the Anthropic / OpenAI API and does not read the Keychain. The only network activity is a one-time download of the LiteLLM pricing table for Codex cost estimates (cached for 7 days; offline fallback available).
+- usage only reads `~/.claude/usage-status.json`, `~/.claude/tt-status.json`, and Codex's session files. It does not call the Anthropic / OpenAI API and does not read the Keychain. The only network activity is a one-time download of the LiteLLM pricing table for Codex cost estimates (cached for 7 days; offline fallback available).
 - When Claude Code isn't running, the status file isn't updated — but actual usage isn't changing either (until reset time), so the displayed value is still accurate. After reset time passes, it auto-resets to zero.
 - If the status file hasn't been updated for more than 6 hours, the status line notes "status file is N minutes stale, numbers may be out of date."
 
@@ -234,7 +234,7 @@ USAG_DEBUG=1 python3 main.py
 | Status says "N minutes stale" | Claude Code isn't running | Open Claude Code and let it run; it updates the file on its next status refresh |
 | Codex section is empty | `~/.codex/sessions/` doesn't exist or has no `rate_limits` events yet | Run a Codex conversation to generate log entries |
 | Today's cost shows $0.00 | Model name doesn't match the pricing table, or pricing download/cache failed | Delete `~/.claude/pricing_cache.json` to force a re-fetch; or run with `USAG_DEBUG=1` for details |
-| App won't open (blocked by macOS) | Gatekeeper blocks unsigned apps | Finder → find `usag.app` → right-click → Open → confirm Open |
+| App won't open (blocked by macOS) | Gatekeeper blocks unsigned apps | Finder → find `usage.app` → right-click → Open → confirm Open |
 
 ## Build a .app bundle (optional)
 
@@ -244,6 +244,6 @@ If you want to launch usage by double-clicking instead of opening a terminal, bu
 ./scripts/build_app.sh
 ```
 
-The output is `dist/usag.app`. Double-click it or run `open dist/usag.app`.
+The output is `dist/usage.app`. Double-click it or run `open dist/usage.app`.
 
-Each GitHub Release build (push a `v*` tag) automatically builds the app in CI and attaches `usag.app.zip` to the Release page.
+Each GitHub Release build (push a `v*` tag) automatically builds the app in CI and attaches `usage.app.zip` to the Release page.