token-tracker 0.4.7__tar.gz → 0.4.9__tar.gz

{token_tracker-0.4.7/src/token_tracker.egg-info → token_tracker-0.4.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: token-tracker
-Version: 0.4.7
+Version: 0.4.9
 Summary: Track token usage across local AI agents (Claude Code, Codex)
 Author-email: stormzhang <stormzhang.dev@gmail.com>
 License: MIT License
@@ -43,10 +43,14 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: rich>=13.7
 Requires-Dist: questionary<3,>=2.0
+Requires-Dist: textual>=1.0
+Requires-Dist: iterm2>=2.9; sys_platform == "darwin"
 Provides-Extra: test
 Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.24; extra == "test"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
 Requires-Dist: ruff>=0.6; extra == "dev"
 Requires-Dist: mypy>=1.8; extra == "dev"
 Dynamic: license-file
@@ -67,6 +71,8 @@ Dynamic: license-file
 
 - **多 Agent 统一追踪** — Claude Code + Codex 统一读取，多 Agent 按来源分组
 - **状态栏集成** — Claude Code 用官方 StatusLine 接口；**Codex 业界首创伪 statusline 方案**（hook 注入两行真彩色状态栏，把官方未开放的能力在 Codex 里做了出来）
+- **实时侧边栏** — `tt sidebar` 窄窗格常驻面板：全部活跃会话一屏总览（状态灯 + 最近提示词 + 「下一步」建议），点击会话直达对应 iTerm2 / tmux 窗格
+- **当前会话自动分屏** — Codex 中显式执行 `$tt-sidebar`，在原会话右侧自动打开 1/3 宽度的独立提示词侧边栏
 - **限额监控** — 实时 5h / 7d 配额百分比 + 重置倒计时
 - **多维成本分析** — 会话 / 日 / 周 / 月多维报表，等效成本统计
 - **定价识别** — litellm 在线定价 + 内置官方价双层兜底，覆盖 Claude / OpenAI / Gemini / Grok 及国产主流（Kimi / GLM / Qwen / 豆包 / DeepSeek / MiniMax / MiMo）；新模型自动套用同系列定价、不静默归零
@@ -124,7 +130,7 @@ Codex 官方暂不支持自定义 StatusLine。Token Tracker 通过 hook 注入
 
 ## 报表速览
 
-`tt status` — 过去 5h 实时面板（合并概览 + 5h/7d 额度 + 近期会话）
+`tt status` — 今日实时面板（今日合并概览 + 5h/7d 额度 + 今日会话）
 
 ![Status](assets/screenshot.png)
 
@@ -140,6 +146,34 @@ Codex 官方暂不支持自定义 StatusLine。Token Tracker 通过 hook 注入
 
 ![Sessions](assets/screenshot-sessions.png)
 
+## 实时侧边栏（`tt sidebar`）
+
+在终端分屏 / tmux 窄窗格里常驻，一屏总览本机所有 AI 会话：
+
+- **活跃会话列表** — 过去 5h 内有动静的会话（Claude Code + Codex），按最近活动排序取前 10；头行显示状态灯、`项目名(分支)`、agent、模型与距上次活动时间
+- **三地时钟** — 北京、洛杉矶、伦敦合并为一行，只显示城市与 `HH:MM`
+- **提示词历史** — 运行中、待确认、等输入会话保留最近 5 条，历史最多 1 行、最新最多 2 行；空闲会话只显示最新 1 条，不显示「下一步」
+- **状态灯** — 运行中（星形动画）/ 需要关注（工具调用无结果，大概率在等授权）/ 等输入 / 空闲
+- **「下一步」建议** — 从 AI 最后一条回复的收尾段提取征询 / 待办（纯规则，不走模型）；AI 正在用 AskUserQuestion 提问时直接显示问题与选项
+- **点击跳转** — 点会话头行直接切换到它所在的 iTerm2 / tmux 窗格（需启用对应 Agent 的状态栏组件提供映射；Codex 在下一次回答完成后建立映射；iTerm2 首次点击会弹 macOS 自动化授权，属预期）
+
+操作：鼠标拖拽选择文字，松开后自动复制；滚轮 / 方向键 / PgUp/PgDn 滚动，`q` / `Esc` / `Ctrl+C` 退出；`tt sidebar --once` 打印一帧快照即退。数据每 5s 刷新，只读本地会话记录、不写任何产物；加 `--claude` / `--codex` 可只看单个 agent。
+
+### Codex 当前会话自动 1/3 分屏（`$tt-sidebar`）
+
+`tt setup` 会把 `$tt-sidebar` 安装为用户级 Codex Skill。它与普通 `tt sidebar` 相互独立：普通命令继续显示全部活跃会话；Skill 只显示发起命令的当前 Codex 会话，右侧自动占 1/3 宽度，完整提示词按时间倒序展示，最新永远置顶。
+
+在 Codex 输入：
+
+```text
+$tt-sidebar
+```
+
+- 支持 iTerm2（需在 iTerm2 设置中启用 Python API）与 tmux；原会话窗格保持焦点。
+- `tt setup` 把 Codex 的伪 statusline `Stop` 与 sidebar `UserPromptSubmit` 统一安装到用户级 `hooks.json`；后者用本地 FIFO 把新提示词推给已打开的分屏，无 sidebar 时立即返回，不轮询 transcript、不上传或持久化提示词。
+- Codex 会要求审查非托管 Hook：安装后运行 `/hooks`，信任 Token Tracker 对应项。Skill 未立即出现时重启 Codex。
+- `tt unsetup` 会一并移除 Token Tracker 管理的 Skill 与 Hook；若 `~/.agents/skills/tt-sidebar` 已是用户自己的同名 Skill，安装与卸载都不会覆盖它。
+
 ## 安装
 
 ```bash
@@ -148,7 +182,7 @@ curl -sSL https://raw.githubusercontent.com/stormzhang/token-tracker/main/instal
 
 脚本自动选最优安装方式（uv / pipx / 私有 venv），绕开 PEP 668、不污染系统 Python。
 
-> **升级**：重跑上面的命令即可（脚本幂等、自动升到最新）。
+> **升级**：重跑上面的命令即可（脚本幂等、自动升到最新）。包含新 Agent 集成的版本升级后，再运行一次 `tt setup`；例如 `$tt-sidebar` 需要由 setup 安装到 Codex 用户级 Skill 目录。
 > **卸载**：`tt unsetup`
 
 **升级后 `tt --version` 还是旧版？** 多半是旧版装在别的 Python 环境里遮蔽了新版（常见于 Windows、或早期用 `pip install` 装过）。卸载旧版后重装一次即可：
@@ -161,13 +195,14 @@ curl -sSL https://raw.githubusercontent.com/stormzhang/token-tracker/main/instal
 ## 使用
 
 ```bash
-tt setup          # 交互配置向导（终端：上下键选语言 / 主题 / 各组件）；非 tty 环境按推荐默认自动配置
+tt setup          # 配置状态栏，并安装 Codex $tt-sidebar Skill / 提示词 Hook
 tt                # 过去一年 token 热力图 + 顶部三段概览（= tt daily）
 tt daily          # 同上（tt 无参即进 daily）
-tt status         # 过去 5h 实时面板
+tt status         # 今日消耗、5h/7d 额度与今日会话
 tt weekly         # 周报
 tt monthly        # 月报
-tt sessions       # 最近 20 条会话明细（tt sessions <n> 改条数、--sort 改排序）
+tt sessions       # 最近 20 条会话明细（tt sessions <正整数> 改条数、--sort 改排序）
+tt sidebar        # 常驻侧边栏：活跃会话总览 + 提示词历史 + 状态灯 + 点击跳转（--once 一帧快照）
 tt theme          # 查看 / 切换配色主题（show / list / set / preview）
 tt unsetup        # 卸载并恢复安装前的配置
 tt --version      # 查看版本（-v / -V 同义）

{token_tracker-0.4.7 → token_tracker-0.4.9}/README.md

@@ -14,6 +14,8 @@
 
 - **多 Agent 统一追踪** — Claude Code + Codex 统一读取，多 Agent 按来源分组
 - **状态栏集成** — Claude Code 用官方 StatusLine 接口；**Codex 业界首创伪 statusline 方案**（hook 注入两行真彩色状态栏，把官方未开放的能力在 Codex 里做了出来）
+- **实时侧边栏** — `tt sidebar` 窄窗格常驻面板：全部活跃会话一屏总览（状态灯 + 最近提示词 + 「下一步」建议），点击会话直达对应 iTerm2 / tmux 窗格
+- **当前会话自动分屏** — Codex 中显式执行 `$tt-sidebar`，在原会话右侧自动打开 1/3 宽度的独立提示词侧边栏
 - **限额监控** — 实时 5h / 7d 配额百分比 + 重置倒计时
 - **多维成本分析** — 会话 / 日 / 周 / 月多维报表，等效成本统计
 - **定价识别** — litellm 在线定价 + 内置官方价双层兜底，覆盖 Claude / OpenAI / Gemini / Grok 及国产主流（Kimi / GLM / Qwen / 豆包 / DeepSeek / MiniMax / MiMo）；新模型自动套用同系列定价、不静默归零
@@ -71,7 +73,7 @@ Codex 官方暂不支持自定义 StatusLine。Token Tracker 通过 hook 注入
 
 ## 报表速览
 
-`tt status` — 过去 5h 实时面板（合并概览 + 5h/7d 额度 + 近期会话）
+`tt status` — 今日实时面板（今日合并概览 + 5h/7d 额度 + 今日会话）
 
 ![Status](assets/screenshot.png)
 
@@ -87,6 +89,34 @@ Codex 官方暂不支持自定义 StatusLine。Token Tracker 通过 hook 注入
 
 ![Sessions](assets/screenshot-sessions.png)
 
+## 实时侧边栏（`tt sidebar`）
+
+在终端分屏 / tmux 窄窗格里常驻，一屏总览本机所有 AI 会话：
+
+- **活跃会话列表** — 过去 5h 内有动静的会话（Claude Code + Codex），按最近活动排序取前 10；头行显示状态灯、`项目名(分支)`、agent、模型与距上次活动时间
+- **三地时钟** — 北京、洛杉矶、伦敦合并为一行，只显示城市与 `HH:MM`
+- **提示词历史** — 运行中、待确认、等输入会话保留最近 5 条，历史最多 1 行、最新最多 2 行；空闲会话只显示最新 1 条，不显示「下一步」
+- **状态灯** — 运行中（星形动画）/ 需要关注（工具调用无结果，大概率在等授权）/ 等输入 / 空闲
+- **「下一步」建议** — 从 AI 最后一条回复的收尾段提取征询 / 待办（纯规则，不走模型）；AI 正在用 AskUserQuestion 提问时直接显示问题与选项
+- **点击跳转** — 点会话头行直接切换到它所在的 iTerm2 / tmux 窗格（需启用对应 Agent 的状态栏组件提供映射；Codex 在下一次回答完成后建立映射；iTerm2 首次点击会弹 macOS 自动化授权，属预期）
+
+操作：鼠标拖拽选择文字，松开后自动复制；滚轮 / 方向键 / PgUp/PgDn 滚动，`q` / `Esc` / `Ctrl+C` 退出；`tt sidebar --once` 打印一帧快照即退。数据每 5s 刷新，只读本地会话记录、不写任何产物；加 `--claude` / `--codex` 可只看单个 agent。
+
+### Codex 当前会话自动 1/3 分屏（`$tt-sidebar`）
+
+`tt setup` 会把 `$tt-sidebar` 安装为用户级 Codex Skill。它与普通 `tt sidebar` 相互独立：普通命令继续显示全部活跃会话；Skill 只显示发起命令的当前 Codex 会话，右侧自动占 1/3 宽度，完整提示词按时间倒序展示，最新永远置顶。
+
+在 Codex 输入：
+
+```text
+$tt-sidebar
+```
+
+- 支持 iTerm2（需在 iTerm2 设置中启用 Python API）与 tmux；原会话窗格保持焦点。
+- `tt setup` 把 Codex 的伪 statusline `Stop` 与 sidebar `UserPromptSubmit` 统一安装到用户级 `hooks.json`；后者用本地 FIFO 把新提示词推给已打开的分屏，无 sidebar 时立即返回，不轮询 transcript、不上传或持久化提示词。
+- Codex 会要求审查非托管 Hook：安装后运行 `/hooks`，信任 Token Tracker 对应项。Skill 未立即出现时重启 Codex。
+- `tt unsetup` 会一并移除 Token Tracker 管理的 Skill 与 Hook；若 `~/.agents/skills/tt-sidebar` 已是用户自己的同名 Skill，安装与卸载都不会覆盖它。
+
 ## 安装
 
 ```bash
@@ -95,7 +125,7 @@ curl -sSL https://raw.githubusercontent.com/stormzhang/token-tracker/main/instal
 
 脚本自动选最优安装方式（uv / pipx / 私有 venv），绕开 PEP 668、不污染系统 Python。
 
-> **升级**：重跑上面的命令即可（脚本幂等、自动升到最新）。
+> **升级**：重跑上面的命令即可（脚本幂等、自动升到最新）。包含新 Agent 集成的版本升级后，再运行一次 `tt setup`；例如 `$tt-sidebar` 需要由 setup 安装到 Codex 用户级 Skill 目录。
 > **卸载**：`tt unsetup`
 
 **升级后 `tt --version` 还是旧版？** 多半是旧版装在别的 Python 环境里遮蔽了新版（常见于 Windows、或早期用 `pip install` 装过）。卸载旧版后重装一次即可：
@@ -108,13 +138,14 @@ curl -sSL https://raw.githubusercontent.com/stormzhang/token-tracker/main/instal
 ## 使用
 
 ```bash
-tt setup          # 交互配置向导（终端：上下键选语言 / 主题 / 各组件）；非 tty 环境按推荐默认自动配置
+tt setup          # 配置状态栏，并安装 Codex $tt-sidebar Skill / 提示词 Hook
 tt                # 过去一年 token 热力图 + 顶部三段概览（= tt daily）
 tt daily          # 同上（tt 无参即进 daily）
-tt status         # 过去 5h 实时面板
+tt status         # 今日消耗、5h/7d 额度与今日会话
 tt weekly         # 周报
 tt monthly        # 月报
-tt sessions       # 最近 20 条会话明细（tt sessions <n> 改条数、--sort 改排序）
+tt sessions       # 最近 20 条会话明细（tt sessions <正整数> 改条数、--sort 改排序）
+tt sidebar        # 常驻侧边栏：活跃会话总览 + 提示词历史 + 状态灯 + 点击跳转（--once 一帧快照）
 tt theme          # 查看 / 切换配色主题（show / list / set / preview）
 tt unsetup        # 卸载并恢复安装前的配置
 tt --version      # 查看版本（-v / -V 同义）

{token_tracker-0.4.7 → token_tracker-0.4.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "token-tracker"
-version = "0.4.7"
+version = "0.4.9"
 description = "Track token usage across local AI agents (Claude Code, Codex)"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -28,14 +28,20 @@ dependencies = [
     "rich>=13.7",
     # wizard 补丁挂在 questionary 私有内部（InquirerControl._get_choice_tokens 等），锁大版本防破坏
     "questionary>=2.0,<3",
+    # 仅 tt sidebar live 模式用（cli 延迟 import，日常 tt 启动不加载）；与 rich 同门，渲染对象直接复用
+    "textual>=1.0",
+    # 仅 macOS 的 $tt-sidebar 自动 iTerm2 分屏 worker 加载；其它平台走 tmux、不安装
+    "iterm2>=2.9; sys_platform == 'darwin'",
 ]
 
 [project.optional-dependencies]
 test = [
     "pytest>=8.0",
+    "pytest-asyncio>=0.24",
 ]
 dev = [
     "pytest>=8.0",
+    "pytest-asyncio>=0.24",
     "ruff>=0.6",
     "mypy>=1.8",
 ]
@@ -51,6 +57,9 @@ tt = "token_tracker.cli:main"
 [tool.setuptools.packages.find]
 where = ["src"]
 
+[tool.setuptools.package-data]
+"token_tracker.skills.tt_sidebar" = ["SKILL.md", "agents/*.yaml"]
+
 [tool.ruff]
 line-length = 120
 target-version = "py311"
@@ -68,6 +77,8 @@ select = ["E4", "E7", "E9", "F", "W", "I", "UP", "B"]
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 addopts = "-q"
+# sidebar 的 Textual app 用 pilot 异步测试；auto 模式让 async def 用例免装饰器直接跑
+asyncio_mode = "auto"
 
 [tool.mypy]
 python_version = "3.11"

{token_tracker-0.4.7 → token_tracker-0.4.9}/src/token_tracker/adapters/claude.py

@@ -3,7 +3,7 @@ from datetime import UTC, datetime
 from pathlib import Path
 
 from .types import AgentInfo, UsageEntry
-from .util import claude_home, iter_jsonl_dicts, project_from_cwd
+from .util import claude_home, file_may_have_events_since, iter_jsonl_dicts, project_from_cwd
 
 CLAUDE_DIRS = [
     os.path.join(claude_home(), "projects"),
@@ -31,6 +31,8 @@ def load_entries(hours_back: int = 0) -> list[UsageEntry]:
         if not base.is_dir():
             continue
         for jsonl_path in base.rglob("*.jsonl"):
+            if not file_may_have_events_since(jsonl_path, cutoff):
+                continue
             fallback_project = _extract_project_from_dir(jsonl_path, base)
             _parse_jsonl(jsonl_path, fallback_project, entries, seen, cutoff)
 

{token_tracker-0.4.7 → token_tracker-0.4.9}/src/token_tracker/adapters/codex.py

@@ -4,7 +4,7 @@ from datetime import UTC, datetime, timedelta
 from pathlib import Path
 
 from .types import AgentInfo, RateLimits, UsageEntry, normalize_pct
-from .util import codex_home, iter_jsonl_dicts, project_from_cwd
+from .util import codex_home, file_may_have_events_since, iter_jsonl_dicts, project_from_cwd
 
 CODEX_DIR = codex_home()
 SESSIONS_DIR = os.path.join(CODEX_DIR, "sessions")
@@ -45,6 +45,8 @@ def load_entries(hours_back: int = 0) -> list[UsageEntry]:
         return entries
 
     for jsonl_path in sessions_path.rglob("*.jsonl"):
+        if not file_may_have_events_since(jsonl_path, cutoff):
+            continue
         _parse_jsonl(jsonl_path, models, entries, seen, cutoff)
 
     entries.sort(key=lambda e: e.timestamp)

{token_tracker-0.4.7 → token_tracker-0.4.9}/src/token_tracker/adapters/util.py

@@ -3,6 +3,7 @@
 import json
 import os
 from collections.abc import Iterator
+from datetime import datetime
 from pathlib import Path
 
 
@@ -45,6 +46,20 @@ def iter_jsonl_dicts(path: Path | str) -> Iterator[dict]:
         return
 
 
+def file_may_have_events_since(path: Path, cutoff: datetime | None) -> bool:
+    """文件是否可能包含 cutoff 之后的事件；无窗口时放行，文件消失时跳过。
+
+    JSONL 只追加写，事件时间不会晚于文件 mtime，因此 mtime 早于 cutoff 的文件可在逐行解析前
+    安全排除。mtime 新只代表“可能有”，仍由解析器按事件时间做最终过滤。
+    """
+    if cutoff is None:
+        return True
+    try:
+        return path.stat().st_mtime >= cutoff.timestamp()
+    except OSError:
+        return False
+
+
 def project_from_cwd(cwd: str) -> str:
     """项目名：优先取所属 git 仓库根的目录名（逐级向上找 .git，纯文件系统、不依赖 git 二进制）；
     非仓库 / 仓库根也删了 → 回退去 home 前缀后的最后一段。

{token_tracker-0.4.7 → token_tracker-0.4.9}/src/token_tracker/analyzer/cost.py

@@ -152,7 +152,8 @@ def _load_pricing() -> dict:
 def _read_cache() -> dict | None:
     try:
         with open(CACHE_PATH, encoding="utf-8") as f:
-            return json.load(f)
+            data = json.load(f)
+        return data if isinstance(data, dict) else None
     except (OSError, json.JSONDecodeError):
         return None
 

{token_tracker-0.4.7 → token_tracker-0.4.9}/src/token_tracker/cli.py

@@ -20,10 +20,12 @@ from .analyzer.aggregator import (
 from .analyzer.cost import calculate_cost
 from .hooks import is_setup, needs_update, setup, unsetup, update_hook
 from .i18n import t
+from .sidebar import registry_update_hint, scan_sessions
 from .tz import system_tz
 from .ui import theme, themes
 from .ui.console import forced_color_console, get_console
 from .ui.heatmap import render_daily_heatmap
+from .ui.sidebar import render_sidebar
 from .ui.status import render_sessions_view, render_status
 from .ui.tables import (
     render_monthly,
@@ -59,12 +61,15 @@ _REPORT_COMMANDS: dict[str, tuple[Callable, Callable | None, str, str, bool]] =
 
 
 def _parse_limit(args: list[str], default: int) -> int:
-    for a in args:
-        try:
-            return int(a)
-        except ValueError:
-            pass
-    return default
+    if not args:
+        return default
+    try:
+        value = int(args[0])
+    except ValueError as exc:
+        raise ValueError(args[0]) from exc
+    if value <= 0:
+        raise ValueError(args[0])
+    return value
 
 
 def _extract_agent_arg(args: list[str]) -> tuple[list[str], str | None]:
@@ -216,6 +221,22 @@ def _summary_from_sessions(sessions) -> StatusSummary:
     return sm
 
 
+def _cmd_sidebar(agents, args: list[str]) -> None:
+    """常驻侧边栏（窄窗格用）：活跃会话 + 各自最近提示词。live 模式跑 Textual app
+    （备用屏 + 滚动 + 5s 定时刷新，q / Ctrl+C 退出）；`--once` 或非 tty 打一帧
+    Rich 快照即退（脚本 / `!tt sidebar` / 测试用）。只读 transcript 与心跳文件，
+    不写任何产物；不跟随会话收窄 agent——侧边栏本职是「总览所有会话」，
+    显式 --claude / --codex 才过滤。"""
+    agent_ids = {a.id for a in agents}
+    if "--once" in args or not sys.stdout.isatty():
+        sessions = scan_sessions(agent_ids=agent_ids)
+        with forced_color_console():
+            get_console().print(render_sidebar(sessions, update_hint=registry_update_hint(sessions)))
+        return
+    from .ui.sidebar_app import SidebarApp  # 延迟 import：textual 仅 live 模式加载
+    SidebarApp(agent_ids=agent_ids).run()
+
+
 def _current_session_agent() -> str | None:
     """识别当前所在的 agent 会话（靠**会话内才有**的环境变量）：Codex / Claude Code；独立终端返回 None。
     不能用 CLAUDE_CONFIG_DIR 判断——那是用户级配置变量（可长期 export 在 shell profile 里挪配置目录，
@@ -385,132 +406,150 @@ def cmd_theme(args: list[str]) -> None:
         get_console().print(f"[dim]{t('theme_usage')}[/dim]")
 
 
-def main():
-    # --mock：本地开发演示，加载 mock/ 假数据再走正常报表流程（mock/ 在 .gitignore）
-    if "--mock" in sys.argv:
-        sys.argv = [a for a in sys.argv if a != "--mock"]
-        _load_local_mock()
+def _apply_theme_override(name: str | None) -> None:
+    if name is None:
+        return
+    if name not in themes.THEMES:
+        get_console().print(f"[red]{t('theme_unknown', name=name)}[/red]")
+        get_console().print(f"[dim]{t('theme_options', names=', '.join(themes.THEME_NAMES))}[/dim]")
+        sys.exit(1)
+    theme.set_active_theme(name)
 
-    args = sys.argv[1:]
-    # --claude / --codex：多 agent 环境按需只看一个 agent 的报表（issue #19），互斥；不给则走默认
-    args, filter_agent = _extract_agent_arg(args)
-    # --theme NAME：临时覆盖主题（仅本次进程、不落配置/不重烘焙状态栏），对所有报表 + status 生效
-    args, theme_override = _extract_theme_arg(args)
-    if theme_override is not None:
-        if theme_override not in themes.THEMES:
-            get_console().print(f"[red]{t('theme_unknown', name=theme_override)}[/red]")
-            get_console().print(f"[dim]{t('theme_options', names=', '.join(themes.THEME_NAMES))}[/dim]")
-            sys.exit(1)
-        theme.set_active_theme(theme_override)
-    command = args[0] if args else "daily"
 
-    # 版本查询不该触发任何文件读写，放在 auto-update 之前短路返回
+def _handle_non_data_command(command: str, args: list[str]) -> bool:
+    """处理不需要 Agent 数据的命令；已处理返回 True。"""
     if command in ("--version", "-v", "-V"):
         print(f"token-tracker {_get_version()}")
         print("by stormzhang · https://github.com/stormzhang/token-tracker")
-        return
-
+        return True
     if command == "theme":
-        cmd_theme(args[1:])
-        return
-
-    # 已配置过的情况下，任意命令都顺带同步状态栏脚本（setup/unsetup 自行处理）
-    # 避免升级 pip 包后忘了 tt setup，导致 ~/.claude/tt-statusline.py 停在旧版本
-    if command not in ("setup", "unsetup") and is_setup() and needs_update():
-        update_hook()
-
-    # 升级感知：新版若新增了值得重配的选项（SETUP_VERSION bump），老用户跑任意命令时
-    # 自动走一遍 setup——_run_setup_flow 内部分流：真终端弹 wizard、会话内 / 非 tty 静默
-    # _auto_setup 用默认值全装（语言跟随系统 / mocha / 组件全开）。两者最终都 save_setup_version()，
-    # 下次启动 setup_version 已是最新、不再触发。
-    if (
-        command not in ("setup", "unsetup")
-        and is_setup()
-        and config.setup_version() < config.SETUP_VERSION
-    ):
-        _run_setup_flow()
-
+        cmd_theme(args)
+        return True
     if command == "setup":
         _run_setup_flow()
-        return
+        return True
     if command == "unsetup":
         unsetup()
-        return
+        return True
+    return False
+
 
-    # 数据命令只看「配没配过」：没配过 → 走 setup 流程（装没装 agent 的检测都在那），
-    # 引导后仍未配置（零 agent / 用户取消）→ 退出。配过则直接往下拿 agents 跑。
+def _ensure_data_ready() -> None:
+    """数据命令运行前同步脚本、处理升级引导，并确保至少完成过一次 setup。"""
+    configured = is_setup()
+    if configured and needs_update():
+        update_hook()
+    if configured and config.setup_version() < config.SETUP_VERSION:
+        _run_setup_flow()
     if not is_setup():
         _run_setup_flow()
         if not is_setup():
             sys.exit(1)
 
-    agents = detect_agents()
-    if filter_agent is not None:
-        # 显式指定 agent：收窄 agents 列表，所有报表命令自动跟随；未装 / 未检测到 → 报错退出
-        matched = [a for a in agents if a.id == filter_agent]
-        if not matched:
-            flag = "--claude" if filter_agent == "claude-code" else "--codex"
-            get_console().print(f"[red]{t('agent_not_detected', flag=flag)}[/red]")
-            sys.exit(1)
-        agents = matched
-    agent_ids = {a.id for a in agents}
-
-    if command in ("status", "dashboard"):
-        data = _build_status_data(agents)
-        if not data:
-            get_console().print(f"[yellow]{t('no_token_data')}[/yellow]")
-            return
-        render_status(**data)
-        return
-
-    rest_args, sort_key, sort_desc = _parse_sort_args(args[1:])
 
+def _select_agents(filter_agent: str | None):
+    agents = detect_agents()
+    if filter_agent is None:
+        return agents
+    matched = [agent for agent in agents if agent.id == filter_agent]
+    if matched:
+        return matched
+    flag = "--claude" if filter_agent == "claude-code" else "--codex"
+    get_console().print(f"[red]{t('agent_not_detected', flag=flag)}[/red]")
+    sys.exit(1)
+
+
+def _report_agents(agents, command: str, filter_agent: str | None):
+    """daily/weekly 在 Agent 会话内自动收窄；显式 filter 优先。"""
+    if filter_agent is not None or command not in ("daily", "weekly"):
+        return agents
+    session_agent = _current_session_agent()
+    if not session_agent or session_agent not in {agent.id for agent in agents}:
+        return agents
+    return [agent for agent in agents if agent.id == session_agent]
+
+
+def _run_report_command(command: str, args: list[str], agents, filter_agent: str | None) -> None:
+    rest_args, sort_key, sort_desc = _parse_sort_args(args)
     if command not in _REPORT_COMMANDS:
         get_console().print(f"[red]{t('unknown_cmd', cmd=command)}[/red]")
         get_console().print(f"[dim]{t('available_cmds')}[/dim]")
         sys.exit(1)
 
-    # daily / weekly 跟随当前会话：CC 会话只看 CC、Codex 会话只看 Codex；
-    # 独立终端（识别不到会话）保持合并所有 agent。显式 --claude / --codex 已在上面收窄 agents、优先级最高。
-    report_agents = agents
-    if filter_agent is None and command in ("daily", "weekly"):
-        session_agent = _current_session_agent()
-        if session_agent and session_agent in agent_ids:
-            report_agents = [a for a in agents if a.id == session_agent]
-    agent_names = [a.name for a in report_agents]
-
+    selected = _report_agents(agents, command, filter_agent)
+    agent_names = [agent.name for agent in selected]
     agg_fn, render_fn, time_attr, no_sort_attr, default_reverse = _REPORT_COMMANDS[command]
-    loaded = _load_per_agent(report_agents)
+    loaded = _load_per_agent(selected)
     stats = _aggregate_per_agent(loaded, agg_fn)
     default_attr = time_attr if sort_key == "time" else no_sort_attr
 
     if command == "sessions":
-        # sessions 看「最近的会话」：先过滤掉活跃 <5min 的碎片会话（与 tt status 同口径，
-        # 见 types.SessionStats.active_minutes），再按时间取最近 N 条（否则史上高 cost 会话
-        # 恒久霸榜、新会话和低成本 agent 永远进不了榜），这 N 条再按 cost（或 --sort）展示
-        kept = [s for s in stats if s.active_minutes >= 5]
-        kept.sort(key=lambda s: s.start_time, reverse=True)
-        shown = kept[:_parse_limit(rest_args, default=20)]
-        _apply_sort(shown, sort_key, sort_desc, default_attr, default_reverse)
-        render_sessions_view(_summary_from_sessions(shown), shown, agent_names)
+        _render_session_report(stats, rest_args, sort_key, sort_desc,
+                               default_attr, default_reverse, agent_names)
         return
 
     assert render_fn is not None  # sessions（render_fn=None）已在上面 return，其余命令都有渲染函数
     _apply_sort(stats, sort_key, sort_desc, default_attr, default_reverse)
     if command == "daily":
-        # daily 顶部三卡片：Last 12 months + This Month + This Week，跟 weekly/monthly 同款样式、
-        # 复用 _render_month_summary / _render_week_summary。weekly/monthly 聚合复用同一份 entries。
         render_fn(stats, agents=agent_names,
                   weekly=_aggregate_per_agent(loaded, aggregate_weekly),
                   monthly=_aggregate_per_agent(loaded, aggregate_monthly))
     elif command == "weekly":
         render_weekly(stats, agents=agent_names, daily=_aggregate_per_agent(loaded, aggregate_daily))
-    elif command == "monthly":
+    else:  # monthly
         render_monthly(stats, agents=agent_names,
                        daily=_aggregate_per_agent(loaded, aggregate_daily),
                        weekly=_aggregate_per_agent(loaded, aggregate_weekly))
-    else:
-        render_fn(stats, agents=agent_names)
+
+
+def _render_session_report(stats, rest_args: list[str], sort_key: str | None,
+                           sort_desc: bool | None, default_attr: str,
+                           default_reverse: bool, agent_names: list[str]) -> None:
+    # 先按时间取最近 N 条，再按用户指定字段展示；避免历史高 cost 会话长期霸榜。
+    kept = [session for session in stats if session.active_minutes >= 5]
+    kept.sort(key=lambda session: session.start_time, reverse=True)
+    try:
+        limit = _parse_limit(rest_args, default=20)
+    except ValueError as exc:
+        get_console().print(f"[red]{t('sessions_limit_invalid', value=exc.args[0])}[/red]")
+        sys.exit(1)
+    shown = kept[:limit]
+    _apply_sort(shown, sort_key, sort_desc, default_attr, default_reverse)
+    render_sessions_view(_summary_from_sessions(shown), shown, agent_names)
+
+
+def main():
+    # --mock：本地开发演示，加载 mock/ 假数据再走正常报表流程（mock/ 在 .gitignore）
+    if "--mock" in sys.argv:
+        sys.argv = [a for a in sys.argv if a != "--mock"]
+        _load_local_mock()
+
+    args = sys.argv[1:]
+    # --claude / --codex：多 agent 环境按需只看一个 agent 的报表（issue #19），互斥；不给则走默认
+    args, filter_agent = _extract_agent_arg(args)
+    # --theme NAME：临时覆盖主题（仅本次进程、不落配置/不重烘焙状态栏），对所有报表 + status 生效
+    args, theme_override = _extract_theme_arg(args)
+    _apply_theme_override(theme_override)
+    command = args[0] if args else "daily"
+
+    if _handle_non_data_command(command, args[1:]):
+        return
+
+    _ensure_data_ready()
+    agents = _select_agents(filter_agent)
+
+    if command in ("status", "dashboard"):
+        data = _build_status_data(agents)
+        if not data:
+            get_console().print(f"[yellow]{t('no_token_data')}[/yellow]")
+            return
+        render_status(**data)
+        return
+
+    if command == "sidebar":
+        _cmd_sidebar(agents, args[1:])
+        return
+    _run_report_command(command, args[1:], agents, filter_agent)
 
 
 if __name__ == "__main__":

{token_tracker-0.4.7 → token_tracker-0.4.9}/src/token_tracker/config.py

@@ -18,17 +18,21 @@ from .ui import themes
 CONFIG_DIR = os.path.expanduser("~/.config/token-tracker")
 CONFIG_PATH = os.path.join(CONFIG_DIR, "config.json")
 # CC statusline 缓存的单一权威路径（statusline 脚本写、tt status / adapters.rate_limits 读）。
-# 注意 templates/claude_statusline.py 因脚本独立运行硬编码了同一路径——改这里必须同步改模板。
+# 注意两个 statusline 模板因脚本独立运行硬编码了对应缓存路径——改这里必须同步改模板。
 STATUS_FILE = os.path.join(CONFIG_DIR, "tt-status.json")
+# Codex Stop hook 采集的会话→终端窗格映射。与 CC 心跳/status 缓存分文件，避免两个
+# Agent 并发 read-modify-write 同一 JSON 时互相覆盖；sidebar 读取时再合并。
+TERMINAL_MAP_FILE = os.path.join(CONFIG_DIR, "tt-terminal-map.json")
 SCHEMA_VERSION = 1
 
 # 引导版本：每次新增"值得让老用户重新走一遍 setup"的配置项时手动 +1（只能整数、一次 +1）。
 # 老用户 config 里没这字段 / 旧版本号 < 当前 → 触发重新引导（真终端弹 wizard、非 tty 静默 _auto_setup）。
 # 跟 SCHEMA_VERSION 解耦：那是数据格式版本，这是用户引导版本，bump 节奏完全不同。
 # 2（0.4.2）：强制所有现存用户（0.3.8/0.4.0=无字段=0、0.4.1=1，全 < 2）升级后重走一遍 setup。
+# 3：安装随包分发的用户级 Codex $tt-sidebar Skill + UserPromptSubmit hook。
 # 注：CC statusLine 变可选组件（issue #16/#17）时决定**不 bump**——小众需求不打断存量用户，
 # 存量 tt 用户 intent 缺失时由 is_setup 按「statusLine 已是 tt 的」推断为已配，想改的手动 tt setup。
-SETUP_VERSION = 2
+SETUP_VERSION = 3
 
 # 旧位置（独立 theme.json / lang.json），老用户首次读 config.json 不存在时自动合并迁移
 _LEGACY_THEME_PATH = os.path.join(CONFIG_DIR, "theme.json")