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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: token-tracker
-Version: 0.4.7
+Version: 0.4.8
 Summary: Track token usage across local AI agents (Claude Code, Codex)
 Author-email: stormzhang <stormzhang.dev@gmail.com>
 License: MIT License
@@ -43,10 +43,13 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: rich>=13.7
 Requires-Dist: questionary<3,>=2.0
+Requires-Dist: textual>=1.0
 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 +70,7 @@ Dynamic: license-file
 
 - **多 Agent 统一追踪** — Claude Code + Codex 统一读取，多 Agent 按来源分组
 - **状态栏集成** — Claude Code 用官方 StatusLine 接口；**Codex 业界首创伪 statusline 方案**（hook 注入两行真彩色状态栏，把官方未开放的能力在 Codex 里做了出来）
+- **实时侧边栏** — `tt sidebar` 窄窗格常驻面板：全部活跃会话一屏总览（状态灯 + 最近提示词 + 「下一步」建议），点击会话直达对应 iTerm2 / tmux 窗格
 - **限额监控** — 实时 5h / 7d 配额百分比 + 重置倒计时
 - **多维成本分析** — 会话 / 日 / 周 / 月多维报表，等效成本统计
 - **定价识别** — litellm 在线定价 + 内置官方价双层兜底，覆盖 Claude / OpenAI / Gemini / Grok 及国产主流（Kimi / GLM / Qwen / 豆包 / DeepSeek / MiniMax / MiMo）；新模型自动套用同系列定价、不静默归零
@@ -124,7 +128,7 @@ Codex 官方暂不支持自定义 StatusLine。Token Tracker 通过 hook 注入
 
 ## 报表速览
 
-`tt status` — 过去 5h 实时面板（合并概览 + 5h/7d 额度 + 近期会话）
+`tt status` — 今日实时面板（今日合并概览 + 5h/7d 额度 + 今日会话）
 
 ![Status](assets/screenshot.png)
 
@@ -140,6 +144,19 @@ 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。
+
 ## 安装
 
 ```bash
@@ -164,10 +181,11 @@ curl -sSL https://raw.githubusercontent.com/stormzhang/token-tracker/main/instal
 tt setup          # 交互配置向导（终端：上下键选语言 / 主题 / 各组件）；非 tty 环境按推荐默认自动配置
 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.8}/README.md

@@ -14,6 +14,7 @@
 
 - **多 Agent 统一追踪** — Claude Code + Codex 统一读取，多 Agent 按来源分组
 - **状态栏集成** — Claude Code 用官方 StatusLine 接口；**Codex 业界首创伪 statusline 方案**（hook 注入两行真彩色状态栏，把官方未开放的能力在 Codex 里做了出来）
+- **实时侧边栏** — `tt sidebar` 窄窗格常驻面板：全部活跃会话一屏总览（状态灯 + 最近提示词 + 「下一步」建议），点击会话直达对应 iTerm2 / tmux 窗格
 - **限额监控** — 实时 5h / 7d 配额百分比 + 重置倒计时
 - **多维成本分析** — 会话 / 日 / 周 / 月多维报表，等效成本统计
 - **定价识别** — litellm 在线定价 + 内置官方价双层兜底，覆盖 Claude / OpenAI / Gemini / Grok 及国产主流（Kimi / GLM / Qwen / 豆包 / DeepSeek / MiniMax / MiMo）；新模型自动套用同系列定价、不静默归零
@@ -71,7 +72,7 @@ Codex 官方暂不支持自定义 StatusLine。Token Tracker 通过 hook 注入
 
 ## 报表速览
 
-`tt status` — 过去 5h 实时面板（合并概览 + 5h/7d 额度 + 近期会话）
+`tt status` — 今日实时面板（今日合并概览 + 5h/7d 额度 + 今日会话）
 
 ![Status](assets/screenshot.png)
 
@@ -87,6 +88,19 @@ 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。
+
 ## 安装
 
 ```bash
