docs: make setup guidance agent-neutral (aqua5230#16)

Reframes setup guidance so Codex-only users aren't treated as edge
cases. Setup button gate changed from Claude-only directory check to
status-line target availability (~/.claude/ or ~/.codex/config.toml).
Fills missing ja/ko hook_not_installed translations and brings both
README variants in sync.

Co-authored-by: ericweichun <ericweichun@users.noreply.github.com>

Author: ericweichun

README.en.md

@@ -72,7 +72,7 @@ If Codex isn't installed or the directory doesn't exist, that part of the UI hid
 
 - macOS
 - Python 3.13
-- Claude Code installed and signed in (Codex is optional)
+- Claude Code or Codex has been used at least once so local usage data exists
 
 ## Quick start
 
@@ -104,11 +104,13 @@ Go to the [GitHub Releases page](https://github.com/aqua5230/usage/releases/late
 ⚠️ Because this app is not signed with an Apple Developer certificate, **macOS Gatekeeper will block the first launch**.
 To open it: find `usage.app` in Finder → right-click → Open → confirm Open. After that, double-clicking works normally.
 
-### First launch: install the hook
+### First launch: set up the status line
 
-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 "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.
+The first time you open usage, if you have already used Codex, the Codex card usually reads `~/.codex/sessions` and shows data directly. If you use Claude Code, the popover may show a **"Set Up Status Line"** button when app-side setup is needed. If you run from source and want to add Codex status-line fields, run the command below to configure detected agents.
 
-If the button doesn't show, usage is already reading data (e.g. you previously installed the third-party tool [stormzhang/token-tracker](https://github.com/stormzhang/token-tracker) and its status file works as a fallback) — nothing else to do.
+Restart the relevant tool afterward: restart Codex once; if Claude Code was configured too, fully quit Claude Code (Cmd+Q) and re-open it.
+
+If the button does not show, usage can already read data or there is no Claude Code setup action for the app to perform.
 
 > **Fallback: install via curl**
 > If the in-app button doesn't work or you prefer the command line, run the following in Terminal (download first, inspect, then run):
@@ -119,7 +121,7 @@ If the button doesn't show, usage is already reading data (e.g. you previously i
 > bash /tmp/usage-install.sh
 > ```
 
-After the hook is installed and Claude Code is restarted, the bottom of the Claude Code window will show a statusLine like this — **5h / 7d quota bars, context usage, session duration, current model — all on one line**. Percentages share the bar color (yellow / green / red), so the warning level reads at a glance:
+After the Claude Code hook is configured and Claude Code is restarted, the bottom of the Claude Code window will show a statusLine like this — **5h / 7d quota bars, context usage, session duration, current model — all on one line**. Percentages share the bar color (yellow / green / red), so the warning level reads at a glance:
 
 <p align="center">
   <img src="docs/statusline.en.png" alt="Claude Code statusLine display (English)" width="640">
@@ -146,32 +148,33 @@ pip install -e .
 
 This creates an isolated Python environment (`.venv`) for the project, activates it, and installs usage plus its dependencies into it.
 
-## First install (wire up the Claude Code hook — source mode only)
+## Set up detected agents (source mode)
 
-> Using the .app? Just click the "Install hook now" button in the popover on first launch instead — you don't need this section. The steps below are for developers running usage from source.
+> Using the .app? Click the "Set Up Status Line" button in the popover on first launch instead. 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.
+This command configures detected agents: Codex gets `tui.status_line` in `~/.codex/config.toml`; if Claude Code is present, usage also copies the hook script into `~/.claude/` and updates Claude Code settings to point at it.
 
 ```bash
 source .venv/bin/activate
 python3 main.py --setup
 ```
 
-**Restart Claude Code once after running this** so it re-reads `~/.claude/settings.json` and refreshes its status line. That refresh is when usage data first lands on disk.
+**Restart Codex once after running this**. If Claude Code was configured, restart Claude Code too so it re-reads `~/.claude/settings.json` and refreshes its status line.
 
 What `--setup` does in detail:
 
-- 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.usage.previousStatusLine` so nothing is overwritten.
+- Configures `tui.status_line` in `~/.codex/config.toml` when Codex is detected.
+- If Claude Code is present, copies `usage_statusline.py` to `~/.claude/usage-statusline.py`.
+- If Claude Code is present, points `statusLine` in `~/.claude/settings.json` at that hook.
+- If you already had a custom Claude Code `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/usage-status.json`.
+`--unsetup` restores the original Codex `status_line` and Claude Code `statusLine`, then removes the Claude hook and `~/.claude/usage-status.json`.
 
 ## Run modes
 
@@ -298,7 +301,7 @@ python3 main.py --tui --mock
 
 ## Options
 
-- `--setup` / `--unsetup` — install or remove the Claude Code statusLine hook.
+- `--setup` / `--unsetup` — configure or restore detected agents (Codex `status_line`; Claude Code `statusLine` hook).
 - `--tui` — force terminal TUI mode (no menu bar).
 - `--interval N` — how often (seconds) the UI re-reads the status file. Minimum 30, default 60.
 - `--mock` — use fake data; don't read any status file.
@@ -349,7 +352,7 @@ The "Fix" column distinguishes three kinds of users — find yours first:
 
 | Symptom | Likely cause | Fix |
 |---------|--------------|-----|
-| Menu bar shows `--` | Hook not installed, or Claude Code hasn't refreshed yet | **.app users**: click the "Install hook now" button in the popover. **Source users**: run `python3 main.py --setup`. Either way, restart Claude Code once afterwards |
+| Menu bar shows `--` | No Codex `rate_limits` yet, or the Claude Code hook has not refreshed | Run one Codex conversation first. For Claude Code integration, **.app users** click "Set Up Status Line"; **Source users** run `python3 main.py --setup` |
 | Accidentally hit "Quit", paw icon disappeared from the menu bar | "Quit" fully terminates the usage process; you have to relaunch it | **.app users**: press `Cmd+Space` for Spotlight, type `usage`, hit Enter; or double-click `usage.app` from `/Applications`. **LaunchAgent users**: run `launchctl start com.lollapalooza.usage` in Terminal. **Source users**: run `python3 main.py` in Terminal again |
 | 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 |

README.md

@@ -72,7 +72,7 @@ Codex CLI 沒有 statusLine hook 這種機制，所以 usage 採另一條路：
 
 - macOS
 - Python 3.13
-- 已經裝好、登入過 Claude Code（Codex 是可選的）
+- 已經使用過 Claude Code 或 Codex 其中之一，讓它們在本機留下用量資料
 
 ## 快速開始
 
@@ -104,11 +104,13 @@ ln -s $(brew --prefix)/Cellar/usage/$(brew list --versions usage | awk '{print $
 ⚠️ 因為沒有 Apple Developer 簽章，**第一次開啟時 macOS Gatekeeper（系統的「擋陌生程式」保全機制）會擋下來**。
 解法：在 Finder 找到 `usage.app` → 按住 Ctrl 點右鍵 → 選「打開」→ 再確認一次「打開」。之後就能直接雙擊。
 
-### 首次打開：把 hook 裝起來
+### 首次打開：設定狀態列
 
-第一次打開 usage，如果你還沒「對接」過 Claude Code，popover 會偵測到「找不到狀態檔」，**最下面會多出一顆「立即安裝 hook」按鈕**，按一下就會幫你裝好。然後**完全結束 Claude Code（Cmd+Q）再重新打開一次**，在 usage 視窗按「立即更新」，數字就會跑出來。
+第一次打開 usage，如果你已經用 Codex 跑過對話，Codex 區塊通常會直接讀取 `~/.codex/sessions` 並顯示。若你使用 Claude Code，popover 可能會在需要時顯示「設定狀態列」按鈕。若你是從原始碼執行、想補齊 Codex 狀態列欄位，可以用下方指令手動設定可偵測到的 agent。
 
-如果按鈕沒出現（代表 usage 已經抓到資料了，例如你之前裝過第三方工具 [stormzhang/token-tracker](https://github.com/stormzhang/token-tracker)），就什麼都不用做。
+設定後請重開相關工具：Codex 需要重新開啟一次；如果有設定 Claude Code，也請完全結束 Claude Code（Cmd+Q）再重新打開一次。
+
+如果按鈕沒出現，代表 usage 已經能讀到資料，或目前沒有需要 app 介入的 Claude Code 設定。
 
 > **備援：手動 curl 安裝**
 > 若按鈕按了沒反應、或你想用指令模式裝，打開 Terminal（終端機）執行以下指令（先下載、確認內容後再執行，比較安全）：
@@ -119,7 +121,7 @@ ln -s $(brew --prefix)/Cellar/usage/$(brew list --versions usage | awk '{print $
 > bash /tmp/usage-install.sh
 > ```
 
-裝完 hook 重啟 Claude Code 後，視窗底部會看到這樣的 statusLine —— **5 小時 / 7 天配額條、對話窗用量、會話時長、目前模型，全擠在一行**；數字跟進度條同色（黃 / 綠 / 紅），掃一眼就知道警示級別：
+設定 Claude Code hook 並重啟 Claude Code 後，視窗底部會看到這樣的 statusLine —— **5 小時 / 7 天配額條、對話窗用量、會話時長、目前模型，全擠在一行**；數字跟進度條同色（黃 / 綠 / 紅），掃一眼就知道警示級別：
 
 <p align="center">
   <img src="docs/statusline.png" alt="Claude Code statusLine 顯示樣式（繁中）" width="640">
@@ -148,32 +150,33 @@ pip install -e .
 
 `source .venv/bin/activate` 是「進入這個抽屜」的意思 —— 跑完之後你 terminal 提示字元前面會多一個 `(.venv)`，代表現在 Python 指令會在這個獨立環境裡跑。
 
-## 跟 Claude Code 對接（原始碼模式必跑一次）
+## 設定可偵測到的 agent（原始碼模式）
 
-> 用 .app 的話，第一次打開直接點 popover 上的「立即安裝 hook」按鈕就好，不用跑這段。下面是給從原始碼跑 usage 的開發者用的。
+> 用 .app 的話，第一次打開直接點 popover 上的「設定狀態列」按鈕即可。下面是給從原始碼跑 usage 的開發者用的。
 
-這個指令會做兩件事：把 usage 的 hook 腳本複製到 `~/.claude/` 裡，再去改 Claude Code 的設定檔，讓它每次刷新狀態列時去叫這個 hook。
+這個指令會設定目前偵測到的 agent：Codex 會更新 `~/.codex/config.toml` 的 `tui.status_line`；如果你也有 Claude Code，會把 usage 的 hook 腳本複製到 `~/.claude/` 裡，再去改 Claude Code 的設定檔，讓它每次刷新狀態列時去叫這個 hook。
 
 ```bash
 source .venv/bin/activate
 python3 main.py --setup
 ```
 
-**跑完後請重開一次 Claude Code**，這樣它才會重新讀 `~/.claude/settings.json` 並刷新一次狀態列（資料這時候才會落到磁碟）。
+**跑完後請重開一次 Codex**。如果有設定 Claude Code，也請重開一次 Claude Code，這樣它才會重新讀 `~/.claude/settings.json` 並刷新一次狀態列（資料這時候才會落到磁碟）。
 
 setup 具體做了什麼：
 
-- 把 `usage_statusline.py` 複製到 `~/.claude/usage-statusline.py`
-- 在 `~/.claude/settings.json` 把 `statusLine` 指向這個 hook
-- 如果你本來就有自訂的 statusLine，會自動備份到 `settings.usage.previousStatusLine`，不會被蓋掉
+- 如果有 Codex，在 `~/.codex/config.toml` 設定 `tui.status_line`
+- 如果有 Claude Code，把 `usage_statusline.py` 複製到 `~/.claude/usage-statusline.py`
+- 如果有 Claude Code，在 `~/.claude/settings.json` 把 `statusLine` 指向這個 hook
+- 如果你本來就有自訂的 Claude Code statusLine，會自動備份到 `settings.usage.previousStatusLine`，不會被蓋掉
 
 要卸載：
 
 ```bash
 python3 main.py --unsetup
 ```
 
-unsetup 會把原本的 statusLine 還原回去、刪掉 hook 跟 `~/.claude/usage-status.json`。
+unsetup 會把原本的 Codex `status_line` 與 Claude Code `statusLine` 還原回去，並刪掉 Claude hook 跟 `~/.claude/usage-status.json`。
 
 ## 跑起來
 
@@ -300,7 +303,7 @@ python3 main.py --tui --mock
 
 ## 全部可用參數
 
-- `--setup` / `--unsetup`：安裝 / 卸載 Claude Code statusLine hook。
+- `--setup` / `--unsetup`：設定 / 還原偵測到的 agent（Codex `status_line`；Claude Code `statusLine` hook）。
 - `--tui`：強制使用終端機 TUI 模式（不開 menu bar）。
 - `--interval N`：UI 多久重新讀一次狀態檔（秒）。最小值 30，預設 60。
 - `--mock`：用假資料跑，不讀任何狀態檔。
@@ -351,7 +354,7 @@ USAGE_LANG=zh-CN python3 main.py   # 簡體中文
 
 | 症狀 | 原因 | 解法 |
 |------|------|------|
-| menu bar 顯示 `--` | hook 還沒裝、或 Claude Code 還沒刷新 | **.app 使用者**：點彈出視窗內的「立即安裝 hook」按鈕；**原始碼使用者**：跑 `python3 main.py --setup`。裝完都要重開一次 Claude Code |
+| menu bar 顯示 `--` | 還沒有 Codex rate_limits，或 Claude Code hook 還沒刷新 | 先用 Codex 跑一次對話；若要接 Claude Code，**.app 使用者**點「設定狀態列」，**原始碼使用者**跑 `python3 main.py --setup` |
 | 不小心按「結束」、腳印從選單列消失 | 「結束」會把整個 usage 程式關掉，要手動再開 | **.app 使用者**：按 `Cmd+Space` 叫出 Spotlight、輸入 `usage` 雙擊；或從 `/Applications` 找到 `usage.app` 雙擊。**LaunchAgent 使用者**：在 Terminal 跑 `launchctl start com.lollapalooza.usage`。**從原始碼跑的**：在 Terminal 再跑一次 `python3 main.py` |
 | 狀態顯示「N 分鐘未更新」 | Claude Code 沒在跑，沒有刷新 statusLine | 打開 Claude Code 跑一下，它刷新時會自動更新 |
 | Codex 那塊空白或不顯示 | `~/.codex/sessions/` 不存在，或還沒有含 rate_limits 的 token_count 事件 | 用 Codex 跑一次對話，等它寫入紀錄 |

i18n.json

@@ -67,7 +67,7 @@
     "refresh_now": "↻ 立即更新",
     "analyze_usage": "報告",
     "analysis_failed": "分析報告產生失敗",
-    "install_hook": "安裝 Hook",
+    "install_hook": "設定狀態列",
     "quit": "⏻ 結束",
     "usage_title": "Usage",
     "current_label": "目前",
@@ -89,7 +89,7 @@
     "loading": "加载数据...",
     "no_data": "暂无数据",
     "no_agent": "未检测到任何 AI Agent",
-    "hook_not_installed": "Hook 尚未安裝。請執行：usage setup",
+    "hook_not_installed": "狀態列尚未設定。請執行：usage setup",
     "detected": "检测到: {agents}",
     "agent_not_found": "未检测到 {name}",
     "unknown_cmd": "未知命令: {cmd}",
@@ -320,7 +320,7 @@
     "refresh_now": "↻ Refresh Now",
     "analyze_usage": "Report",
     "analysis_failed": "Analysis report failed",
-    "install_hook": "Install Hook",
+    "install_hook": "Set Up Status Line",
     "quit": "⏻ Quit",
     "usage_title": "Usage",
     "current_label": "Current",
@@ -342,7 +342,7 @@
     "loading": "Loading...",
     "no_data": "No data",
     "no_agent": "No AI Agent detected",
-    "hook_not_installed": "Hook not installed. Run: usage setup",
+    "hook_not_installed": "Status line not configured. Run: usage setup",
     "detected": "Detected: {agents}",
     "agent_not_found": "{name} not detected",
     "unknown_cmd": "Unknown command: {cmd}",
@@ -573,7 +573,7 @@
     "refresh_now": "↻ 立即更新",
     "analyze_usage": "报告",
     "analysis_failed": "分析报告生成失败",
-    "install_hook": "安装 Hook",
+    "install_hook": "设置状态栏",
     "quit": "⏻ 结束",
     "usage_title": "Usage",
     "current_label": "当前",
@@ -595,7 +595,7 @@
     "loading": "加载数据...",
     "no_data": "暂无数据",
     "no_agent": "未检测到任何 AI Agent",
-    "hook_not_installed": "Hook 尚未安装。请运行：usage setup",
+    "hook_not_installed": "状态栏尚未设置。请运行：usage setup",
     "detected": "检测到: {agents}",
     "agent_not_found": "未检测到 {name}",
     "unknown_cmd": "未知命令: {cmd}",
@@ -826,7 +826,7 @@
     "refresh_now": "↻ 今すぐ更新",
     "analyze_usage": "レポート",
     "analysis_failed": "分析レポートの生成に失敗しました",
-    "install_hook": "フックをインストール",
+    "install_hook": "ステータスラインを設定",
     "quit": "⏻ 終了",
     "usage_title": "使用量",
     "current_label": "現在",
@@ -848,7 +848,7 @@
     "loading": "",
     "no_data": "",
     "no_agent": "",
-    "hook_not_installed": "",
+    "hook_not_installed": "ステータスラインが未設定です。実行してください: usage setup",
     "detected": "",
     "agent_not_found": "",
     "unknown_cmd": "",
@@ -1079,7 +1079,7 @@
     "refresh_now": "↻ 지금 새로고침",
     "analyze_usage": "리포트",
     "analysis_failed": "분석 보고서 생성 실패",
-    "install_hook": "훅 설치",
+    "install_hook": "상태 표시줄 설정",
     "quit": "⏻ 종료",
     "usage_title": "사용량",
     "current_label": "현재",
@@ -1101,7 +1101,7 @@
     "loading": "",
     "no_data": "",
     "no_agent": "",
-    "hook_not_installed": "",
+    "hook_not_installed": "상태 표시줄이 설정되지 않았습니다. 실행하세요: usage setup",
     "detected": "",
     "agent_not_found": "",
     "unknown_cmd": "",

menubar.py

@@ -830,6 +830,14 @@ def _status_message_value(self, outcome: PollOutcome, fallback_key: str) -> str:
             return _t(self.language, "awaiting_rate_limits")
         return outcome.message or _t(self.language, fallback_key)
 
+    def _statusline_setup_available(self) -> bool:
+        try:
+            import setup_hook
+
+            return setup_hook.CLAUDE_SETTINGS.parent.exists() or setup_hook.CODEX_CONFIG.exists()
+        except Exception:
+            return False
+
     def _state_from_outcome(
         self,
         outcome: PollOutcome,
@@ -915,7 +923,9 @@ def _state_from_outcome(
             status_text=status_text,
             today_text=today_text,
             statusline=_statusline_payload(self.language),
-            show_install_button=outcome.state == PollState.TOKEN_ERROR,
+            show_install_button=(
+                outcome.state == PollState.TOKEN_ERROR and self._statusline_setup_available()
+            ),
         )
 
     def _codex_rows(self) -> tuple[tuple[QuotaRowState, QuotaRowState], int | None, str]: