alloevil · alloevil · Sep 8, 2026 · Sep 8, 2026
diff --git a/README.md b/README.md
@@ -1,3 +1,7 @@
+# AgentXRay
+
+**AgentXRay** is a local-first web dashboard that reads and visualizes the session logs your AI coding agents already write to disk, for developers who want to see what those agents actually did.
+
 <p align="center">
   <img src="./assets/hero.svg" width="100%" alt="AgentXRay — X-ray vision into your AI agent sessions. Supports OpenClaw, Codex, Claude Code, and Hermes.">
 </p>
@@ -18,7 +22,7 @@
 </p>
 
 <p align="center">
-  <a href="#quick-start">Quick Start</a> ·
+  <a href="#install">Install</a> ·
   <a href="#features">Features</a> ·
   <a href="#screenshots">Screenshots</a> ·
   <a href="#api">API</a> ·
@@ -27,8 +31,12 @@
 
 ---
 
+## What it is
+
 X-ray vision into your AI agent sessions. Supports **OpenClaw**, **Codex**, **Claude Code**, **Hermes**, **OMP**, **DeepSeek Harness** and **Gemini CLI** — all in one interface.
 
+AgentXRay is a single Node.js + Express server plus a React UI. It reads the JSONL session logs (SQLite, for Hermes) that those CLIs already write under your home directory and normalizes all seven formats into one view: tool calls paired with their results, tokens and cost summed per user turn, per-turn trace waterfalls, prompt extraction and cross-platform full-text search. Nothing is instrumented, and nothing leaves your machine.
+
 ## Why AgentXRay
 
 AgentXRay is a **local-first viewer for the agent sessions you already have**.
@@ -39,6 +47,34 @@ Compared to grepping the raw JSONL yourself, AgentXRay normalizes seven differen
 
 If you build and operate your own agent in production, use a tracing platform. If you want to see what your coding agents actually did, use AgentXRay.
 