@@ -111,10 +125,11 @@ curl -sSL https://raw.githubusercontent.com/stormzhang/token-tracker/main/instal
 tt setup          # 交互配置向导（终端：上下键选语言 / 主题 / 各组件）；非 tty 环境按推荐默认自动配置
 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.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "token-tracker"
-version = "0.4.7"
+version = "0.4.8"
 description = "Track token usage across local AI agents (Claude Code, Codex)"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -28,14 +28,18 @@ dependencies = [
     "rich>=13.7",
     # wizard 补丁挂在 questionary 私有内部（InquirerControl._get_choice_tokens 等），锁大版本防破坏
     "questionary>=2.0,<3",
+    # 仅 tt sidebar live 模式用（cli 延迟 import，日常 tt 启动不加载）；与 rich 同门，渲染对象直接复用
+    "textual>=1.0",
 ]
 
 [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",
 ]
@@ -68,6 +72,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.8}/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.8}/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.8}/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.8}/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.8}/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.8}/src/token_tracker/config.py

@@ -18,8 +18,11 @@ 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）。

{token_tracker-0.4.7 → token_tracker-0.4.8}/src/token_tracker/hooks.py

@@ -38,8 +38,9 @@ CODEX_DIR = _CODEX
 CODEX_CONFIG = os.path.join(CODEX_DIR, "config.toml")     # 改 Codex 配置，留 agent 目录
 CODEX_STATUSLINE_HOOK_PATH = os.path.join(_TT, "codex-statusline.py")
 STATUS_FILE = config.STATUS_FILE                          # CC statusline 缓存（单一权威定义在 config）
-HOOK_VERSION = "1.8"
-STATUSLINE_HOOK_VERSION = "1.1"
+TERMINAL_MAP_FILE = config.TERMINAL_MAP_FILE              # Codex Stop hook 采集的终端定位映射
+HOOK_VERSION = "2.1"  # 2.0: 采集 _terminal_map（sidebar 点击跳转）；2.1: 共享状态无条件随帧携带、防异常帧清表
+STATUSLINE_HOOK_VERSION = "1.2"  # 1.2: 采集 Codex 会话终端定位，供 tt sidebar 点击跳转
 
 CC_BACKUP_PATH = os.path.join(_TT, "cc-backup.json")
 CODEX_BACKUP_LEGACY = os.path.join(_TT, "codex-backup.json")  # 老用户残留，unsetup 时还能恢复
@@ -162,6 +163,8 @@ def _uninstall_codex_statusline(content: str) -> str:
     """删 Codex statusline 脚本 + 从 content 移除 tt 追加的 Stop hook 段（不动用户其它）。"""
     if os.path.exists(CODEX_STATUSLINE_HOOK_PATH):
         os.remove(CODEX_STATUSLINE_HOOK_PATH)
+    if os.path.exists(TERMINAL_MAP_FILE):
+        os.remove(TERMINAL_MAP_FILE)
     return _CODEX_STATUSLINE_REGEX.sub("\n", content)
 
 

{token_tracker-0.4.7 → token_tracker-0.4.8}/src/token_tracker/i18n.py

