Improve report CLI and project usage refresh

Author: ericweichun

README.en.md

@@ -108,9 +108,11 @@ To open it: find `usage.app` in Finder → right-click → Open → confirm Open
 
 ### First launch: set up the status line
 
-The first time you open usage, if you have already used Codex, the Codex card can show data immediately. If usage needs to configure Codex status-line fields, or if you also want Claude Code integration, the popover may show a **"Set Up Status Line"** button at the bottom. Click it once to configure detected agents. Restart Codex afterward; if Claude Code was configured too, fully quit Claude Code (Cmd+Q) and re-open it.
+The first time you open usage, if you have already used Codex, the Codex card usually reads `~/.codex/sessions` and shows data directly. You do not need Claude Code installed, and you do not need extra setup just to read Codex history.
 
-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.
+If you run from source and want to add Codex status-line fields, run `python3 main.py --setup`; it prioritizes detected Codex configuration, and only configures Claude Code integration if Claude Code is also present.
+
+If you also want Claude Code integration, the popover may show a **"Set Up Status Line"** button when Claude Code needs app-side setup. Click it once, then 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):

README.md

@@ -108,9 +108,11 @@ ln -s $(brew --prefix)/Cellar/usage/$(brew list --versions usage | awk '{print $
 
 ### 首次打開：設定狀態列
 
-第一次打開 usage，如果你已經用 Codex 跑過對話，Codex 區塊會直接顯示。若需要補齊 Codex 狀態列欄位或你也想對接 Claude Code，popover 可能會顯示「設定狀態列」按鈕，按一下就會幫你設定可偵測到的 agent。設定後請重開 Codex；如果有設定 Claude Code，也請完全結束 Claude Code（Cmd+Q）再重新打開一次。
+第一次打開 usage，如果你已經用 Codex 跑過對話，Codex 區塊通常會直接讀取 `~/.codex/sessions` 並顯示，不需要安裝 Claude Code，也不需要先做額外設定。
 
-如果按鈕沒出現（代表 usage 已經抓到資料了，例如你之前裝過第三方工具 [stormzhang/token-tracker](https://github.com/stormzhang/token-tracker)），就什麼都不用做。
+若你是從原始碼執行、想補齊 Codex status line 欄位，可以跑 `python3 main.py --setup`；它會優先設定可偵測到的 Codex，若你的環境也有 Claude Code，才會一併處理 Claude Code 對接。
+
+如果你也想對接 Claude Code，popover 可能會在需要時顯示「設定狀態列」按鈕。按一下後請完全結束 Claude Code（Cmd+Q）再重新打開一次。若按鈕沒出現，代表 usage 已經能讀到資料或目前沒有需要 app 介入的 Claude Code 設定。
 
 > **備援：手動 curl 安裝**
 > 若按鈕按了沒反應、或你想用指令模式裝，打開 Terminal（終端機）執行以下指令（先下載、確認內容後再執行，比較安全）：

menubar.py

@@ -334,6 +334,8 @@ class AppDelegate(NSObject):
     _refresh_in_flight = objc.ivar()
     _refresh_queued = objc.ivar()
     _fs_stream = objc.ivar()
+    _history_entries_cache = objc.ivar()
+    _history_entries_cache_fingerprint = objc.ivar()
     language = objc.ivar()
 
     def initWithMock_interval_(self, mock: bool, interval: int) -> AppDelegate:
@@ -356,6 +358,8 @@ def initWithMock_interval_(self, mock: bool, interval: int) -> AppDelegate:
         self._refresh_in_flight = False
         self._refresh_queued = False
         self._fs_stream = None
+        self._history_entries_cache = None
+        self._history_entries_cache_fingerprint = None
         return self
 
     def applicationDidFinishLaunching_(self, notification: Any) -> None:
@@ -992,9 +996,39 @@ def _codex_rows(self) -> tuple[tuple[QuotaRowState, QuotaRowState], int | None]:
         )
         return rows, codex_5h_pct
 
+    def _history_sources_fingerprint(self) -> tuple[tuple[str, int, float], ...]:
+        sources = (
+            Path.home() / ".claude",
+            Path.home() / ".codex" / "sessions",
+        )
+        fingerprint: list[tuple[str, int, float]] = []
+        for source in sources:
+            newest_mtime = 0.0
+            file_count = 0
+            try:
+                if source.exists():
+                    for path in source.rglob("*.jsonl"):
+                        try:
+                            stat = path.stat()
+                        except OSError:
+                            continue
+                        file_count += 1
+                        newest_mtime = max(newest_mtime, stat.st_mtime)
+            except OSError:
+                pass
+            fingerprint.append((str(source), file_count, newest_mtime))
+        return tuple(fingerprint)
+
     def _load_history_entries(self) -> list[UsageEntry]:
         if self.mock:
             return []
+        fingerprint = self._history_sources_fingerprint()
+        if (
+            self._history_entries_cache is not None
+            and self._history_entries_cache_fingerprint == fingerprint
+        ):
+            return list(self._history_entries_cache)
+
         entries: list[UsageEntry] = []
         try:
             entries.extend(load_entries(hours_back=0))
@@ -1006,6 +1040,8 @@ def _load_history_entries(self) -> list[UsageEntry]:
         except Exception:
             if os.environ.get("USAGE_DEBUG") == "1":
                 logger.warning("Codex project usage load failed", exc_info=True)
+        self._history_entries_cache = list(entries)
+        self._history_entries_cache_fingerprint = fingerprint
         return entries
 
     def _project_rows(

tests/test_menubar.py

@@ -603,6 +603,94 @@ def test_load_history_entries_includes_codex_entries(monkeypatch: pytest.MonkeyP
     assert entries == [claude_entry, codex_entry]
 
 
+def test_load_history_entries_reuses_cache_when_sources_do_not_change(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    delegate = menubar.AppDelegate.alloc().initWithMock_interval_(False, 60)
+    claude_entry = history_loader.UsageEntry(
+        timestamp=datetime(2026, 5, 21, tzinfo=UTC),
+        session_id="claude-session",
+        message_id="claude-message",
+        request_id="claude-request",
+        model="claude",
+        input_tokens=10,
+        output_tokens=5,
+        cache_creation_tokens=0,
+        cache_read_tokens=0,
+        cost_usd=0.01,
+        project="ClaudeProject",
+    )
+    codex_entry = history_loader.UsageEntry(
+        timestamp=datetime(2026, 5, 22, tzinfo=UTC),
+        session_id="codex-session",
+        message_id="codex-message",
+        request_id="",
+        model="gpt",
+        input_tokens=20,
+        output_tokens=7,
+        cache_creation_tokens=0,
+        cache_read_tokens=0,
+        cost_usd=None,
+        project="CodexProject",
+    )
+    calls = {"claude": 0, "codex": 0}
+
+    def fake_claude_entries(*, hours_back: int = 0) -> list[history_loader.UsageEntry]:
+        calls["claude"] += 1
+        return [claude_entry]
+
+    def fake_codex_entries(*, hours_back: int = 0) -> list[history_loader.UsageEntry]:
+        calls["codex"] += 1
+        return [codex_entry]
+
+    monkeypatch.setattr(delegate, "_history_sources_fingerprint", lambda: (("same", 1, 1.0),))
+    monkeypatch.setattr(menubar, "load_entries", fake_claude_entries)
+    monkeypatch.setattr(codex_loader, "load_entries", fake_codex_entries)
+
+    first = delegate._load_history_entries()
+    second = delegate._load_history_entries()
+
+    assert first == [claude_entry, codex_entry]
+    assert second == first
+    assert calls == {"claude": 1, "codex": 1}
+
+
+def test_load_history_entries_refreshes_cache_when_sources_change(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    delegate = menubar.AppDelegate.alloc().initWithMock_interval_(False, 60)
+    entries = [
+        history_loader.UsageEntry(
+            timestamp=datetime(2026, 5, 22, tzinfo=UTC),
+            session_id="codex-session",
+            message_id="codex-message",
+            request_id="",
+            model="gpt",
+            input_tokens=20,
+            output_tokens=7,
+            cache_creation_tokens=0,
+            cache_read_tokens=0,
+            cost_usd=None,
+            project="CodexProject",
+        )
+    ]
+    calls = 0
+    fingerprints = iter(((("old", 1, 1.0),), (("new", 2, 2.0),)))
+
+    def fake_codex_entries(*, hours_back: int = 0) -> list[history_loader.UsageEntry]:
+        nonlocal calls
+        calls += 1
+        return entries
+
+    monkeypatch.setattr(delegate, "_history_sources_fingerprint", lambda: next(fingerprints))
+    monkeypatch.setattr(menubar, "load_entries", lambda *, hours_back=0: [])
+    monkeypatch.setattr(codex_loader, "load_entries", fake_codex_entries)
+
+    assert delegate._load_history_entries() == entries
+    assert delegate._load_history_entries() == entries
+    assert calls == 2
+
+
 def test_project_rows_top3(monkeypatch: pytest.MonkeyPatch) -> None:
     delegate = menubar.AppDelegate.alloc().initWithMock_interval_(False, 60)
     now = datetime.now(tz=UTC)

tests/test_usage_cli.py

@@ -121,6 +121,46 @@ def test_main_report_defaults_to_all_time(
     assert calls == {"agents": [agent], "period": expected_period}
 
 
+def test_main_report_help_does_not_build_report(monkeypatch: pytest.MonkeyPatch) -> None:
+    from analyzer import reporter
+
+    printed: list[str] = []
+
+    monkeypatch.setattr(sys, "argv", ["usage", "report", "--help"])
+    monkeypatch.setattr(
+        usage_cli,
+        "detect_agents",
+        lambda: pytest.fail("report help should not detect agents"),
+    )
+    monkeypatch.setattr(usage_cli, "is_setup", lambda: True)
+    monkeypatch.setattr(usage_cli.console, "print", lambda value: printed.append(str(value)))
+    monkeypatch.setattr(
+        reporter,
+        "build_report_data",
+        lambda agents, period: pytest.fail("report help should not build a report"),
+    )
+
+    usage_cli.main()
+
+    assert any("Usage: usage report" in line for line in printed)
+
+
+def test_main_report_rejects_unknown_option(monkeypatch: pytest.MonkeyPatch) -> None:
+    agent = AgentInfo("codex", "Codex", "~/.codex", True)
+    printed: list[str] = []
+
+    monkeypatch.setattr(sys, "argv", ["usage", "report", "--bogus"])
+    monkeypatch.setattr(usage_cli, "detect_agents", lambda: [agent])
+    monkeypatch.setattr(usage_cli, "is_setup", lambda: True)
+    monkeypatch.setattr(usage_cli.console, "print", lambda value: printed.append(str(value)))
+
+    with pytest.raises(SystemExit) as exc_info:
+        usage_cli.main()
+
+    assert exc_info.value.code == 1
+    assert any("unknown report option" in line for line in printed)
+
+
 def test_main_exits_when_no_agents_detected(monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.setattr(sys, "argv", ["usage", "dashboard"])
     monkeypatch.setattr(usage_cli, "detect_agents", lambda: [])

usage_cli.py

@@ -26,6 +26,20 @@
     "output": ("output_tokens", True),
 }
 
+REPORT_HELP = """Usage: usage report [--all|--last30|--today|--week|--month] [--out PATH]
+
+Generate an HTML usage report.
+
+Options:
+  --all       Include all usage data (default)
+  --last30    Include the last 30 days
+  --today     Include today only
+  --week      Include this week
+  --month     Include this month
+  --out PATH  Save to a specific path
+  -h, --help  Show this help
+"""
+
 
 def _parse_sort_args(args: list[str]) -> tuple[list[str], str | None, bool]:
     """Extract --sort KEY and --asc from args, return (remaining, sort_key, descending)."""
@@ -49,6 +63,43 @@ def _parse_sort_args(args: list[str]) -> tuple[list[str], str | None, bool]:
     return remaining, sort_key, descending
 
 
+def _parse_report_args(args: list[str]) -> tuple[str, str | None, bool]:
+    period = "all"
+    out_path = None
+    show_help = False
+    i = 0
+    while i < len(args):
+        arg = args[i]
+        if arg in {"-h", "--help"}:
+            show_help = True
+        elif arg == "--last30":
+            period = "last30"
+        elif arg == "--today":
+            period = "today"
+        elif arg == "--week":
+            period = "week"
+        elif arg == "--month":
+            period = "month"
+        elif arg == "--all":
+            period = "all"
+        elif arg.startswith("--out="):
+            out_path = arg[6:]
+        elif arg == "--out":
+            if i + 1 >= len(args) or args[i + 1].startswith("--"):
+                console.print("[red]Error:[/red] --out requires a path")
+                sys.exit(1)
+            out_path = args[i + 1]
+            i += 1
+        elif arg.startswith("-"):
+            console.print(f"[red]Error:[/red] unknown report option: {arg}")
+            sys.exit(1)
+        else:
+            console.print(f"[red]Error:[/red] unexpected report argument: {arg}")
+            sys.exit(1)
+        i += 1
+    return period, out_path, show_help
+
+
 def _apply_sort(stats, sort_key: str | None, descending: bool, default_attr: str, default_reverse: bool):
     if sort_key is None:
         stats.sort(key=lambda s: getattr(s, default_attr), reverse=default_reverse)
@@ -364,6 +415,9 @@ def main():
     if command in ("--version", "-v", "-V"):
         print(f"usage {_get_version()}")
         return
+    if command == "report" and any(arg in {"-h", "--help"} for arg in args[1:]):
+        console.print(REPORT_HELP)
+        return
     if command == "setup":
         setup()
         return
@@ -412,27 +466,10 @@ def main():
     rest_args, sort_key, sort_desc = _parse_sort_args(args[1:])
 
     if command == "report":
-        period = "all"
-        out_path = None
-        i = 1
-        while i < len(args):
-            arg = args[i]
-            if arg == "--last30":
-                period = "last30"
-            elif arg == "--today":
-                period = "today"
-            elif arg == "--week":
-                period = "week"
-            elif arg == "--month":
-                period = "month"
-            elif arg == "--all":
-                period = "all"
-            elif arg.startswith("--out="):
-                out_path = arg[6:]
-            elif arg == "--out" and i + 1 < len(args):
-                out_path = args[i + 1]
-                i += 1
-            i += 1
+        period, out_path, show_help = _parse_report_args(args[1:])
+        if show_help:
+            console.print(REPORT_HELP)
+            return
         from analyzer.reporter import build_report_data
         from ui.html_report import save_and_open