agentic-metric-x 0.2.1__tar.gz

agentic_metric_x-0.2.1/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build package
+        run: |
+          pip install build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

agentic_metric_x-0.2.1/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Virtualenvs
+.venv/
+venv/
+.env
+
+# Editor / IDE
+.vscode/
+.idea/
+*.swp
+
+# OS
+.DS_Store
+
+# Local data
+*.db
+
+# Tooling markers
+.codex
+.claude/

agentic_metric_x-0.2.1/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+## v0.2.1 (2026-04-24)
+
+Follow-up correctness fixes on top of v0.2.0.
+
+### Bug fixes
+
+- **Usage billing attribution**: per-session rows are now split into
+  `session_usage` per-day buckets so today/week/month rollups no longer
+  over-count cross-day sessions. `report` and the TUI both read from the
+  new bucketed view.
+- **Codex forked session accounting**: when Codex resumes or forks a
+  session it appends a new JSONL file that replays prior turns; the
+  collector now dedupes replayed events so the forked session does not
+  double-count the parent session's tokens.
+- **Backend usage accounting**: Claude Code and Codex collectors now
+  re-emit historical session totals on every sync (instead of only new
+  events), so pricing overrides and backfills consistently re-cost past
+  sessions. Aggregator queries and a large batch of tests were updated
+  alongside.
+
+## v0.2.0 (2026-04-23)
+
+Focused fork: supports **Codex** and **Claude Code** only, with
+redesigned TUI, a unified `report` command, and several calculation
+correctness fixes.
+
+### Breaking changes
+
+- Removed collectors: VS Code Copilot Chat, OpenCode, Qwen Code. If you
+  still need these, stay on v0.1.8 upstream.
+- Replaced `today` / `history` / `status` CLI commands with a single
+  `report` command:
+  `report [--today|--week|--month|--range FROM:TO]`.
+
+### Bug fixes
+
+- **Codex double-counting cached tokens**: OpenAI's `input_tokens` is
+  the total (including cached). The collector now stores
+  `input_tokens - cached_input_tokens`, so `estimate_cost` no longer
+  charges cached tokens at both input and cache-read pricing. This
+  dramatically lowers Codex session cost (observed -87% on a large
+  session with heavy prompt cache).
+- **Pricing prefix matching**: sort by prefix length descending, so
+  `gpt-5.4-mini` matches its own entry rather than `gpt-5.4`.
+- **Date aggregation timezone**: `date(started_at, 'localtime')` is
+  used everywhere, fixing UTC-vs-local off-by-one day in today / week /
+  month rollups.
+- **File truncation recovery**: if a JSONL file shrinks (truncated or
+  rewritten), the collector now re-parses from offset 0 instead of
+  silently skipping.
+- **`git_branch` upsert**: the branch column is now updated from later
+  syncs, not permanently pinned by the first insert.
+- **User-pricing I/O**: overrides are cached in memory keyed by file
+  mtime, avoiding a disk read on every cost estimation.
+
+### Pricing table
+
+- Added: `claude-opus-4-7`, `gpt-5.4` / `-mini` / `-nano` / `-pro`,
+  `gemini-3.1-pro`, `gemini-3.1-flash`.
+- Family fallback now splits `gpt-5` from generic `gpt-` so modern
+  5.x models pick up 5.x pricing.
+
+### TUI redesign
+
+- Top row: three summary cells — TODAY / WEEK / MONTH — switched with
+  `t` / `w` / `m`.
+- Active-now table stays compact; dim rows show today's idle sessions.
+- 30-day cost bar chart under the active table.
+- Agent × model nested breakdown with proportion bars, driven by the
+  currently-focused time range.
+- Subtle panel borders, muted titles, yellow cost highlights.
+
+## v0.1.8 (upstream baseline)
+
+- Multiple live sessions in the same directory detected separately.
+- Fix closed sessions being marked active via VS Code-specific fallback.

