luoyuctl · luoyuctl · May 4, 2026
diff --git a/README.md b/README.md
@@ -5,7 +5,7 @@
 <h1 align="center">AgentTrace</h1>
 
 <p align="center">
-  Review AI coding agent history across cost, tokens, and time, then find why a run was slow.
+  Find which AI coding agent burned your tokens, what it cost, and why the run got slow.
 </p>
 
 <p align="center">
@@ -31,6 +31,8 @@
 
 **agenttrace** is a local TUI and report generator for AI coding agent session history. It reads Claude Code, Codex CLI, Gemini CLI, Qwen Code, Cursor, Aider, OpenCode, OpenClaw, Hermes Agent, Kimi CLI, and Copilot-style logs, then helps with two daily jobs: see what multiple agents spent across cost, tokens, and time; and diagnose why a task ran slowly.
 
+Think of it as a local cost explorer and slow-run debugger for coding agents.
+
 ## Why agenttrace?
 
 AI coding agents now behave like small build systems: they call tools, retry, stall, and spend tokens while you only see the final answer.
@@ -44,6 +46,16 @@ It helps you answer:
 - **What should I inspect first?** Rank sessions by cost, duration, turns, health, failures, anomalies, model, source, or text search.
 - **Can I inspect this privately?** Everything runs locally; prompts, code, and logs do not need to leave your machine.
 
+## 60-second proof
+
+```bash
+agenttrace --doctor
+agenttrace --overview -f json
+agenttrace
+```
+
+On a real local machine, agenttrace found `1,707` reportable sessions, `8.68B` tokens, `$4,716.31` estimated cost, and `35` critical sessions without uploading prompts or code.
+
 ## Real local run
 
 These screenshots were captured from a local run against real session logs. They are not `--demo` output and not test fixtures.
@@ -84,6 +96,7 @@ curl -sL https://raw.githubusercontent.com/luoyuctl/agenttrace/master/install.sh
 Other install paths:
 
 ```bash
+npm install -g agenttrace
 brew install luoyuctl/tap/agenttrace
 go install github.com/luoyuctl/agenttrace/cmd/agenttrace@latest
 ```
@@ -94,8 +107,6 @@ Windows:
 iwr -useb https://raw.githubusercontent.com/luoyuctl/agenttrace/master/install.ps1 | iex
 ```
 
-The npm wrapper is prepared in `npm/`, but the public package is not published yet.
-
 ## Common workflows
 
 ```bash
@@ -138,9 +149,11 @@ Claude Code, Codex CLI, Gemini CLI, Qwen Code, Cline, Aider, Cursor exports, Her
 
 - Site: https://luoyuctl.github.io/agenttrace/
 - Sample HTML report: https://luoyuctl.github.io/agenttrace/demo-report.html
+- Comparison: [docs/comparison.md](docs/comparison.md)
 - CI setup: [docs/ci-integration.md](docs/ci-integration.md)
 - Cursor import: [docs/cursor-import.md](docs/cursor-import.md)
 - Parser guide: [docs/parser-guide.md](docs/parser-guide.md)
