usage-cli 0.32.0__tar.gz → 0.32.1__tar.gz

{usage_cli-0.32.0 → usage_cli-0.32.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: usage-cli
-Version: 0.32.0
+Version: 0.32.1
 Summary: usage — 在 macOS menu bar 與 Windows 系統匣顯示 Claude Code、Codex、Antigravity 用量的小工具（也提供終端機 TUI）
 License-Expression: AGPL-3.0-only
 Requires-Python: >=3.13
@@ -57,7 +57,7 @@ It lands in your Applications folder automatically. Open it once; if macOS 15 or
 
 **Not on macOS?** `uvx usage-cli` runs the terminal interface anywhere, Linux included — no install, no menu bar.
 
-**Jump to:** [What You Get](#what-you-get) · [Privacy](#privacy--data-sources) · [Requirements](#requirements) · [Install](#install) · [Status Line](#first-launch-set-up-the-status-line) · [Windows](#windows-support) · [Themes](#theme-gallery) · [Troubleshooting](#troubleshooting) · [Comparison](#comparison) · [Not a Fit?](#when-usage-isnt-the-right-fit) · [Development](#development)
+**Jump to:** [What You Get](#what-you-get) · [Privacy](#privacy--data-sources) · [Requirements](#requirements) · [Install](#install) · [Status Line](#first-launch-set-up-the-status-line) · [Claude Code Side Pane](#claude-code-side-pane) · [Windows](#windows-support) · [Themes](#theme-gallery) · [Troubleshooting](#troubleshooting) · [Comparison](#comparison) · [Not a Fit?](#when-usage-isnt-the-right-fit) · [Development](#development)
 
 ## What You Get
 
@@ -76,7 +76,7 @@ It lands in your Applications folder automatically. Open it once; if macOS 15 or
 
 - **Progress Concierge:** Open a new Claude Code session and `usage` hands your last progress straight to the AI, including your last request, uncommitted changes, and unfinished todos. No `/resume`, no recap. When you do `/resume` a conversation that sat long enough for its cache to expire, it warns you how many tokens the next message will re-send and suggests `/compact` first. Off by default.
 - **Token Saver:** A menu-bar toggle asks Claude Code and Codex to answer more tersely and in plainer language, saving output tokens while keeping code and error messages byte-exact. A light reminder keeps long conversations from drifting back to verbose — in an A/B test on real sessions, late replies stayed ~40% shorter instead of drifting 84% longer.
-- **Claude Code side pane (macOS):** Toggle quotas, Claude sessions and background jobs inside Claude Code. Requires a recent Claude Code with mod support (tested with 2.1.289). Open a new conversation or run `/reload-plugins` after enabling. The pane opens on the right automatically at terminal widths ≥144 columns; use `/usage-dash` in narrower terminals. macOS Terminal supports only 256 colors and may show a gray background; select an ANSI dark theme in `/config`. Conversations waiting for your permission or MCP input are marked in yellow across panes, and background jobs also list subagents started by Claude with the Agent tool and their status. When the usage app starts, it automatically updates an enabled pane to the bundled version.
+- **Claude Code side pane (macOS and Windows):** Quotas, conversations, and background jobs inside Claude Code. [See the side pane](#claude-code-side-pane).
 - **Auto-start 5-hour Session:** Off by default. Turn it on and, right after a 5-hour quota resets, `usage` sends one tiny message to each tool (Claude with Haiku, Antigravity with Gemini 3.5 Flash Low, Codex with its cheapest model) so the next 5-hour window starts counting right away. Those messages do use a little quota, but the amount is negligible. Checking your quota never sends a message; only this switch does.
 - **Terminal Integration:** `usage status --json` hands your Claude Code, Codex, Antigravity, and Grok quota to any tool that can run a command — Starship, tmux, or your own scripts. Reads the same local files as the menu bar. [Ready-made snippets](docs/DEVELOPMENT.md#quota-status-for-other-tools-usage-status).
 - **Token-waste Health Check:** A daily background diagnosis scans your logs for waste, including repeated file reads, polluter directories, and noisy Bash output. If it finds issues, a one-line heads-up appears; say "show me" and the AI walks you through fixes.
@@ -147,6 +147,34 @@ Once set up, the bottom of the Claude Code window will show a status line like t
   <img src="docs/statusline.en.gif" alt="Claude Code statusLine display (English)" width="900">
 </p>
 
+## Claude Code Side Pane
+
+See your quota, other conversations, and background jobs without leaving Claude Code. Available on macOS and Windows.
+
+<p align="center"><img src="docs/side-pane.png" alt="Claude Code side pane showing quotas, conversations, and background jobs" width="637"></p>
+
+**What you’ll see**
+
+- **Quotas:** Your 5-hour and weekly limits.
+- **Claude conversations:** Conversations waiting for your permission or MCP input are marked in yellow.
+- **Background jobs:** Includes subagents started by Claude with the Agent tool and their status.
+
+**How to enable**
+
+1. In the usage menu bar menu (macOS) or the system-tray panel menu (Windows), check **Claude Code side pane**.
+2. Open a new conversation or run `/reload-plugins`.
+3. At terminal widths ≥144 columns, the pane opens on the right automatically. In narrower terminals, enter `/usage-dash`.
+
+<details>
+<summary>Compatibility and updates</summary>
+
+- Requires a recent Claude Code with mod support; tested with 2.1.289.
+- The pane docks on the right only in Claude Code's fullscreen layout; otherwise it appears above the prompt. On Windows, enabling the pane turns the fullscreen layout on as well, and turning the pane off switches it back.
+- The built-in macOS Terminal supports only 256 colors and may show a gray background. Select an ANSI dark theme in `/config`.
+- When the usage app starts, it automatically updates an enabled pane to the bundled version.
+
+</details>
+
 ## Windows Support
 
 Windows has the full core experience: the system-tray UI, Claude Code status-line hook, and Codex history parsing all work natively. Download `usage-windows.zip` from the [latest GitHub Release](https://github.com/aqua5230/usage/releases/latest), unzip it, then run `usage.exe`—no installer is needed. If SmartScreen shows **Windows protected your PC** on first launch, click **More info** → **Run anyway**. The tray UI requires Microsoft Edge WebView2 Runtime, which is normally included with Windows 10 and 11.

{usage_cli-0.32.0 → usage_cli-0.32.1}/README.md

@@ -37,7 +37,7 @@ It lands in your Applications folder automatically. Open it once; if macOS 15 or
 
 **Not on macOS?** `uvx usage-cli` runs the terminal interface anywhere, Linux included — no install, no menu bar.
 
-**Jump to:** [What You Get](#what-you-get) · [Privacy](#privacy--data-sources) · [Requirements](#requirements) · [Install](#install) · [Status Line](#first-launch-set-up-the-status-line) · [Windows](#windows-support) · [Themes](#theme-gallery) · [Troubleshooting](#troubleshooting) · [Comparison](#comparison) · [Not a Fit?](#when-usage-isnt-the-right-fit) · [Development](#development)
+**Jump to:** [What You Get](#what-you-get) · [Privacy](#privacy--data-sources) · [Requirements](#requirements) · [Install](#install) · [Status Line](#first-launch-set-up-the-status-line) · [Claude Code Side Pane](#claude-code-side-pane) · [Windows](#windows-support) · [Themes](#theme-gallery) · [Troubleshooting](#troubleshooting) · [Comparison](#comparison) · [Not a Fit?](#when-usage-isnt-the-right-fit) · [Development](#development)
 
 ## What You Get
 
@@ -56,7 +56,7 @@ It lands in your Applications folder automatically. Open it once; if macOS 15 or
 
 - **Progress Concierge:** Open a new Claude Code session and `usage` hands your last progress straight to the AI, including your last request, uncommitted changes, and unfinished todos. No `/resume`, no recap. When you do `/resume` a conversation that sat long enough for its cache to expire, it warns you how many tokens the next message will re-send and suggests `/compact` first. Off by default.
 - **Token Saver:** A menu-bar toggle asks Claude Code and Codex to answer more tersely and in plainer language, saving output tokens while keeping code and error messages byte-exact. A light reminder keeps long conversations from drifting back to verbose — in an A/B test on real sessions, late replies stayed ~40% shorter instead of drifting 84% longer.
-- **Claude Code side pane (macOS):** Toggle quotas, Claude sessions and background jobs inside Claude Code. Requires a recent Claude Code with mod support (tested with 2.1.289). Open a new conversation or run `/reload-plugins` after enabling. The pane opens on the right automatically at terminal widths ≥144 columns; use `/usage-dash` in narrower terminals. macOS Terminal supports only 256 colors and may show a gray background; select an ANSI dark theme in `/config`. Conversations waiting for your permission or MCP input are marked in yellow across panes, and background jobs also list subagents started by Claude with the Agent tool and their status. When the usage app starts, it automatically updates an enabled pane to the bundled version.
+- **Claude Code side pane (macOS and Windows):** Quotas, conversations, and background jobs inside Claude Code. [See the side pane](#claude-code-side-pane).
 - **Auto-start 5-hour Session:** Off by default. Turn it on and, right after a 5-hour quota resets, `usage` sends one tiny message to each tool (Claude with Haiku, Antigravity with Gemini 3.5 Flash Low, Codex with its cheapest model) so the next 5-hour window starts counting right away. Those messages do use a little quota, but the amount is negligible. Checking your quota never sends a message; only this switch does.
 - **Terminal Integration:** `usage status --json` hands your Claude Code, Codex, Antigravity, and Grok quota to any tool that can run a command — Starship, tmux, or your own scripts. Reads the same local files as the menu bar. [Ready-made snippets](docs/DEVELOPMENT.md#quota-status-for-other-tools-usage-status).
 - **Token-waste Health Check:** A daily background diagnosis scans your logs for waste, including repeated file reads, polluter directories, and noisy Bash output. If it finds issues, a one-line heads-up appears; say "show me" and the AI walks you through fixes.
@@ -127,6 +127,34 @@ Once set up, the bottom of the Claude Code window will show a status line like t
   <img src="docs/statusline.en.gif" alt="Claude Code statusLine display (English)" width="900">
 </p>
 
+## Claude Code Side Pane
+
+See your quota, other conversations, and background jobs without leaving Claude Code. Available on macOS and Windows.
+
+<p align="center"><img src="docs/side-pane.png" alt="Claude Code side pane showing quotas, conversations, and background jobs" width="637"></p>
+
+**What you’ll see**
+
+- **Quotas:** Your 5-hour and weekly limits.
+- **Claude conversations:** Conversations waiting for your permission or MCP input are marked in yellow.
+- **Background jobs:** Includes subagents started by Claude with the Agent tool and their status.
+
+**How to enable**
+
+1. In the usage menu bar menu (macOS) or the system-tray panel menu (Windows), check **Claude Code side pane**.
+2. Open a new conversation or run `/reload-plugins`.
+3. At terminal widths ≥144 columns, the pane opens on the right automatically. In narrower terminals, enter `/usage-dash`.
+
+<details>
+<summary>Compatibility and updates</summary>
+
+- Requires a recent Claude Code with mod support; tested with 2.1.289.
+- The pane docks on the right only in Claude Code's fullscreen layout; otherwise it appears above the prompt. On Windows, enabling the pane turns the fullscreen layout on as well, and turning the pane off switches it back.
+- The built-in macOS Terminal supports only 256 colors and may show a gray background. Select an ANSI dark theme in `/config`.
+- When the usage app starts, it automatically updates an enabled pane to the bundled version.
+
+</details>
+
 ## Windows Support
 
 Windows has the full core experience: the system-tray UI, Claude Code status-line hook, and Codex history parsing all work natively. Download `usage-windows.zip` from the [latest GitHub Release](https://github.com/aqua5230/usage/releases/latest), unzip it, then run `usage.exe`—no installer is needed. If SmartScreen shows **Windows protected your PC** on first launch, click **More info** → **Run anyway**. The tray UI requires Microsoft Edge WebView2 Runtime, which is normally included with Windows 10 and 11.

{usage_cli-0.32.0 → usage_cli-0.32.1}/i18n.json

@@ -471,6 +471,7 @@
     "claude_pane_menu": "Claude Code 側邊面板",
     "claude_pane_tooltip": "在 Claude Code 顯示額度、對話與背景工作",
     "claude_pane_enabled_msg": "已開啟側邊面板。開新的 Claude Code 對話（或在對話裡打 /reload-plugins）後生效；終端機寬度不夠時打 /usage-dash 叫出面板。",
+    "claude_pane_fullscreen_enabled_note": "已一併開啟 Claude Code 的全螢幕介面，讓面板顯示在右側。取消勾選側邊面板時會改回。",
     "claude_pane_disabled_msg": "已移除 Claude Code 側邊面板。",
     "claude_pane_action_failed": "Claude Code 側邊面板切換失敗。",
     "claude_pane_source_missing": "找不到面板原始碼。已檢查：{tried}",
@@ -952,6 +953,7 @@
     "claude_pane_menu": "Claude Code side pane",
     "claude_pane_tooltip": "Show quotas, Claude sessions and background jobs in Claude Code",
     "claude_pane_enabled_msg": "Pane enabled. Open a new Claude Code conversation (or run /reload-plugins in a conversation). If the terminal is too narrow, run /usage-dash to open the pane.",
+    "claude_pane_fullscreen_enabled_note": "Claude Code's fullscreen layout is now on so the pane can sit on the right. Turning the side pane off switches it back.",
     "claude_pane_disabled_msg": "Claude Code side pane removed.",
     "claude_pane_action_failed": "Could not change the Claude Code side pane.",
     "claude_pane_source_missing": "Pane source not found. Tried: {tried}",
@@ -1433,6 +1435,7 @@
     "claude_pane_menu": "Claude Code 侧边面板",
     "claude_pane_tooltip": "在 Claude Code 显示额度、对话与后台任务",
     "claude_pane_enabled_msg": "已开启侧边面板。打开新的 Claude Code 对话（或在对话里输入 /reload-plugins）后生效；终端宽度不够时输入 /usage-dash 打开面板。",
+    "claude_pane_fullscreen_enabled_note": "已一并开启 Claude Code 的全屏界面，让面板显示在右侧。取消勾选侧边面板时会改回。",
     "claude_pane_disabled_msg": "已移除 Claude Code 侧边面板。",
     "claude_pane_action_failed": "Claude Code 侧边面板切换失败。",
     "claude_pane_source_missing": "找不到面板源代码。已检查：{tried}",
@@ -1914,6 +1917,7 @@
     "claude_pane_menu": "Claude Code サイドパネル",
     "claude_pane_tooltip": "Claude Code に使用量、セッション、バックグラウンド作業を表示",
     "claude_pane_enabled_msg": "サイドパネルを有効にしました。新しい Claude Code セッションを開くか、会話で /reload-plugins を実行してください。ターミナルの幅が足りない場合は /usage-dash で開けます。",
+    "claude_pane_fullscreen_enabled_note": "Claude Code のフルスクリーンレイアウトを有効にし、パネルを右側に表示できるようにしました。サイドパネルをオフにすると元に戻ります。",
     "claude_pane_disabled_msg": "Claude Code サイドパネルを削除しました。",
     "claude_pane_action_failed": "Claude Code サイドパネルを切り替えられませんでした。",
     "claude_pane_source_missing": "パネルのソースがありません。確認先: {tried}",
@@ -2395,6 +2399,7 @@
     "claude_pane_menu": "Claude Code 사이드 패널",
     "claude_pane_tooltip": "Claude Code에 사용량, 대화 및 백그라운드 작업 표시",
     "claude_pane_enabled_msg": "사이드 패널을 켰습니다. 새 Claude Code 대화를 열거나 대화에서 /reload-plugins를 실행하세요. 터미널이 좁으면 /usage-dash로 패널을 여세요.",
+    "claude_pane_fullscreen_enabled_note": "Claude Code의 전체 화면 레이아웃도 켜서 패널이 오른쪽에 표시됩니다. 사이드 패널을 끄면 원래대로 돌아갑니다.",
     "claude_pane_disabled_msg": "Claude Code 사이드 패널을 제거했습니다.",
     "claude_pane_action_failed": "Claude Code 사이드 패널을 전환하지 못했습니다.",
     "claude_pane_source_missing": "패널 소스를 찾을 수 없습니다. 확인한 경로: {tried}",

{usage_cli-0.32.0 → usage_cli-0.32.1}/installer/claude_pane.py

@@ -45,6 +45,8 @@ def _resolve_source() -> Path:
 
 
 def _status_argv() -> list[str]:
+    if getattr(sys, "frozen", False) and sys.platform == "win32":
+        return [sys.executable, "status", "--json"]
     if getattr(sys, "frozen", False):
         resources = str(Path(sys.executable).resolve().parent.parent / "Resources")
         major, minor = sys.version_info[:2]
@@ -142,9 +144,25 @@ def enable_claude_pane() -> int:
     return 0
 
 
+def is_fullscreen_layout() -> bool:
+    return setup_hook._load_settings().get("tui") == "fullscreen"
+
+
+def enable_fullscreen_layout() -> None:
+    settings = setup_hook._load_settings()
+    settings["tui"] = "fullscreen"
+    usage = settings.get("usage")
+    if not isinstance(usage, dict):
+        usage = {}
+        settings["usage"] = usage
+    usage["claudePaneSetFullscreen"] = True
+    setup_hook._save_settings(settings)
+
+
 def disable_claude_pane() -> int:
     settings = setup_hook._load_settings()
     env = _env(settings)
+    changed = False
     if PLUGIN_DIRS_KEY in env:
         value = _remove_path(env[PLUGIN_DIRS_KEY], str(INSTALL_DIR.absolute()))
         if value:
@@ -153,6 +171,16 @@ def disable_claude_pane() -> int:
             env.pop(PLUGIN_DIRS_KEY)
         if not env:
             settings.pop("env", None)
+        changed = True
+    usage = settings.get("usage")
+    if isinstance(usage, dict) and usage.get("claudePaneSetFullscreen") is True:
+        if settings.get("tui") == "fullscreen":
+            settings.pop("tui")
+        usage.pop("claudePaneSetFullscreen")
+        if not usage:
+            settings.pop("usage")
+        changed = True
+    if changed:
         setup_hook._save_settings(settings)
     if INSTALL_DIR.exists():
         shutil.rmtree(INSTALL_DIR)

{usage_cli-0.32.0 → usage_cli-0.32.1}/main.py

@@ -314,6 +314,11 @@ async def run_tui(mock: bool, interval: int, force_group: int | None = None) ->
 
 
 def main() -> None:
+    if sys.argv[1:2] == ["status"]:
+        import usage_cli
+
+        usage_cli.main()
+        return
     _setup_logging()
     args = parse_args()
     if args.doctor:

{usage_cli-0.32.0 → usage_cli-0.32.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "usage-cli"
-version = "0.32.0"
+version = "0.32.1"
 description = "usage — 在 macOS menu bar 與 Windows 系統匣顯示 Claude Code、Codex、Antigravity 用量的小工具（也提供終端機 TUI）"
 readme = "README.md"
 requires-python = ">=3.13"

{usage_cli-0.32.0 → usage_cli-0.32.1}/tests/test_claude_pane.py

@@ -82,6 +82,50 @@ def test_disable_only_ours(isolated: Path, others: bool, keep_env: bool) -> None
     assert not pane.is_claude_pane_enabled()
 
 
+def test_enable_fullscreen_layout_records_usage_flag(isolated: Path) -> None:
+    setup_hook._save_settings({"usage": {"other": "keep"}, "other": "keep"})
+
+    pane.enable_fullscreen_layout()
+
+    assert setup_hook._load_settings() == {
+        "tui": "fullscreen",
+        "usage": {"other": "keep", "claudePaneSetFullscreen": True},
+        "other": "keep",
+    }
+
+
+def test_disable_restores_fullscreen_layout_set_by_pane(isolated: Path) -> None:
+    pane.INSTALL_DIR.mkdir(parents=True)
+    setup_hook._save_settings(
+        {
+            "tui": "fullscreen",
+            "usage": {"claudePaneSetFullscreen": True, "other": "keep"},
+        }
+    )
+
+    assert pane.disable_claude_pane() == 0
+
+    assert setup_hook._load_settings() == {"usage": {"other": "keep"}}
+
+
+def test_disable_keeps_user_fullscreen_layout(isolated: Path) -> None:
+    pane.INSTALL_DIR.mkdir(parents=True)
+    setup_hook._save_settings({"tui": "fullscreen"})
+
+    assert pane.disable_claude_pane() == 0
+
+    assert setup_hook._load_settings() == {"tui": "fullscreen"}
+
+
+def test_disable_keeps_changed_tui_when_pane_flagged(isolated: Path) -> None:
+    pane.INSTALL_DIR.mkdir(parents=True)
+    setup_hook._save_settings({"tui": "compact", "usage": {"claudePaneSetFullscreen": True}})
+
+    assert pane.disable_claude_pane() == 0
+
+    assert setup_hook._load_settings() == {"tui": "compact"}
+
+
 def test_tilde_disable_and_reinstall(isolated: Path, monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.setenv("HOME", str(pane.INSTALL_DIR.parent))
     monkeypatch.setenv("USERPROFILE", str(pane.INSTALL_DIR.parent))
@@ -222,6 +266,15 @@ def test_uses_platform_separator(monkeypatch: pytest.MonkeyPatch) -> None:
     assert pane._remove_path("/other;/pane/", "/pane") == "/other"
 
 
+def test_status_argv_uses_windows_frozen_executable(monkeypatch: pytest.MonkeyPatch) -> None:
+    executable = r"C:\\Program Files\\usage\\usage.exe"
+    monkeypatch.setattr(sys, "frozen", True, raising=False)
+    monkeypatch.setattr(sys, "platform", "win32")
+    monkeypatch.setattr(sys, "executable", executable)
+
+    assert pane._status_argv() == [executable, "status", "--json"]
+
+
 def test_missing_sidecar_language_falls_back(
     isolated: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:

{usage_cli-0.32.0 → usage_cli-0.32.1}/tests/test_main.py

@@ -70,6 +70,19 @@ def test_parse_args_setup(monkeypatch: Any) -> None:
     assert args.setup is True
 
 
+def test_main_delegates_status_before_logging(monkeypatch: Any) -> None:
+    import usage_cli
+
+    calls: list[str] = []
+    monkeypatch.setattr(sys, "argv", ["usage", "status", "--json"])
+    monkeypatch.setattr(main, "_setup_logging", lambda: calls.append("logging"))
+    monkeypatch.setattr(usage_cli, "main", lambda: calls.append("status"))
+
+    main.main()
+
+    assert calls == ["status"]
+
+
 def test_apply_outcome_success_updates_snapshot_and_clears_fatal_message() -> None:
     state = AppViewState(fatal_message="boom")
     snapshot = _snapshot()

{usage_cli-0.32.0 → usage_cli-0.32.1}/tests/test_wintray.py

@@ -22,6 +22,7 @@ import panels
 import prefs
 import service_status
 from i18n import _t
+from installer import claude_pane
 from loaders import codex_loader
 from loaders.agy_quota_probe import AgyQuotaGroup, AgyQuotaResult, AgyQuotaWindow
 from menubar import agy as menubar_agy
@@ -1534,6 +1535,7 @@ def test_panel_menu_data_is_localized_and_reads_current_checks(
     monkeypatch.setattr(wintray, "_window_keeper_enabled", lambda: True)
     monkeypatch.setattr(wintray, "_session_resume_enabled", lambda: True)
     monkeypatch.setattr(wintray, "_terse_mode_enabled", lambda: False)
+    monkeypatch.setattr(wintray, "_claude_pane_enabled", lambda: True)
 
     menu = controller._panel_menu_data()
 
@@ -1553,6 +1555,7 @@ def test_panel_menu_data_is_localized_and_reads_current_checks(
         "window_keeper_menu",
         "project_butler",
         "terse_mode_menu",
+        "claude_pane_menu",
         "separator",
         "check_update",
     ]
@@ -1566,6 +1569,7 @@ def test_panel_menu_data_is_localized_and_reads_current_checks(
     assert menu[7]["checked"] is True
     assert menu[8]["checked"] is True
     assert menu[9]["checked"] is False
+    assert menu[10]["checked"] is True
 
 
 def test_panel_and_tray_menus_render_the_shared_model(
@@ -1683,6 +1687,7 @@ def test_tray_quit_label_removes_the_power_glyph() -> None:
         ({"action": "toggle_window_keeper"}, "toggle_window_keeper", ()),
         ({"action": "toggle_session_resume"}, "toggle_session_resume", ()),
         ({"action": "toggle_terse_mode"}, "toggle_terse_mode", ()),
+        ({"action": "toggle_claude_pane"}, "toggle_claude_pane", ()),
         ({"action": "check_update"}, "check_update", ()),
         ({"action": "quit"}, "quit", ()),
     ],
@@ -1930,6 +1935,7 @@ def test_attach_schedules_startup_maintenance_after_tray_is_visible(
         "wintray.app.usage_diagnosis_snapshot.maybe_schedule_refresh",
         lambda: events.append("diagnosis"),
     )
+    monkeypatch.setattr(claude_pane, "refresh_claude_pane", lambda: events.append("claude-pane"))
     monkeypatch.setattr(
         controller,
         "_clear_stale_update_cache",
@@ -1951,7 +1957,8 @@ def test_attach_schedules_startup_maintenance_after_tray_is_visible(
     ]
     startup = next(thread for thread in threads if thread.target == controller._startup_maintenance)
     startup.target(**startup.kwargs)
-    assert events[-3:] == [
+    assert events[-4:] == [
+        "claude-pane",
         "diagnosis",
         "clear-update-cache",
         (
@@ -1961,6 +1968,86 @@ def test_attach_schedules_startup_maintenance_after_tray_is_visible(
     ]
 
 
+def test_claude_pane_menu_check_and_toggle_results(monkeypatch: pytest.MonkeyPatch) -> None:
+    controller = wintray._WindowsTrayController(mock=True, interval=60)
+    controller.language = "en"
+    entry = wintray_menu.MenuCommand(
+        "claude_pane_menu", "toggle_claude_pane", checked_by="claude_pane"
+    )
+    messages: list[str] = []
+    monkeypatch.setattr(claude_pane, "is_claude_pane_enabled", lambda: False)
+    monkeypatch.setattr(claude_pane, "enable_claude_pane", lambda: 0)
+    monkeypatch.setattr(claude_pane, "is_fullscreen_layout", lambda: True)
+    monkeypatch.setattr(controller, "_message_box", messages.append)
+
+    assert wintray._menu_checked(controller, entry) is False
+    controller._toggle_claude_pane_in_background()
+
+    assert messages == [_t("en", "claude_pane_enabled_msg")]
+
+
+def test_claude_pane_toggle_enables_fullscreen_and_reports_note(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    controller = wintray._WindowsTrayController(mock=True, interval=60)
+    controller.language = "en"
+    messages: list[str] = []
+    calls: list[str] = []
+    monkeypatch.setattr(claude_pane, "is_claude_pane_enabled", lambda: False)
+    monkeypatch.setattr(claude_pane, "enable_claude_pane", lambda: 0)
+    monkeypatch.setattr(claude_pane, "is_fullscreen_layout", lambda: False)
+    monkeypatch.setattr(claude_pane, "enable_fullscreen_layout", lambda: calls.append("fullscreen"))
+
+    monkeypatch.setattr(controller, "_message_box", messages.append)
+
+    controller._toggle_claude_pane_in_background()
+
+    assert calls == ["fullscreen"]
+    assert messages == [
+        f"{_t('en', 'claude_pane_enabled_msg')}\n\n"
+        f"{_t('en', 'claude_pane_fullscreen_enabled_note')}"
+    ]
+
+
+def test_claude_pane_toggle_fullscreen_failure_reports_error(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    controller = wintray._WindowsTrayController(mock=True, interval=60)
+    controller.language = "en"
+    messages: list[str] = []
+    monkeypatch.setattr(claude_pane, "is_claude_pane_enabled", lambda: False)
+    monkeypatch.setattr(claude_pane, "enable_claude_pane", lambda: 0)
+    monkeypatch.setattr(claude_pane, "is_fullscreen_layout", lambda: False)
+
+    def fail() -> None:
+        raise OSError("fullscreen failure")
+
+    monkeypatch.setattr(claude_pane, "enable_fullscreen_layout", fail)
+    monkeypatch.setattr(controller, "_message_box", messages.append)
+
+    controller._toggle_claude_pane_in_background()
+
+    assert messages == [f"{_t('en', 'claude_pane_action_failed')}\n\nfullscreen failure"]
+
+
+def test_claude_pane_toggle_failure_reports_output(monkeypatch: pytest.MonkeyPatch) -> None:
+    controller = wintray._WindowsTrayController(mock=True, interval=60)
+    controller.language = "en"
+    messages: list[str] = []
+    monkeypatch.setattr(claude_pane, "is_claude_pane_enabled", lambda: False)
+
+    def fail() -> int:
+        print("pane failure")
+        return 1
+
+    monkeypatch.setattr(claude_pane, "enable_claude_pane", fail)
+    monkeypatch.setattr(controller, "_message_box", messages.append)
+
+    controller._toggle_claude_pane_in_background()
+
+    assert messages == [f"{_t('en', 'claude_pane_action_failed')}\n\npane failure"]
+
+
 def test_refresh_requested_while_busy_runs_once_after_current_refresh(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:

{usage_cli-0.32.0 → usage_cli-0.32.1}/usage_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: usage-cli
-Version: 0.32.0
+Version: 0.32.1
 Summary: usage — 在 macOS menu bar 與 Windows 系統匣顯示 Claude Code、Codex、Antigravity 用量的小工具（也提供終端機 TUI）
 License-Expression: AGPL-3.0-only
 Requires-Python: >=3.13
@@ -57,7 +57,7 @@ It lands in your Applications folder automatically. Open it once; if macOS 15 or
 
 **Not on macOS?** `uvx usage-cli` runs the terminal interface anywhere, Linux included — no install, no menu bar.
 
-**Jump to:** [What You Get](#what-you-get) · [Privacy](#privacy--data-sources) · [Requirements](#requirements) · [Install](#install) · [Status Line](#first-launch-set-up-the-status-line) · [Windows](#windows-support) · [Themes](#theme-gallery) · [Troubleshooting](#troubleshooting) · [Comparison](#comparison) · [Not a Fit?](#when-usage-isnt-the-right-fit) · [Development](#development)
+**Jump to:** [What You Get](#what-you-get) · [Privacy](#privacy--data-sources) · [Requirements](#requirements) · [Install](#install) · [Status Line](#first-launch-set-up-the-status-line) · [Claude Code Side Pane](#claude-code-side-pane) · [Windows](#windows-support) · [Themes](#theme-gallery) · [Troubleshooting](#troubleshooting) · [Comparison](#comparison) · [Not a Fit?](#when-usage-isnt-the-right-fit) · [Development](#development)
 
 ## What You Get
 
@@ -76,7 +76,7 @@ It lands in your Applications folder automatically. Open it once; if macOS 15 or
 
 - **Progress Concierge:** Open a new Claude Code session and `usage` hands your last progress straight to the AI, including your last request, uncommitted changes, and unfinished todos. No `/resume`, no recap. When you do `/resume` a conversation that sat long enough for its cache to expire, it warns you how many tokens the next message will re-send and suggests `/compact` first. Off by default.
 - **Token Saver:** A menu-bar toggle asks Claude Code and Codex to answer more tersely and in plainer language, saving output tokens while keeping code and error messages byte-exact. A light reminder keeps long conversations from drifting back to verbose — in an A/B test on real sessions, late replies stayed ~40% shorter instead of drifting 84% longer.
-- **Claude Code side pane (macOS):** Toggle quotas, Claude sessions and background jobs inside Claude Code. Requires a recent Claude Code with mod support (tested with 2.1.289). Open a new conversation or run `/reload-plugins` after enabling. The pane opens on the right automatically at terminal widths ≥144 columns; use `/usage-dash` in narrower terminals. macOS Terminal supports only 256 colors and may show a gray background; select an ANSI dark theme in `/config`. Conversations waiting for your permission or MCP input are marked in yellow across panes, and background jobs also list subagents started by Claude with the Agent tool and their status. When the usage app starts, it automatically updates an enabled pane to the bundled version.
+- **Claude Code side pane (macOS and Windows):** Quotas, conversations, and background jobs inside Claude Code. [See the side pane](#claude-code-side-pane).
 - **Auto-start 5-hour Session:** Off by default. Turn it on and, right after a 5-hour quota resets, `usage` sends one tiny message to each tool (Claude with Haiku, Antigravity with Gemini 3.5 Flash Low, Codex with its cheapest model) so the next 5-hour window starts counting right away. Those messages do use a little quota, but the amount is negligible. Checking your quota never sends a message; only this switch does.
 - **Terminal Integration:** `usage status --json` hands your Claude Code, Codex, Antigravity, and Grok quota to any tool that can run a command — Starship, tmux, or your own scripts. Reads the same local files as the menu bar. [Ready-made snippets](docs/DEVELOPMENT.md#quota-status-for-other-tools-usage-status).
 - **Token-waste Health Check:** A daily background diagnosis scans your logs for waste, including repeated file reads, polluter directories, and noisy Bash output. If it finds issues, a one-line heads-up appears; say "show me" and the AI walks you through fixes.
@@ -147,6 +147,34 @@ Once set up, the bottom of the Claude Code window will show a status line like t
   <img src="docs/statusline.en.gif" alt="Claude Code statusLine display (English)" width="900">
 </p>
 
+## Claude Code Side Pane
+
+See your quota, other conversations, and background jobs without leaving Claude Code. Available on macOS and Windows.
+
+<p align="center"><img src="docs/side-pane.png" alt="Claude Code side pane showing quotas, conversations, and background jobs" width="637"></p>
+
+**What you’ll see**
+
+- **Quotas:** Your 5-hour and weekly limits.
+- **Claude conversations:** Conversations waiting for your permission or MCP input are marked in yellow.
+- **Background jobs:** Includes subagents started by Claude with the Agent tool and their status.
+
+**How to enable**
+
+1. In the usage menu bar menu (macOS) or the system-tray panel menu (Windows), check **Claude Code side pane**.
+2. Open a new conversation or run `/reload-plugins`.
+3. At terminal widths ≥144 columns, the pane opens on the right automatically. In narrower terminals, enter `/usage-dash`.
+
+<details>
+<summary>Compatibility and updates</summary>
+
+- Requires a recent Claude Code with mod support; tested with 2.1.289.
+- The pane docks on the right only in Claude Code's fullscreen layout; otherwise it appears above the prompt. On Windows, enabling the pane turns the fullscreen layout on as well, and turning the pane off switches it back.
+- The built-in macOS Terminal supports only 256 colors and may show a gray background. Select an ANSI dark theme in `/config`.
+- When the usage app starts, it automatically updates an enabled pane to the bundled version.
+
+</details>
+
 ## Windows Support
 
 Windows has the full core experience: the system-tray UI, Claude Code status-line hook, and Codex history parsing all work natively. Download `usage-windows.zip` from the [latest GitHub Release](https://github.com/aqua5230/usage/releases/latest), unzip it, then run `usage.exe`—no installer is needed. If SmartScreen shows **Windows protected your PC** on first launch, click **More info** → **Run anyway**. The tray UI requires Microsoft Edge WebView2 Runtime, which is normally included with Windows 10 and 11.

{usage_cli-0.32.0 → usage_cli-0.32.1}/usage_cli.py

@@ -10,7 +10,7 @@ import sys
 from collections.abc import Callable
 from datetime import UTC, datetime
 from pathlib import Path
-from typing import Any
+from typing import Any, cast
 
 from loaders import agy_quota_probe, codex_loader, grok_quota_probe
 from adapters import agy, claude, codex, grok, muse
@@ -483,6 +483,8 @@ def _run_status(args: list[str]) -> None:
 
     payload = _status_payload(include_extra_agents="--json" in args)
     if "--json" in args:
+        if sys.platform == "win32" and sys.stdout is not None:
+            cast(Any, sys.stdout).reconfigure(encoding="utf-8")
         print(json.dumps(payload, ensure_ascii=False, separators=(",", ":")))
     else:
         print(_status_summary(payload))

{usage_cli-0.32.0 → usage_cli-0.32.1}/wintray/app.py

@@ -864,6 +864,12 @@ class _WindowsTrayController:
         self.refresh()
 
     def _startup_maintenance(self) -> None:
+        from installer import claude_pane
+
+        try:
+            claude_pane.refresh_claude_pane()
+        except (OSError, SystemExit):
+            logger.warning("Claude Code pane refresh failed", exc_info=True)
         usage_diagnosis_snapshot.maybe_schedule_refresh()
         self._clear_stale_update_cache()
         self._check_update_in_background(
@@ -1838,6 +1844,49 @@ class _WindowsTrayController:
             if os.environ.get("USAGE_DEBUG") == "1":
                 logger.warning("toggle terse mode failed", exc_info=True)
 
+    def toggle_claude_pane(self, _icon: Any = None, _item: Any = None) -> None:
+        threading.Thread(target=self._toggle_claude_pane_in_background, daemon=True).start()
+
+    def _toggle_claude_pane_in_background(self) -> None:
+        import contextlib
+        import io
+
+        from installer import claude_pane
+
+        output = io.StringIO()
+        ok = False
+        enabled = False
+        try:
+            with contextlib.redirect_stdout(output), contextlib.redirect_stderr(output):
+                enabled = not claude_pane.is_claude_pane_enabled()
+                action = (
+                    claude_pane.enable_claude_pane if enabled else claude_pane.disable_claude_pane
+                )
+                ok = action() == 0
+        except SystemExit as exc:
+            print(exc.code, file=output)
+        except Exception as exc:
+            print(f"{type(exc).__name__}: {exc}", file=output)
+
+        if ok:
+            if enabled and not claude_pane.is_fullscreen_layout():
+                try:
+                    claude_pane.enable_fullscreen_layout()
+                except (OSError, SystemExit) as exc:
+                    self._message_box(f"{_t(self.language, 'claude_pane_action_failed')}\n\n{exc}")
+                else:
+                    self._message_box(
+                        f"{_t(self.language, 'claude_pane_enabled_msg')}\n\n"
+                        f"{_t(self.language, 'claude_pane_fullscreen_enabled_note')}"
+                    )
+            else:
+                key = "claude_pane_enabled_msg" if enabled else "claude_pane_disabled_msg"
+                self._message_box(_t(self.language, key))
+        else:
+            self._message_box(
+                f"{_t(self.language, 'claude_pane_action_failed')}\n\n{output.getvalue().strip()}"
+            )
+
     def _process_quota_notifications(self, state: menubar_state.PopoverState) -> None:
         try:
             events = self._quota_notifier.update(
@@ -2120,6 +2169,8 @@ class _WindowsTrayController:
                 self.toggle_session_resume()
             elif action == "toggle_terse_mode":
                 self.toggle_terse_mode()
+            elif action == "toggle_claude_pane":
+                self.toggle_claude_pane()
             elif action == "check_update":
                 self.check_update()
             elif action == "quit":
@@ -2221,6 +2272,7 @@ def _menu_checked(controller: _WindowsTrayController, entry: wintray_menu.MenuCo
         "window_keeper": _window_keeper_enabled,
         "session_resume": _session_resume_enabled,
         "terse_mode": _terse_mode_enabled,
+        "claude_pane": _claude_pane_enabled,
     }
     return checks[entry.checked_by]() if entry.checked_by is not None else False
 
@@ -2292,6 +2344,15 @@ def _terse_mode_enabled() -> bool:
         return False
 
 
+def _claude_pane_enabled() -> bool:
+    try:
+        from installer import claude_pane
+
+        return claude_pane.is_claude_pane_enabled()
+    except Exception:
+        return False
+
+
 _SINGLE_INSTANCE_MUTEX = "usage-windows-tray-single-instance"
 _ERROR_ALREADY_EXISTS = 183
 _single_instance_handle: int | None = None