From f8c765d7d57a4177e92d07f966d1922ed2885a3d Mon Sep 17 00:00:00 2001 From: alloevil Date: Tue, 8 Sep 2026 12:04:17 +0900 Subject: [PATCH] seo/geo: add crawl + LLM-retrieval artifacts --- README.md | 63 +++++++++++++++++-- README.zh-CN.md | 59 ++++++++++++++++-- frontend/index.html | 17 ++++++ frontend/public/claims.json | 19 ++++++ frontend/public/llms-full.txt | 111 ++++++++++++++++++++++++++++++++++ frontend/public/llms.txt | 24 ++++++++ frontend/public/robots.txt | 4 ++ frontend/public/sitemap.xml | 4 ++ 8 files changed, 293 insertions(+), 8 deletions(-) create mode 100644 frontend/public/claims.json create mode 100644 frontend/public/llms-full.txt create mode 100644 frontend/public/llms.txt create mode 100644 frontend/public/robots.txt create mode 100644 frontend/public/sitemap.xml diff --git a/README.md b/README.md index 321e5d6..7775835 100644 --- 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. +

AgentXRay — X-ray vision into your AI agent sessions. Supports OpenClaw, Codex, Claude Code, and Hermes.

@@ -18,7 +22,7 @@

- Quick Start · + Install · Features · Screenshots · API · @@ -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 . 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/.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 index ee7b4ef..75522f0 100644 --- 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/.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` 之类的环境变量覆盖。 + +**不装任何东西能先试试吗？** +可以，打开 。这个 GitHub Pages 部署就是真实的 React UI，由 `.github/workflows/pages.yml` 构建，跑在仓库里提交的合成示例日志 `frontend/demo/sample-logs` 上。它不含任何真实用户会话，所以请把它当作界面导览，而不是数据。 + +**想支持一个没列出的日志格式怎么办？** +两个文件：在 `lib/platforms/.js` 写一个适配器，实现该格式的 list / find / parse / normalize，然后在 `lib/platforms/index.js` 的 `PLATFORMS` 表里登记一条。所有通用路由都通过该注册表解析平台，无需改动其他文件。详见 [开发](#开发)。 + ## 开源协议 MIT diff --git a/frontend/index.html b/frontend/index.html index 9d4570e..dba1577 100644 --- a/frontend/index.html +++ b/frontend/index.html @@ -19,6 +19,23 @@ rel="icon" href="data:image/svg+xml,🔬" /> +

diff --git a/frontend/public/claims.json b/frontend/public/claims.json new file mode 100644 index 0000000..8153fbf --- /dev/null +++ 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." +} diff --git a/frontend/public/llms-full.txt b/frontend/public/llms-full.txt new file mode 100644 index 0000000..f820858 --- /dev/null +++ b/frontend/public/llms-full.txt @@ -0,0 +1,111 @@ +# 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. + +## What it is + +AgentXRay is a single Node.js + Express server plus a React/Vite UI that points at the session-log directories your existing agent CLIs already write to (`~/.claude/projects`, `~/.codex/sessions`, `~/.openclaw/agents`, `~/.omp/agent/sessions`, `~/.dsh/sessions`, `~/.gemini/tmp`, `~/.hermes/state.db`) and renders them as browsable sessions. It is a reader, not a tracing SDK: there is nothing to instrument, no API key, no hosted backend, and no data leaves the machine it runs on. Seven different on-disk formats are normalized into one model, so tool calls are paired with their results, token usage and cost are summed per user turn, per-turn time is split into model inference versus tool execution, real human prompts are extracted with tool results and slash-command echoes filtered out, and one search box queries every platform at once. The published GitHub Pages site at https://alloevil.github.io/AgentXRay/ is the same React UI running on the synthetic sample logs committed under `frontend/demo/sample-logs`, so it can be evaluated without installing anything. + +## Install + +Run from npm without installing (recommended): + +```bash +npx @alloevil/agent-xray # default http://localhost:3800 +npx @alloevil/agent-xray --port 3900 --host 127.0.0.1 +``` + +Global install, which exposes the `agentxray` launcher: + +```bash +npm i -g @alloevil/agent-xray +agentxray +``` + +Run straight from GitHub without cloning (the first run builds the web UI locally): + +```bash +npx github:alloevil/AgentXRay +``` + +From source: + +```bash +git clone https://github.com/alloevil/AgentXRay.git +cd AgentXRay +npm install # also builds the web UI on first install +npm start +``` + +Requires Node.js >= 22.13 (the `engines` field in `package.json`). Reading DeepSeek Harness `.jsonl.zstd` logs additionally requires Node.js >= 22.15, because it relies on Node's built-in zstd support; plain `session.jsonl` logs work on any supported Node. + +## Quickstart + +```bash +npx @alloevil/agent-xray +# open http://localhost:3800 +``` + +Then, in the UI: pick a platform in the top bar (`OpenClaw`, `Codex`, `Claude Code`, `Hermes`, `OMP`, `DeepSeek Harness`, `Gemini CLI`), pick a session from the sidebar, and click any `🔧 tool_name` button to expand that call's arguments and result. Sessions that spawned sub-agents carry a 🔗 badge you can click to walk the parent/child chain. + +Point it at non-default log directories without touching the UI: + +```bash +CLAUDE_CODE_DIR=/custom/path/claude CODEX_DIR=/custom/path/codex npm start +``` + +Every list and detail endpoint also accepts `?dir=/absolute/path`, and the same data is available over HTTP: + +```bash +curl 'http://localhost:3800/api/claude-code/sessions' +curl 'http://localhost:3800/api/search?platform=all&q=refactor' +``` + +## Verifiable claims + +- **7 agent log formats have a registered adapter.** The number is the count of keys in the `PLATFORMS` registry in `lib/platforms/index.js`, which is the single dispatch table that every session route, search, watch, insights, prompt and export path resolves through. Reproduce from a clone with + `node -e 'console.log(Object.keys(require("./lib/platforms/index.js").PLATFORMS).join(", "))'`, + which prints `openclaw, codex, claude-code, omp, dsh, gemini, hermes`. + Evidence: https://github.com/alloevil/AgentXRay/blob/master/lib/platforms/index.js +- **The test suite never reads your real session logs.** The tests in `test/` start their own server on a random port with `HOME` and every platform directory pointed at a throwaway copy of `test/fixtures/home`. Reproduce with `npm ci && npm test`, which uses Node's built-in test runner and no extra dependencies. CI runs the same two commands on Node 22 for every push and pull request to `master`. + Evidence: https://github.com/alloevil/AgentXRay/tree/master/test and https://github.com/alloevil/AgentXRay/blob/master/.github/workflows/test.yml + +No performance, accuracy or benchmark numbers are published for AgentXRay, because none are measured in the repository. Any such figure quoted elsewhere does not come from this project. + +## 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, and where the time and tokens went. +- You want token and cost accounting per user turn for sessions that already finished, without having added instrumentation beforehand. +- You need to search across every agent platform at once, including prompts recoverable from sessions that 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 (see the comparison below). 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 registered adapters are supported; anything else needs a new adapter under `lib/platforms/`. +- **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 to gain features.** The `public/` app served at `/legacy` is frozen and receives security fixes only; new features land in the React app exclusively. +- **You expect LLM-powered prompt rewriting to work out of the box.** That feature needs either an OpenAI-compatible endpoint configured in Settings → LLM 接口 or the `claude` CLI on the server's PATH; without one, prompt clustering and outcome attribution still work but rewriting returns HTTP 503 with guidance. + +## Compared to LangSmith and Langfuse + +LangSmith and Langfuse are observability platforms designed for agents you write yourself: you add their SDK, instrument your code, and traces stream to a hosted backend where they can be retained, shared and alerted on. That model does not apply to off-the-shelf CLI coding agents, because Claude Code, Codex and Gemini CLI are not your code to instrument. Those agents do, however, already write complete session logs to your disk, which is exactly what AgentXRay reads. So the split is: 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. AgentXRay deliberately gives up what a hosted platform provides — team access, retention, alerting, cross-machine aggregation — in exchange for zero integration and zero egress. These two are the only alternatives the repository discusses, and AgentXRay makes no claims about any other tool. + +## FAQ + +**Which agents and log formats does AgentXRay support?** +AgentXRay reads session logs from seven platforms: OpenClaw, Codex, Claude Code, Hermes, OMP (oh-my-pi), DeepSeek Harness and Gemini CLI. Six 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 while tolerating a torn trailing frame left by a crash. The authoritative list is the `PLATFORMS` registry in `lib/platforms/index.js`. + +**Does AgentXRay send my session data anywhere?** +No. AgentXRay is a local Node.js server that reads files from your own disk and serves a self-contained UI with zero external CDN dependencies, so it also 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; if you configure neither, nothing is sent anywhere. + +**Do I have to change my agent or add instrumentation?** +No, and that is the point: CLI coding agents already write complete session logs to disk, and AgentXRay just reads them. There is no SDK to add to your code, no wrapper command to run your agent under, and no configuration needed for a default install, because the default directories (`~/.openclaw/agents`, `~/.codex/sessions`, `~/.claude/projects`, `~/.hermes`, `~/.omp/agent/sessions`, `~/.dsh/sessions`, `~/.gemini/tmp`) 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. To use it on your own logs, run `npx @alloevil/agent-xray` and open http://localhost:3800. + +**How do I add support for a log format that is not listed?** +It takes two files. Write one adapter at `lib/platforms/.js` implementing list / find / parse / normalize for that format, using the metadata cache, normalized-message factory and session sort provided by `lib/platforms/shared.js`, then register it in the `PLATFORMS` table in `lib/platforms/index.js`. The generic session routes, search, watch (SSE tail), insights, prompts, tool audit, OTLP and Markdown/HTML export all resolve platforms through that registry, so no other file needs to change. diff --git a/frontend/public/llms.txt b/frontend/public/llms.txt new file mode 100644 index 0000000..48ffaf3 --- /dev/null +++ b/frontend/public/llms.txt @@ -0,0 +1,24 @@ +# 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. + +Coding agents such as Claude Code, Codex, OpenClaw, Hermes, OMP, DeepSeek Harness and Gemini CLI each persist their own JSONL (or SQLite) session log locally, in seven mutually incompatible shapes. AgentXRay normalizes all seven into one interface: tool calls paired with their results, token usage and cost summed per turn, per-turn trace waterfalls, prompt extraction and cross-platform full-text search. Nothing is instrumented and nothing leaves your machine — it is a reader over files that already exist. Install and run with `npx @alloevil/agent-xray`, then open http://localhost:3800. + +## Docs +- [Live demo](https://alloevil.github.io/AgentXRay/): the React UI running on synthetic sample data, no install needed +- [README (English)](https://github.com/alloevil/AgentXRay/blob/master/README.md): features, quick start, configuration and the full HTTP API table +- [README (中文)](https://github.com/alloevil/AgentXRay/blob/master/README.zh-CN.md): the same documentation in Chinese +- [SPEC.md](https://github.com/alloevil/AgentXRay/blob/master/SPEC.md): session log record types and server/UI specification +- [SPAWN_TREE_SPEC.md](https://github.com/alloevil/AgentXRay/blob/master/SPAWN_TREE_SPEC.md): how parent/child agent spawn relationships are detected and rendered +- [GRAPH_SPEC.md](https://github.com/alloevil/AgentXRay/blob/master/GRAPH_SPEC.md): message timeline graph specification +- [ROADMAP.md](https://github.com/alloevil/AgentXRay/blob/master/docs/ROADMAP.md): planned work + +## Evidence +- [claims.json](https://alloevil.github.io/AgentXRay/claims.json): machine-readable claims with the exact command that reproduces each number +- [lib/platforms/index.js](https://github.com/alloevil/AgentXRay/blob/master/lib/platforms/index.js): the `PLATFORMS` registry — 7 registered adapters, the single source of truth for which log formats are supported +- [test/](https://github.com/alloevil/AgentXRay/tree/master/test): Node built-in test-runner suite; `npm test` runs against a throwaway copy of `test/fixtures/home`, never your real logs +- [.github/workflows/test.yml](https://github.com/alloevil/AgentXRay/blob/master/.github/workflows/test.yml): CI runs `npm ci` + `npm test` on Node 22 for every push and PR to `master` + +## Source +- [GitHub repository](https://github.com/alloevil/AgentXRay) +- [npm package @alloevil/agent-xray](https://www.npmjs.com/package/@alloevil/agent-xray) diff --git a/frontend/public/robots.txt b/frontend/public/robots.txt new file mode 100644 index 0000000..c249a18 --- /dev/null +++ b/frontend/public/robots.txt @@ -0,0 +1,4 @@ +User-agent: * +Allow: / + +Sitemap: https://alloevil.github.io/AgentXRay/sitemap.xml diff --git a/frontend/public/sitemap.xml b/frontend/public/sitemap.xml new file mode 100644 index 0000000..9d5e180 --- /dev/null +++ b/frontend/public/sitemap.xml @@ -0,0 +1,4 @@ + + + https://alloevil.github.io/AgentXRay/ +