agentic_metric_x-0.2.1/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 MrQianjinsi
+Copyright (c) 2026 xihuai18
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentic_metric_x-0.2.1/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: agentic-metric-x
+Version: 0.2.1
+Summary: Minimal personal-usage monitor for Codex + Claude Code
+Project-URL: Homepage, https://github.com/xihuai18/agentic-metric
+Project-URL: Repository, https://github.com/xihuai18/agentic-metric
+Project-URL: Issues, https://github.com/xihuai18/agentic-metric/issues
+Author: xihuai18
+Author-email: MrQianjinsi <mrqianjinsi@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,claude-code,codex,coding-agent,metrics,tui
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: rich>=13.0.0
+Requires-Dist: textual-plotext>=0.3.0
+Requires-Dist: textual>=1.0.0
+Requires-Dist: typer>=0.9.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Agentic Metric
+
+[中文文档](README-CN.md)
+
+A local-only monitoring tool for AI coding agents — like `top`, but for your coding agents. Track token usage and costs across **Claude Code** and **Codex** — with a TUI dashboard and CLI.
+
+**Supported platforms: Linux and macOS.**
+
+**All data stays on your machine. No network requests, no telemetry, no data leaves your computer.** The tool only reads local agent data files (`~/.claude/`, `~/.codex/`) and process info.
+
+![Agentic Metric TUI](agentic-metric-screenshot.png)
+
+## Features
+
+- **Live monitoring** — Detect running agent processes, incremental JSONL session parsing
+- **Cost estimation** — Per-model pricing table with CLI management, calculates API-equivalent costs
+- **Unified report** — One `report` command for today / week / month / custom date range, with agent × model breakdown, top projects, top sessions, and hourly/daily/weekly heatmaps
+- **TUI dashboard** — Terminal UI with live refresh, stacked summary cells, heatmap strip, 30-day cost chart, and agent × model breakdown
+- **Multi-agent** — Plugin architecture; supports Claude Code and Codex today, extensible
+
+## Agent Data Coverage
+
+| Field | Claude Code | Codex |
+|-------|:-----------:|:-----:|
+| Session ID | ✓ | ✓ |
+| Project path | ✓ | ✓ |
+| Git branch | ✓ | ✓ |
+| Model | ✓ | ✓ |
+| Input tokens | ✓ | ✓ |
+| Output tokens | ✓ | ✓ |
+| Cache tokens | ✓ | ✓¹ |
+| User turns | ✓ | ✓ |
+| Message count | ✓ | ✓ |
+| First/last prompt | ✓ | ✓ |
+| Cost estimation | ✓ | ✓ |
+| Live active status | ✓ | ✓ |
+
+> ¹ Codex exposes cache-read tokens only; cache-write is not reported. Codex's
+> `input_tokens` already includes cached tokens, so the collector stores
+> `input_tokens − cached_input_tokens` to avoid double-charging at both input
+> and cache-read pricing.
+
+## Installation
+
+Requires Python 3.10+.
+
+```bash
+pip install agentic-metric-x
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uvx agentic-metric-x              # Run directly without installing
+uv tool install agentic-metric-x   # Or install persistently
+uv tool upgrade agentic-metric-x   # Upgrade to latest version
+```
+
+## Usage
+
+```bash
+agentic-metric                       # Launch TUI dashboard (default when no command given)
+agentic-metric tui                   # Launch TUI dashboard explicitly
+agentic-metric sync                  # Force sync collectors to the local database
+agentic-metric report --today        # Today's usage report
+agentic-metric report --week         # This week (Mon → today)
+agentic-metric report --month        # This month
+agentic-metric report --range 2026-04-01:2026-04-23   # Custom date range
+agentic-metric today                 # Shortcut for `report --today`
+agentic-metric week                  # Shortcut for `report --week`
+agentic-metric month                 # Shortcut for `report --month`
+agentic-metric history -d 30         # Last N days (default 14)
+agentic-metric pricing               # Manage model pricing
+```
+
+`report` shows a header with total cost / sessions / turns / tokens / cache-hit
+rate, a delta vs. the previous equivalent period, a heatmap strip (hours for
+`--today`, days for `--week`, weeks for `--month`), a 30-day cost chart, and
+breakdowns by agent × model, top projects, top sessions, and time buckets.
+
+### Pricing Management
+
+Model pricing is used for cost estimation. Builtin pricing is included for common models. You can add new models or override existing prices via CLI — overrides are stored in `$DATA/agentic_metric/pricing.json`.
+
+```bash
+agentic-metric pricing list                                                # List all model pricing
+agentic-metric pricing set deepseek-r2 -i 0.5 -o 2.0                       # Add a new model
+agentic-metric pricing set claude-opus-4-7 -i 4.0 -o 20.0 -cr 0.4 -cw 5.0  # Override builtin
+agentic-metric pricing reset deepseek-r2                                   # Reset a model to builtin default
+agentic-metric pricing reset --all                                         # Reset all overrides
+```
+
+For unknown models, pricing falls back by model family (e.g. `claude-sonnet-*` uses Sonnet pricing, `gpt-5*` uses GPT-5 pricing) before using the global default.
+
+### TUI Keybindings
+
+| Key | Action |
+|-----|--------|
+| `←` / `→` | Switch view (Today / Week / Month) |
+| `↑` / `↓` | Move time range earlier / later |
+| `.` | Jump back to "now" (reset offset) |
+| `t` / `w` / `m` | Focus Today / Week / Month directly |
+| `r` | Refresh data |
+| `q` | Quit |
+
+## Data Sources
+
+Paths differ by platform. `$DATA` refers to:
+
+| | Linux | macOS |
+|--|-------|-------|
+| `$DATA` | `~/.local/share` | `~/Library/Application Support` |
+
+| Agent | Path | Data |
+|-------|------|------|
+| Claude Code | `~/.claude/projects/` | JSONL sessions, token usage, model, branch |
+| Claude Code | `~/.claude/stats-cache.json` | Daily activity stats |
+| Claude Code | Process detection | Running status, working directory |
+| Codex | `~/.codex/sessions/` | JSONL sessions, token usage, model |
+| Codex | Process detection | Running status, working directory |
+
+Claude Code honors `CLAUDE_CONFIG_DIR` and Codex honors `CODEX_HOME` — if you
+have relocated either agent's config directory, the collectors pick up the
+environment variable automatically.
+
+All aggregated data is stored locally in `$DATA/agentic_metric/data.db` (SQLite).
+
+## Unsupported Agents
+
+- **Cursor** — Cursor stopped writing token usage data (`tokenCount`) to its local `state.vscdb` database around January 2026 (approximately version 2.0.63+). All `inputTokens`/`outputTokens` values are now zero. Cursor has moved usage tracking to a server-side system. Since this tool is designed to be fully offline with no network requests, monitoring Cursor usage is not supported.
+- **OpenCode / Qwen Code / VS Code Copilot Chat** — collectors for these
+  agents existed up to v0.1.8 and were removed in v0.2.0 as this fork narrowed
+  its focus to Claude Code and Codex. If you need them, stay on v0.1.8 from
+  upstream.
+
+## Privacy
+
+- **Fully offline** — no network requests, no data sent anywhere
+- **Read-only** — never modifies agent config or data files
+- All stats stored in a local SQLite database
+- Delete the data directory at any time to remove all data (`~/.local/share/agentic_metric/` on Linux, `~/Library/Application Support/agentic_metric/` on macOS)
+
+## Development
+
+```bash
+git clone https://github.com/xihuai18/agentic-metric
+cd agentic-metric
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+Forked from [MrQianjinsi/agentic-metric](https://github.com/MrQianjinsi/agentic-metric) (v0.1.8 upstream). See [CHANGELOG.md](CHANGELOG.md) for what changed in this fork.

agentic_metric_x-0.2.1/README-CN.md

@@ -0,0 +1,152 @@
+# Agentic Metric
+
+[English](README.md)
+
+本地化的 AI coding agent 指标监控工具 — 类似 `top`,但监控的是你的 coding agent。追踪 **Claude Code** 和 **Codex** 的 token 用量和成本,提供 TUI 仪表盘和 CLI 命令。
+
+**支持平台:Linux 和 macOS。**
+
+**所有数据完全存储在本地,使用过程不会联网。** 工具仅读取本机的 agent 数据文件(`~/.claude/`、`~/.codex/`)和进程信息,不发送任何数据到外部服务器。
+
+![Agentic Metric TUI](agentic-metric-screenshot.png)
+
+## 功能
+
+- **实时监控** — 检测运行中的 agent 进程,增量解析 JSONL 会话数据
+- **成本估算** — 基于各模型定价表计算 API 等效成本,支持 CLI 管理定价
+- **统一的用量报告** — 单个 `report` 命令覆盖今日 / 本周 / 本月 / 自定义区间,含 agent × model 明细、项目排行、会话排行、小时/天/周热图
+- **TUI 仪表盘** — 终端图形界面,实时刷新,含汇总卡片、热图条、30 天成本柱图、agent × model 分解
+- **多 Agent 支持** — 插件架构;目前支持 Claude Code 和 Codex,可扩展
+
+## 各 Agent 指标覆盖情况
+
+| 字段 | Claude Code | Codex |
+|------|:-----------:|:-----:|
+| 会话 ID | ✓ | ✓ |
+| 项目路径 | ✓ | ✓ |
+| Git 分支 | ✓ | ✓ |
+| 模型名称 | ✓ | ✓ |
+| Input tokens | ✓ | ✓ |
+| Output tokens | ✓ | ✓ |
+| Cache tokens | ✓ | ✓¹ |
+| 用户轮次 | ✓ | ✓ |
+| 消息总数 | ✓ | ✓ |
+| 首条/末条 prompt | ✓ | ✓ |
+| 成本估算 | ✓ | ✓ |
+| 实时活跃状态 | ✓ | ✓ |
+
+> ¹ Codex 仅暴露 cache-read tokens,cache-write 不上报。OpenAI 的 `input_tokens`
+> 字段本身包含了已缓存部分,collector 存储时会扣掉 `cached_input_tokens`,
+> 避免在 input 价和 cache-read 价上重复计费。
+
+## 安装
+
+需要 Python 3.10+。
+
+```bash
+pip install agentic-metric-x
+```
+
+或使用 [uv](https://docs.astral.sh/uv/):
+
+```bash
+uvx agentic-metric-x              # 直接运行,无需安装
+uv tool install agentic-metric-x   # 持久安装
+uv tool upgrade agentic-metric-x   # 升级到最新版
+```
+
+## 使用
+
+```bash
+agentic-metric                       # 启动 TUI 仪表盘(无参数时默认启动)
+agentic-metric tui                   # 显式启动 TUI 仪表盘
+agentic-metric sync                  # 强制同步各 collector 到本地数据库
+agentic-metric report --today        # 今日用量报告
+agentic-metric report --week         # 本周(周一至今)
+agentic-metric report --month        # 本月
+agentic-metric report --range 2026-04-01:2026-04-23   # 自定义日期区间
+agentic-metric today                 # `report --today` 的快捷方式
+agentic-metric week                  # `report --week` 的快捷方式
+agentic-metric month                 # `report --month` 的快捷方式
+agentic-metric history -d 30         # 最近 N 天(默认 14 天)
+agentic-metric pricing               # 管理模型定价
+```
+
+`report` 会输出:总成本 / sessions / 用户轮次 / tokens / 缓存命中率的汇总条,
+与上一同类周期的差额,一个热图条(`--today` 按小时、`--week` 按日、`--month`
+按周),30 天成本柱图,以及 agent × model、项目、会话、时间桶的明细表。
+
+### 定价管理
+
+模型定价用于成本估算。常见模型已内置定价,你可以通过 CLI 添加新模型或覆盖现有价格 — 用户自定义定价存储在 `$DATA/agentic_metric/pricing.json`。
+
+```bash
+agentic-metric pricing list                                                # 查看所有模型定价
+agentic-metric pricing set deepseek-r2 -i 0.5 -o 2.0                       # 添加新模型
+agentic-metric pricing set claude-opus-4-7 -i 4.0 -o 20.0 -cr 0.4 -cw 5.0  # 覆盖内置定价
+agentic-metric pricing reset deepseek-r2                                   # 恢复单个模型为内置默认
+agentic-metric pricing reset --all                                         # 恢复所有定价为默认
+```
+
+对于未知模型,会按模型族自动匹配定价(如 `claude-sonnet-*` 使用 Sonnet 定价,`gpt-5*` 使用 GPT-5 定价),最后才使用全局默认值。
+
+### TUI 快捷键
+
+| 键 | 功能 |
+|----|------|
+| `←` / `→` | 切换视图(Today / Week / Month) |
+| `↑` / `↓` | 时间范围往前 / 往后 |
+| `.` | 回到"现在"(清空 offset) |
+| `t` / `w` / `m` | 直接聚焦 Today / Week / Month |
+| `r` | 刷新数据 |
+| `q` | 退出 |
+
+## 数据来源
+
+数据路径因平台而异,下表中 `$DATA` 含义如下:
+
+| | Linux | macOS |
+|--|-------|-------|
+| `$DATA` | `~/.local/share` | `~/Library/Application Support` |
+
+| Agent | 数据路径 | 采集内容 |
+|-------|---------|---------|
+| Claude Code | `~/.claude/projects/` | JSONL 会话、token 用量、模型、分支 |
+| Claude Code | `~/.claude/stats-cache.json` | 每日活动统计 |
+| Claude Code | 进程检测 | 运行状态、工作目录 |
+| Codex | `~/.codex/sessions/` | JSONL 会话、token 用量、模型 |
+| Codex | 进程检测 | 运行状态、工作目录 |
+
+Claude Code 支持 `CLAUDE_CONFIG_DIR`,Codex 支持 `CODEX_HOME`,如果你改了
+这两个 agent 的配置目录,collector 会自动读取环境变量。
+
+所有数据汇总存储在 `$DATA/agentic_metric/data.db`(SQLite)。
+
+## 不支持的 Agent
+
+- **Cursor** — Cursor 自 2026 年 1 月左右(约 2.0.63+ 版本)起不再向本地 `state.vscdb` 数据库写入 token 用量数据(`tokenCount`),所有 `inputTokens`/`outputTokens` 值均为 0。Cursor 已将用量追踪迁移至服务端。由于本工具的设计原则是完全离线、不联网,无法通过网络 API 获取 Cursor 的用量数据,因此无法支持监测 Cursor 的用量。
+- **OpenCode / Qwen Code / VS Code Copilot Chat** — 这三个 collector 在
+  v0.1.8 之前存在,v0.2.0 起因本 fork 聚焦 Claude Code + Codex 而移除。
+  如果你仍需要这些 agent 的统计,请使用上游的 v0.1.8。
+
+## 隐私
+
+- 不联网,不发送任何数据
+- 不修改 agent 的配置或数据文件(只读)
+- 所有统计数据存储在本地 SQLite 数据库
+- 可随时删除数据目录清除所有数据(Linux: `~/.local/share/agentic_metric/`,macOS: `~/Library/Application Support/agentic_metric/`)
+
+## 开发
+
+```bash
+git clone https://github.com/xihuai18/agentic-metric
+cd agentic-metric
+pip install -e ".[dev]"
+pytest
+```
+
+## 许可证
+
+MIT — 详见 [LICENSE](LICENSE)。
+
+Fork 自 [MrQianjinsi/agentic-metric](https://github.com/MrQianjinsi/agentic-metric)(基于上游 v0.1.8)。本 fork 相对上游的变更见 [CHANGELOG.md](CHANGELOG.md)。

agentic_metric_x-0.2.1/README.md

@@ -0,0 +1,156 @@
+# Agentic Metric
+
+[中文文档](README-CN.md)
+
+A local-only monitoring tool for AI coding agents — like `top`, but for your coding agents. Track token usage and costs across **Claude Code** and **Codex** — with a TUI dashboard and CLI.
+
+**Supported platforms: Linux and macOS.**
+
+**All data stays on your machine. No network requests, no telemetry, no data leaves your computer.** The tool only reads local agent data files (`~/.claude/`, `~/.codex/`) and process info.
+
+![Agentic Metric TUI](agentic-metric-screenshot.png)
+
+## Features
+
+- **Live monitoring** — Detect running agent processes, incremental JSONL session parsing
+- **Cost estimation** — Per-model pricing table with CLI management, calculates API-equivalent costs
+- **Unified report** — One `report` command for today / week / month / custom date range, with agent × model breakdown, top projects, top sessions, and hourly/daily/weekly heatmaps
+- **TUI dashboard** — Terminal UI with live refresh, stacked summary cells, heatmap strip, 30-day cost chart, and agent × model breakdown
+- **Multi-agent** — Plugin architecture; supports Claude Code and Codex today, extensible
+
+## Agent Data Coverage
+
+| Field | Claude Code | Codex |
+|-------|:-----------:|:-----:|
+| Session ID | ✓ | ✓ |
+| Project path | ✓ | ✓ |
+| Git branch | ✓ | ✓ |
+| Model | ✓ | ✓ |
+| Input tokens | ✓ | ✓ |
+| Output tokens | ✓ | ✓ |
+| Cache tokens | ✓ | ✓¹ |
+| User turns | ✓ | ✓ |
+| Message count | ✓ | ✓ |
+| First/last prompt | ✓ | ✓ |
+| Cost estimation | ✓ | ✓ |
+| Live active status | ✓ | ✓ |
+
+> ¹ Codex exposes cache-read tokens only; cache-write is not reported. Codex's
+> `input_tokens` already includes cached tokens, so the collector stores
+> `input_tokens − cached_input_tokens` to avoid double-charging at both input
+> and cache-read pricing.
+
+## Installation
+
+Requires Python 3.10+.
+
+```bash
+pip install agentic-metric-x
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uvx agentic-metric-x              # Run directly without installing
+uv tool install agentic-metric-x   # Or install persistently
+uv tool upgrade agentic-metric-x   # Upgrade to latest version
+```
+
+## Usage
+
+```bash
+agentic-metric                       # Launch TUI dashboard (default when no command given)
+agentic-metric tui                   # Launch TUI dashboard explicitly
+agentic-metric sync                  # Force sync collectors to the local database
+agentic-metric report --today        # Today's usage report
+agentic-metric report --week         # This week (Mon → today)
+agentic-metric report --month        # This month
+agentic-metric report --range 2026-04-01:2026-04-23   # Custom date range
+agentic-metric today                 # Shortcut for `report --today`
+agentic-metric week                  # Shortcut for `report --week`
+agentic-metric month                 # Shortcut for `report --month`
+agentic-metric history -d 30         # Last N days (default 14)
+agentic-metric pricing               # Manage model pricing
+```
+
+`report` shows a header with total cost / sessions / turns / tokens / cache-hit
+rate, a delta vs. the previous equivalent period, a heatmap strip (hours for
+`--today`, days for `--week`, weeks for `--month`), a 30-day cost chart, and
+breakdowns by agent × model, top projects, top sessions, and time buckets.
+
+### Pricing Management
+
+Model pricing is used for cost estimation. Builtin pricing is included for common models. You can add new models or override existing prices via CLI — overrides are stored in `$DATA/agentic_metric/pricing.json`.
+
+```bash
+agentic-metric pricing list                                                # List all model pricing
+agentic-metric pricing set deepseek-r2 -i 0.5 -o 2.0                       # Add a new model
+agentic-metric pricing set claude-opus-4-7 -i 4.0 -o 20.0 -cr 0.4 -cw 5.0  # Override builtin
+agentic-metric pricing reset deepseek-r2                                   # Reset a model to builtin default
+agentic-metric pricing reset --all                                         # Reset all overrides
+```
+
+For unknown models, pricing falls back by model family (e.g. `claude-sonnet-*` uses Sonnet pricing, `gpt-5*` uses GPT-5 pricing) before using the global default.
+
+### TUI Keybindings
+
+| Key | Action |
+|-----|--------|
+| `←` / `→` | Switch view (Today / Week / Month) |
+| `↑` / `↓` | Move time range earlier / later |
+| `.` | Jump back to "now" (reset offset) |
+| `t` / `w` / `m` | Focus Today / Week / Month directly |
+| `r` | Refresh data |
+| `q` | Quit |
+
+## Data Sources
+
+Paths differ by platform. `$DATA` refers to:
+
+| | Linux | macOS |
+|--|-------|-------|
+| `$DATA` | `~/.local/share` | `~/Library/Application Support` |
+
+| Agent | Path | Data |
+|-------|------|------|
+| Claude Code | `~/.claude/projects/` | JSONL sessions, token usage, model, branch |
+| Claude Code | `~/.claude/stats-cache.json` | Daily activity stats |
+| Claude Code | Process detection | Running status, working directory |
+| Codex | `~/.codex/sessions/` | JSONL sessions, token usage, model |
+| Codex | Process detection | Running status, working directory |
+
+Claude Code honors `CLAUDE_CONFIG_DIR` and Codex honors `CODEX_HOME` — if you
+have relocated either agent's config directory, the collectors pick up the
+environment variable automatically.
+
+All aggregated data is stored locally in `$DATA/agentic_metric/data.db` (SQLite).
+
+## Unsupported Agents
+
+- **Cursor** — Cursor stopped writing token usage data (`tokenCount`) to its local `state.vscdb` database around January 2026 (approximately version 2.0.63+). All `inputTokens`/`outputTokens` values are now zero. Cursor has moved usage tracking to a server-side system. Since this tool is designed to be fully offline with no network requests, monitoring Cursor usage is not supported.
+- **OpenCode / Qwen Code / VS Code Copilot Chat** — collectors for these
+  agents existed up to v0.1.8 and were removed in v0.2.0 as this fork narrowed
+  its focus to Claude Code and Codex. If you need them, stay on v0.1.8 from
+  upstream.
+
+## Privacy
+
+- **Fully offline** — no network requests, no data sent anywhere
+- **Read-only** — never modifies agent config or data files
+- All stats stored in a local SQLite database
+- Delete the data directory at any time to remove all data (`~/.local/share/agentic_metric/` on Linux, `~/Library/Application Support/agentic_metric/` on macOS)
+
+## Development
+
+```bash
+git clone https://github.com/xihuai18/agentic-metric
+cd agentic-metric
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+Forked from [MrQianjinsi/agentic-metric](https://github.com/MrQianjinsi/agentic-metric) (v0.1.8 upstream). See [CHANGELOG.md](CHANGELOG.md) for what changed in this fork.