+## When to use it
+
+- You use one or more CLI coding agents and want to review what a session actually did — which tools ran, with what arguments, what came back, where the time and tokens went.
+- You want token and cost accounting per user turn for sessions that have already finished, without having instrumented anything beforehand.
+- You need to search across every agent platform at once, including prompts recoverable from sessions Claude Code's own cleanup already deleted.
+- You want your session data to stay on your machine: no SDK, no account, no egress.
+- You want to collect the prompts worth keeping and install them as native slash commands for Claude Code, Codex or OMP.
+
+## When NOT to use it
+
+- **You are building your own agent and want production tracing.** Use an observability platform instead. AgentXRay reads finished log files; it is not an instrumentation SDK and has no hosted backend, retention policy, alerting or team dashboard.
+- **You need a multi-user or remotely hosted service.** It is a single-process local server, meant to run on the machine that owns the logs.
+- **Your agent does not write session logs in a supported format.** Only the seven adapters registered in `lib/platforms/index.js` are supported; anything else needs a new adapter (see [Development](#development)).
+- **You cannot run Node.js ≥ 22.13**, or you need compressed DeepSeek Harness logs on a Node older than 22.15.
+- **You want the legacy vanilla UI under `public/` to gain features.** It is frozen and receives security fixes only.
+- **You expect the LLM-powered prompt rewriting to work with no setup.** It needs an OpenAI-compatible endpoint configured in Settings → LLM 接口, or the `claude` CLI on the server's PATH; without one, clustering and attribution still work but rewriting returns HTTP 503.
+
+## Compared to LangSmith and Langfuse
+
+| | AgentXRay | LangSmith / Langfuse |
+|---|---|---|
+| Built for | agent sessions you already have on disk | agents you write yourself |
+| Integration | none — reads existing log files | add their SDK and instrument your code |
+| Works with off-the-shelf CLI agents (Claude Code, Codex, Gemini CLI) | yes, they already log to disk | not their model — that code is not yours to instrument |
+| Where data lives | your machine only | hosted backend |
+
+Rule of thumb: if you build and operate your own agent in production, use a tracing platform. If you want to see what your coding agents actually did, use AgentXRay. LangSmith and Langfuse are the only alternatives this project makes any comparison against.
+
 ---
 
 ## Features
@@ -99,16 +135,16 @@ Configure platform directories from the UI. Changes are saved to localStorage
 
 ---
 
-## Quick Start
+## Install
 
-**Option 1 — npx from npm** (once the package is published to npm)
+**Option 1 — npx from npm**
 
 ```bash
 npx @alloevil/agent-xray            # default http://localhost:3800
 npx @alloevil/agent-xray --port 3900 --host 127.0.0.1
 ```
 
-A global install (`npm i -g agent-xray`) exposes the same launcher as `agentxray`.
+A global install (`npm i -g @alloevil/agent-xray`) exposes the same launcher as `agentxray`.
 
 **Option 2 — npx straight from GitHub** (works today, no clone)
 
@@ -284,6 +320,25 @@ Tests live in `test/` and use Node's built-in test runner — no extra dependenc
 
 ---
 
+## FAQ
+
+**Which agents and log formats does AgentXRay support?**
+Seven platforms: OpenClaw, Codex, Claude Code, Hermes, OMP (oh-my-pi), DeepSeek Harness and Gemini CLI. Six of them store JSONL; Hermes stores SQLite at `~/.hermes/state.db`. DeepSeek Harness logs may be multi-frame zstd-compressed `.jsonl.zstd`, which AgentXRay decompresses frame by frame, tolerating a torn trailing frame left by a crash. The authoritative list is the `PLATFORMS` registry in `lib/platforms/index.js` — run `node -e 'console.log(Object.keys(require("./lib/platforms/index.js").PLATFORMS))'` to print it.
+
+**Does AgentXRay send my session data anywhere?**
+No. It is a local Node.js server reading files from your own disk, serving a self-contained UI with zero external CDN dependencies, so it works offline. The only outbound traffic it can make is the optional prompt-rewrite feature, which calls an OpenAI-compatible endpoint you configure yourself or shells out to a local `claude` CLI; configure neither and nothing is sent anywhere.
+
+**Do I have to change my agent or add instrumentation?**
+No. CLI coding agents already write complete session logs to disk, and AgentXRay just reads them. There is no SDK to add to your code and no wrapper command to run your agent under. A default install needs no configuration either, because the default directories listed under [Configuration](#configuration) are used unless you override them in the settings panel or through environment variables such as `CLAUDE_CODE_DIR`.
+
+**How do I try it without installing anything?**
+Open <https://alloevil.github.io/AgentXRay/>. That GitHub Pages deployment is the real React UI, built by `.github/workflows/pages.yml`, running against the synthetic sample logs committed under `frontend/demo/sample-logs`. It contains no real user sessions, so treat it as a UI tour rather than as data.
+
+**How do I add support for a log format that is not listed?**
+Two files: write an adapter at `lib/platforms/<name>.js` implementing list / find / parse / normalize for that format, then register it in the `PLATFORMS` table in `lib/platforms/index.js`. Every generic route resolves platforms through that registry, so no other file needs to change. See [Development](#development).
+
+---
+
 ## License
 
 [MIT](LICENSE)

diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -1,11 +1,17 @@
 # AgentXRay
 
-AI Agent 会话 X 光透视工具，支持 **OpenClaw**、**Codex**、**Claude Code**、**Hermes**、**OMP**、**DeepSeek Harness** 和 **Gemini CLI** —— 一个界面全搞定。
+**AgentXRay** 是一个 local-first 的 Web 面板，直接读取并可视化 AI coding agent 已经写在你磁盘上的会话日志，面向想看清这些 agent 究竟做了什么的开发者。
 
 [English](README.md) | 中文
 
 **[在线 Demo](https://alloevil.github.io/AgentXRay/)**（合成示例数据，非真实用户会话）
 
+## 这是什么
+
+AI Agent 会话 X 光透视工具，支持 **OpenClaw**、**Codex**、**Claude Code**、**Hermes**、**OMP**、**DeepSeek Harness** 和 **Gemini CLI** —— 一个界面全搞定。
+
+AgentXRay 由一个 Node.js + Express 服务和一套 React UI 组成：它读取这些 CLI 本来就写在你 home 目录下的 JSONL 会话日志（Hermes 是 SQLite），把七种格式归一化到同一个视图 —— 工具调用与结果自动配对、按轮次汇总 token 与花费、每轮耗时瀑布图、prompt 提取、跨平台全文搜索。零埋点、零接入，数据不出本机。
+
 ## 为什么是 AgentXRay
 
 AgentXRay 是一个 **local-first 的查看器，看的是你已经拥有的 agent 会话**。
@@ -18,6 +24,34 @@ LangSmith、Langfuse 这类观测平台面向的是*你自己写的* agent：接
 
 ![Main View](screenshots/main-view.png)
 
+## 何时该用
+
+- 你在用一个或多个 CLI coding agent，想复盘某次会话到底做了什么：调用了哪些工具、参数是什么、返回了什么、时间和 token 花在哪里。
+- 你想按用户轮次核算 token 与花费，而这些会话早已结束，当时并没有做任何埋点。
+- 你需要一次搜索全部 agent 平台，包括从 Claude Code 自身清理机制已删除的会话里恢复出来的 prompt。
+- 你希望会话数据只留在本机：不装 SDK、不注册账号、不外传。
+- 你想把值得复用的 prompt 收集起来，并一键安装为 Claude Code、Codex 或 OMP 的原生 slash command。
+
+## 何时不该用
+
+- **你在做自己的 agent，需要生产级 tracing。** 那请用观测平台。AgentXRay 读的是已经落盘的日志文件，它不是埋点 SDK，没有托管后端、数据留存策略、告警和团队看板。
+- **你需要多人协作或远程托管的服务。** 它是单进程本地服务，设计上就跑在持有日志的那台机器上。
+- **你的 agent 不以受支持的格式落盘。** 目前只支持 `lib/platforms/index.js` 中注册的七个适配器，其他格式需要新写一个适配器（见 [开发](#开发)）。
+- **你无法使用 Node.js ≥ 22.13**，或需要在低于 22.15 的 Node 上读取压缩的 DeepSeek Harness 日志。
+- **你期待 `public/` 下的 legacy 原生 UI 继续加功能。** 它已冻结，仅接受安全修复。
+- **你期待 LLM prompt 改写开箱即用。** 该功能需要在 设置 → LLM 接口 配好 OpenAI 兼容端点，或者服务端 PATH 上有 `claude` CLI；两者都没有时，聚类与归因仍然可用，但改写会返回 HTTP 503。
+
+## 与 LangSmith / Langfuse 的区别
+
+| | AgentXRay | LangSmith / Langfuse |
+|---|---|---|
+| 面向 | 你磁盘上已有的 agent 会话 | 你自己写的 agent |
+| 接入方式 | 无需接入，直接读现有日志文件 | 接入 SDK，在代码里埋点 |
+| 能否覆盖现成 CLI agent（Claude Code、Codex、Gemini CLI） | 可以，它们本来就在落盘 | 不适用，这些代码不是你的，没法埋点 |
+| 数据存放 | 仅本机 | 托管后端 |
+
+一句话：在生产环境构建和运营自己的 agent，请用 tracing 平台；想看清 coding agent 到底干了什么，用 AgentXRay。本项目只与 LangSmith、Langfuse 作对比，不评价其他工具。
+
 ## 功能特性
 
 - **多平台支持** — 一个界面统一查看 OpenClaw、Codex、Claude Code、Hermes、OMP、DeepSeek Harness、Gemini CLI 的会话日志（dsh 的多帧 zstd 压缩日志透明解压；Gemini CLI 的 `/rewind` 回滚记录会先折叠，回滚掉的历史不会重复渲染）
@@ -71,16 +105,16 @@ LangSmith、Langfuse 这类观测平台面向的是*你自己写的* agent：接
 
 ![Settings](screenshots/settings-panel.png)
 
-## 快速开始
+## 安装
 
-**方式一 — 通过 npm 使用 npx**（包发布到 npm 后可用）
+**方式一 — 通过 npm 使用 npx**
 
 ```bash
 npx @alloevil/agent-xray            # 默认 http://localhost:3800
 npx @alloevil/agent-xray --port 3900 --host 127.0.0.1
 ```
 
-全局安装（`npm i -g agent-xray`）后可直接使用 `agentxray` 命令。
+全局安装（`npm i -g @alloevil/agent-xray`）后可直接使用 `agentxray` 命令。
 
 **方式二 — 直接从 GitHub 运行 npx**（现在即可用，无需克隆）
 
@@ -242,6 +276,23 @@ dsh 的 `.jsonl.zstd` 日志是多个独立 Zstandard 帧的串联（每个持
 
 **新增平台只需两个文件**：在 `lib/platforms/<name>.js` 写一个适配器（针对该日志格式的 list / find / parse / normalize，`lib/platforms/shared.js` 提供元数据缓存、归一化消息工厂和会话排序），再到 `lib/platforms/index.js` 的 `PLATFORMS` 注册表登记一条。通用会话路由、搜索、watch（SSE 实时跟踪）、洞察、Prompt 提取、工具体检、OTLP 与 Markdown/HTML 导出全部通过该注册表解析平台，无需改动其他文件。
 
+## 常见问题
+
+**AgentXRay 支持哪些 agent 和日志格式？**
+七个平台：OpenClaw、Codex、Claude Code、Hermes、OMP（oh-my-pi）、DeepSeek Harness 和 Gemini CLI。其中六个是 JSONL，Hermes 是位于 `~/.hermes/state.db` 的 SQLite。DeepSeek Harness 的日志可能是多帧 zstd 压缩的 `.jsonl.zstd`，AgentXRay 会逐帧解压，并容忍崩溃残留的尾部不完整帧。权威清单是 `lib/platforms/index.js` 里的 `PLATFORMS` 注册表，可用 `node -e 'console.log(Object.keys(require("./lib/platforms/index.js").PLATFORMS))'` 打印。
+
+**AgentXRay 会把我的会话数据传到别处吗？**
+不会。它是一个读取你本机磁盘文件的本地 Node.js 服务，UI 完全自包含、零外部 CDN，因此离线也能用。唯一可能产生外发流量的是可选的 prompt 改写功能：它调用你自己配置的 OpenAI 兼容端点，或调起本机的 `claude` CLI；两者都不配置时，不会有任何数据外发。
+
+**需要改动我的 agent 或加埋点吗？**
+不需要。CLI coding agent 本来就把完整会话日志写在磁盘上，AgentXRay 只是读它们。你不需要在代码里接 SDK，也不需要用什么包装命令来启动 agent。默认安装同样无需配置，[配置](#配置) 一节列出的默认目录会直接生效，除非你在设置面板里改，或用 `CLAUDE_CODE_DIR` 之类的环境变量覆盖。
+
+**不装任何东西能先试试吗？**
+可以，打开 <https://alloevil.github.io/AgentXRay/>。这个 GitHub Pages 部署就是真实的 React UI，由 `.github/workflows/pages.yml` 构建，跑在仓库里提交的合成示例日志 `frontend/demo/sample-logs` 上。它不含任何真实用户会话，所以请把它当作界面导览，而不是数据。
+
+**想支持一个没列出的日志格式怎么办？**
+两个文件：在 `lib/platforms/<name>.js` 写一个适配器，实现该格式的 list / find / parse / normalize，然后在 `lib/platforms/index.js` 的 `PLATFORMS` 表里登记一条。所有通用路由都通过该注册表解析平台，无需改动其他文件。详见 [开发](#开发)。
+
 ## 开源协议
 
 MIT
diff --git a/frontend/index.html b/frontend/index.html
@@ -19,6 +19,23 @@
       rel="icon"
       href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>🔬</text></svg>"
     />
+    <script type="application/ld+json">
+      {
+        "@context": "https://schema.org",
+        "@type": "SoftwareApplication",
+        "name": "AgentXRay",
+        "description": "Local-first web dashboard that reads and visualizes the session logs AI coding agents already write to disk — OpenClaw, Codex, Claude Code, Hermes, OMP, DeepSeek Harness and Gemini CLI in one interface.",
+        "applicationCategory": "DeveloperApplication",
+        "operatingSystem": "macOS, Linux, Windows",
+        "url": "https://alloevil.github.io/AgentXRay/",
+        "codeRepository": "https://github.com/alloevil/AgentXRay",
+        "programmingLanguage": "JavaScript, TypeScript",
+        "license": "https://opensource.org/licenses/MIT",
+        "isAccessibleForFree": true,
+        "offers": { "@type": "Offer", "price": "0", "priceCurrency": "USD" },
+        "author": { "@type": "Person", "name": "allo", "url": "https://github.com/alloevil" }
+      }
+    </script>
   </head>
   <body>
     <div id="root"></div>

diff --git a/frontend/public/claims.json b/frontend/public/claims.json
@@ -0,0 +1,19 @@
+{
+  "project": "AgentXRay",
+  "url": "https://alloevil.github.io/AgentXRay/",
+  "repository": "https://github.com/alloevil/AgentXRay",
+  "updated": "2026-09-08",
+  "claims": [
+    {
+      "id": "supported-log-formats",
+      "claim": "AgentXRay has a registered adapter for 7 agent session log formats: OpenClaw, Codex, Claude Code, OMP, DeepSeek Harness, Gemini CLI and Hermes.",
+      "value": "7",
+      "metric": "number of platform adapters registered in the PLATFORMS dispatch table that every session route, search, watch, insights, prompt and export path resolves through",
+      "method": "counted the keys of the PLATFORMS object exported by lib/platforms/index.js in the committed source",
+      "repro": "node -e 'console.log(Object.keys(require(\"./lib/platforms/index.js\").PLATFORMS).join(\", \"))'",
+      "evidence": "https://github.com/alloevil/AgentXRay/blob/master/lib/platforms/index.js",
+      "verified": "2026-09-08"
+    }
+  ],
+  "notClaimed": "No performance, accuracy or benchmark numbers are published for AgentXRay, because none are measured in this repository."
+}