@@ -10,7 +10,24 @@ _STRINGS = {
         "unknown_cmd": "未知命令: {cmd}",
         "agent_filter_conflict": "--claude 与 --codex 互斥，只能指定其中一个",
         "agent_not_detected": "未检测到 {flag} 的使用数据，请先在该 agent 中使用后再查询",
-        "available_cmds": "可用命令: status, daily, weekly, monthly, sessions, theme, setup, unsetup, --version",
+        "sessions_limit_invalid": "会话条数必须是正整数，收到: {value}",
+        "available_cmds": "可用命令: status, daily, weekly, monthly, sessions, sidebar, theme, setup, unsetup, --version",
+        # --- sidebar（cli.py / ui/sidebar.py）---
+        "sidebar_empty": "窗口期内没有活跃会话",
+        "sidebar_waiting_prompt": "等待当前会话的第一条提示词…",
+        "sidebar_state_running": "运行中",
+        "sidebar_state_attention": "待确认",
+        "sidebar_state_waiting": "等输入",
+        "sidebar_state_idle": "空闲",
+        "sidebar_jump_no_target": "该会话暂无终端定位（其状态栏渲染过一帧后才有）",
+        "sidebar_jump_failed": "跳转失败: {err}",
+        "sidebar_next": "下一步",
+        "sidebar_active_count": "最近活跃会话 {n} 条",
+        "sidebar_tz_bj": "北京",
+        "sidebar_tz_la": "洛杉矶",
+        "sidebar_tz_ldn": "伦敦",
+        "sidebar_jump_gone": "目标终端窗格不存在（可能已关闭）",
+        "sidebar_update_hint": "Claude Code 版本较旧，无法识别已关闭的会话，建议升级",
         # --- status.py（会话表列名与 tips）---
         "recent_sessions": "最近会话",
         "sessions_tips": "Tips: tt sessions <N> 调数量 · --sort cost|tokens|time|messages · --asc/--desc 改排序",
@@ -41,7 +58,6 @@ _STRINGS = {
         "theme_usage": "用法: tt theme [show | list | set <主题名> | preview <主题名>]",
         # --- wizard (wizard.py) ---
         "wizard_pick_theme": "选择配色主题",
-        "wizard_theme_prompt": "选择主题",
         "wizard_q_cc_statusline": "接管 Claude Code 状态栏",
         "wizard_q_codex_statusline": "启用 Codex 伪 statusline",
         "theme_recommended": "（推荐）",
@@ -86,7 +102,24 @@ _STRINGS = {
         "unknown_cmd": "Unknown command: {cmd}",
         "agent_filter_conflict": "--claude and --codex are mutually exclusive; please pick one",
         "agent_not_detected": "No usage data for {flag}; use it in that agent first, then query again",
-        "available_cmds": "Available commands: status, daily, weekly, monthly, sessions, theme, setup, unsetup, --version",
+        "sessions_limit_invalid": "Session count must be a positive integer, got: {value}",
+        "available_cmds": "Available commands: status, daily, weekly, monthly, sessions, sidebar, theme, setup, unsetup, --version",
+        # --- sidebar（cli.py / ui/sidebar.py）---
+        "sidebar_empty": "No active sessions in the window",
+        "sidebar_waiting_prompt": "Waiting for the first prompt in this session…",
+        "sidebar_state_running": "running",
+        "sidebar_state_attention": "needs you",
+        "sidebar_state_waiting": "awaiting input",
+        "sidebar_state_idle": "idle",
+        "sidebar_jump_no_target": "No terminal mapping for this session yet (appears after its statusline renders a frame)",
+        "sidebar_jump_failed": "Jump failed: {err}",
+        "sidebar_next": "Next",
+        "sidebar_active_count": "{n} active sessions",
+        "sidebar_tz_bj": "Beijing",
+        "sidebar_tz_la": "LA",
+        "sidebar_tz_ldn": "London",
+        "sidebar_jump_gone": "Target terminal pane no longer exists (probably closed)",
+        "sidebar_update_hint": "Claude Code is too old to detect closed sessions; consider updating",
         # --- status.py（会话表列名与 tips）---
         "recent_sessions": "Recent Sessions",
         "sessions_tips": "Tips: tt sessions <N> for count · --sort cost|tokens|time|messages · --asc/--desc to sort",
@@ -117,7 +150,6 @@ _STRINGS = {
         "theme_usage": "Usage: tt theme [show | list | set <name> | preview <name>]",
         # --- wizard (wizard.py) ---
         "wizard_pick_theme": "Pick a theme",
-        "wizard_theme_prompt": "Pick a theme",
         "wizard_q_cc_statusline": "Take over Claude Code status line",
         "wizard_q_codex_statusline": "Enable Codex faux statusline",
         "theme_recommended": "(recommended)",