+- Roadmap: [ROADMAP.md](ROADMAP.md)
 - Launch notes: [docs/launch-kit.md](docs/launch-kit.md)
 
 Listed in [Awesome Gemini CLI](https://github.com/Piebald-AI/awesome-gemini-cli), [Charm in the Wild](https://github.com/charm-and-friends/charm-in-the-wild), and [Awesome Claude Code and Skills](https://github.com/GetBindu/awesome-claude-code-and-skills).

diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -5,7 +5,7 @@
 <h1 align="center">AgentTrace</h1>
 
 <p align="center">
-  汇总多个 AI 编程 Agent 的历史成本、Token 和耗时，并定位任务为什么跑得慢。
+  找出哪个 AI 编程 Agent 最烧 Token、花了多少钱，以及任务为什么跑得慢。
 </p>
 
 <p align="center">
@@ -31,6 +31,8 @@
 
 **agenttrace** 是一个本地 TUI 和报告生成工具，用来分析 AI 编程 Agent 的历史会话。它会读取 Claude Code、Codex CLI、Gemini CLI、Qwen Code、Cursor、Aider、OpenCode、OpenClaw、Hermes Agent、Kimi CLI 和 Copilot 风格日志，主要帮你做两件事：汇总多个 Agent 历史会话的成本、Token 和耗时；定位某次任务为什么跑得慢。
 
+可以把它理解成 AI 编程 Agent 的本地成本账单 + 慢任务调试器。
+
 ## 为什么需要 agenttrace？
 
 AI 编程 Agent 越来越像一套小型构建系统：会调用工具、重试、卡住、花 token，但你最后往往只看到一段总结。
@@ -44,6 +46,16 @@ AI 编程 Agent 越来越像一套小型构建系统：会调用工具、重试
 - **先看哪一次？** 按成本、耗时、轮次、健康分、失败、异常、模型、来源或文本搜索排序。
 - **能不能本地看？** 所有分析都在本机完成，不需要上传 prompt、代码和日志。
 
+## 60 秒看价值
+
+```bash
+agenttrace --doctor
+agenttrace --overview -f json
+agenttrace
+```
+
+一次真实本机运行中，agenttrace 找到了 `1,707` 个可报告会话、`8.68B` Token、`$4,716.31` 估算成本和 `35` 个 Critical 会话，全程不上传 prompt 和代码。
+
 ## 真实本机运行
 
 ```bash
@@ -67,6 +79,7 @@ curl -sL https://raw.githubusercontent.com/luoyuctl/agenttrace/master/install.sh
 其它安装方式：
 
 ```bash
+npm install -g agenttrace
 brew install luoyuctl/tap/agenttrace
 go install github.com/luoyuctl/agenttrace/cmd/agenttrace@latest
 ```
@@ -113,9 +126,11 @@ Claude Code、Codex CLI、Gemini CLI、Qwen Code、Cline、Aider、Cursor export
 - 官网：https://luoyuctl.github.io/agenttrace/
 - AI Agent 可观测性指南：https://luoyuctl.github.io/agenttrace/ai-agent-observability.html
 - 示例 HTML 报告：https://luoyuctl.github.io/agenttrace/demo-report.html
+- 对比说明：[docs/comparison.md](docs/comparison.md)
 - CI 集成：[docs/ci-integration.md](docs/ci-integration.md)
 - Cursor 导入：[docs/cursor-import.md](docs/cursor-import.md)
 - Parser 指南：[docs/parser-guide.md](docs/parser-guide.md)
+- 路线图：[ROADMAP.md](ROADMAP.md)
 - 发布说明草案：[docs/launch-kit.md](docs/launch-kit.md)
 
 agenttrace 已被收录在 [Awesome Gemini CLI](https://github.com/Piebald-AI/awesome-gemini-cli)、[Charm in the Wild](https://github.com/charm-and-friends/charm-in-the-wild) 和 [Awesome Claude Code and Skills](https://github.com/GetBindu/awesome-claude-code-and-skills)。

diff --git a/ROADMAP.md b/ROADMAP.md
@@ -0,0 +1,46 @@
+# agenttrace roadmap
+
+agenttrace is focused on two jobs:
+
+1. Review AI coding agent history across cost, tokens, and elapsed time.
+2. Diagnose why an agent task ran slowly.
+
+This roadmap keeps the project pointed at those jobs instead of becoming a generic observability dashboard.
+
+## Now
+
+- Rework the overview around spend, tokens, time, and slow-run triage.
+- Improve the large-history loading state so users can see source counts, cache hits, and parsing progress.
+- Turn the detail page into a diagnosis-first layout with issue, impact, evidence, next action, and confidence.
+- Strengthen diagnostics around slow tools, hanging gaps, retry loops, large params, and context pressure.
+- Make diff explain why one run is slower, costlier, or lower quality.
+
+Tracked issues:
+
+- [#142](https://github.com/luoyuctl/agenttrace/issues/142) Rework overview around spend, tokens, time, and slow-run triage
+- [#143](https://github.com/luoyuctl/agenttrace/issues/143) Improve large-history loading state and cache progress
+- [#145](https://github.com/luoyuctl/agenttrace/issues/145) Turn detail view into a diagnosis-first layout
+- [#146](https://github.com/luoyuctl/agenttrace/issues/146) Strengthen diagnostics as a slow-run analyzer
+- [#147](https://github.com/luoyuctl/agenttrace/issues/147) Make diff view explain why one run is slower or costlier
+
+## Next
+
+- Add reproducible slow-run fixtures that demonstrate expensive, slow, hanging, and context-heavy sessions.
+- Add per-agent guides for Claude Code, Codex CLI, Gemini CLI, Cursor, Aider, OpenCode, and Hermes Agent.
+- Improve parser contribution ergonomics with a small scaffold/template and a clearer parser contract.
+- Publish more shareable reports and screenshots from redacted local runs.
+- Expand install coverage and keep npm, Homebrew, Go install, and shell installers aligned.
+
+## Later
+
+- Add a dedicated "top slow sessions" workflow.
+- Add local report comparison across time windows.
+- Add optional team-oriented rollups that can be exported without uploading private logs.
+- Explore plugin-style parsers if third-party session formats keep changing.
+
+## Non-goals
+
+- Hosted prompt storage.
+- Billing-grade invoice reconciliation.
+- Replacing agent chat UIs.
+- Live tracing while a model is streaming.
diff --git a/docs/comparison.md b/docs/comparison.md
@@ -0,0 +1,58 @@
+# agenttrace comparison
+
+agenttrace is not another chat UI. It is a local session-history dashboard for people who already use AI coding agents and need to understand cost, token usage, elapsed time, and slow runs across tools.
+
+## What agenttrace is for
+
+Use agenttrace when you want to answer:
+
+- Which agent sessions spent the most cost, tokens, and time?
+- Which runs were slow because of long gaps, slow tools, retry loops, large parameters, or context pressure?
+- Which session should I inspect first?
+- Can I generate local JSON, Markdown, or HTML evidence without uploading private prompts and code?
+
+## Alternatives and adjacent tools
+
+| Option | Best for | Gap agenttrace fills |
+|---|---|---|
+| Raw JSONL / local log files | Exact source-of-truth inspection | Aggregates many files into ranked sessions, costs, health, latency, and diagnostics |
+| IDE or agent chat history | Reading one conversation | Compares sessions across agents, models, costs, tokens, and slow-run signals |
+| Token counters / cost-only scripts | Quick spend estimate | Adds time, latency, tool failures, anomalies, context pressure, and TUI triage |
+| CI logs | Build outcome evidence | Adds agent-session health gates and self-contained reports |
+| Hosted observability tools | Centralized team dashboards | Keeps prompts, code, and logs local by default |
+
+## Feature matrix
+
+| Capability | agenttrace | Raw logs | Agent UI history | Cost-only scripts | Hosted dashboards |
+|---|---:|---:|---:|---:|---:|
+| Multi-agent local discovery | Yes | Manual | No | Varies | Varies |
+| Cost and token totals | Yes | Manual | Varies | Yes | Yes |
+| Elapsed time and latency signals | Yes | Manual | Varies | No | Varies |
+| Slow tool and hanging-session diagnosis | Yes | Manual | No | No | Varies |
+| Context pressure and large parameter hints | Yes | Manual | No | No | Varies |
+| Ranked session triage | Yes | No | No | No | Varies |
+| Local TUI | Yes | No | No | No | No |
+| JSON / Markdown / HTML export | Yes | No | No | Varies | Varies |
+| CI health gates | Yes | No | No | Varies | Varies |
+| No hosted backend required | Yes | Yes | Yes | Yes | No |
+
+## When not to use agenttrace
+
+agenttrace is probably not the right tool if you need:
+
+- a hosted multi-user SaaS dashboard
+- live tracing while an agent is still streaming
+- full prompt search across every private log
+- billing-grade accounting from provider invoices
+
+It is intentionally a local-first developer tool for post-run inspection.
+
+## Positioning
+
+Short version:
+
+> agenttrace is a local cost explorer and slow-run debugger for AI coding agents.
+
+Longer version:
+
+> agenttrace reads the session files your coding agents already write, ranks the runs that burned cost, tokens, and time, then shows why a task was slow with evidence like long gaps, slow tools, retry loops, large params, and context pressure.
diff --git a/npm/README.md b/npm/README.md
@@ -1,27 +1,28 @@
 # agenttrace
 
-TUI observability for AI coding agent sessions. It helps you inspect local agent runs across cost, token usage, latency, tool failures, anomalies, health score, and CI quality gates.
+Local-first AI coding agent session history for cost, tokens, time, and slow-run diagnosis.
 
-This directory contains the npm wrapper for agenttrace. The public npm package has not been published yet, so `npm install -g agenttrace` will return a registry 404 until the first publish.
+Use it to answer two questions:
 
-## Install
+- Which coding agent sessions burned the most cost, tokens, and wall-clock time?
+- Why did a specific agent task run slowly?
 
-Use one of the supported install methods for now:
+## Install
 
 ```bash
-brew install luoyuctl/tap/agenttrace
+npm install -g agenttrace
 agenttrace --version
 ```
 
+Other install methods:
+
 ```bash
 curl -fsSL https://raw.githubusercontent.com/luoyuctl/agenttrace/master/install.sh | sh
 agenttrace --version
 ```
 
-After the package is published, the npm install path will be:
-
 ```bash
-npm install -g agenttrace
+brew install luoyuctl/tap/agenttrace
 agenttrace --version
 ```
 
@@ -43,15 +44,15 @@ npm pack --dry-run
 # Open the TUI
 agenttrace
 
-# Try built-in sample sessions
-agenttrace --demo
-
 # Diagnose local session discovery and cache status
 agenttrace --doctor
 
 # JSON overview for automation
 agenttrace --overview -f json
 
+# Try built-in sample sessions if this machine has no local agent logs yet
+agenttrace --demo
+
 # CI health gate
 agenttrace --overview --fail-under-health 80 --fail-on-critical --max-tool-fail-rate 15
 ```

diff --git a/npm/package.json b/npm/package.json
@@ -3,9 +3,16 @@
   "version": "0.4.0",
   "description": "Local-first AI coding agent session history for cost, tokens, time, and slow-run diagnosis",
   "main": "install.js",
+  "homepage": "https://luoyuctl.github.io/agenttrace/",
+  "bugs": {
+    "url": "https://github.com/luoyuctl/agenttrace/issues"
+  },
   "bin": {
     "agenttrace": "run.js"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "files": [
     "install.js",
     "run.js",

diff --git a/site/index.html b/site/index.html
@@ -65,6 +65,7 @@
         <a href="#evidence">Evidence</a>
         <a href="#workflow">Workflow</a>
         <a href="ai-agent-observability.html">Guide</a>
+        <a href="https://github.com/luoyuctl/agenttrace/blob/master/docs/comparison.md">Compare</a>
         <a href="demo-report.html">Report</a>
         <a href="#install">Install</a>
         <a href="https://github.com/luoyuctl/agenttrace/discussions/2">Feedback</a>
@@ -88,6 +89,7 @@ <h1>See what your agents spent, then find why they slowed down.</h1>
               Copy install
             </button>
             <a href="demo-report.html">View sample report</a>
+            <a href="https://github.com/luoyuctl/agenttrace/blob/master/docs/comparison.md">Compare options</a>
             <a href="ai-agent-observability.html">Read the guide</a>
             <a href="https://github.com/luoyuctl/agenttrace/releases/latest">Latest release</a>
           </div>
@@ -211,6 +213,7 @@ <h2>Built in the open for agent operators.</h2>
           <a href="https://github.com/luoyuctl/agenttrace">View source</a>
           <a href="https://github.com/luoyuctl/agenttrace/discussions/2">Share feedback</a>
           <a href="https://github.com/luoyuctl/agenttrace/blob/master/docs/launch-kit.md">Launch kit</a>
+          <a href="https://github.com/luoyuctl/agenttrace/blob/master/ROADMAP.md">Roadmap</a>
           <a href="ai-agent-observability.html">AI observability guide</a>
           <a href="https://github.com/luoyuctl/agenttrace/releases/latest">Release notes</a>
         </div>
@@ -222,6 +225,7 @@ <h2>Built in the open for agent operators.</h2>
       <a href="https://github.com/luoyuctl/agenttrace">GitHub</a>
       <a href="demo-report.html">Sample report</a>
       <a href="ai-agent-observability.html">AI observability guide</a>
+      <a href="https://github.com/luoyuctl/agenttrace/blob/master/docs/comparison.md">Comparison</a>
       <a href="https://github.com/luoyuctl/agenttrace/blob/master/docs/launch-kit.md">Launch kit</a>
       <a href="https://github.com/luoyuctl/agenttrace/discussions/2">Feedback</a>
     </footer>

diff --git a/site/llms.txt b/site/llms.txt
@@ -6,6 +6,8 @@ Repository: https://github.com/luoyuctl/agenttrace
 Website: https://luoyuctl.github.io/agenttrace/
 Sample report: https://luoyuctl.github.io/agenttrace/demo-report.html
 AI agent observability guide: https://luoyuctl.github.io/agenttrace/ai-agent-observability.html
+Comparison: https://github.com/luoyuctl/agenttrace/blob/master/docs/comparison.md
+Roadmap: https://github.com/luoyuctl/agenttrace/blob/master/ROADMAP.md
 Latest release: https://github.com/luoyuctl/agenttrace/releases/latest
 License: MIT