Feat: sub-agent chat view and others

.gitignore

@@ -33,3 +33,5 @@ npm-debug.log*
 package-lock.json
 yarn.lock
 bun.lockb
+.gstack/
+.github/.demo-frames/

CLAUDE.md

@@ -0,0 +1,105 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Agents Run is a web UI for browsing AI coding tool conversation history. It reads from `~/.claude/`, `~/.codex/`, and `~/.gemini/` to present conversations from Claude Code, Codex CLI/Desktop, and Gemini CLI in a unified real-time streaming interface.
+
+## Tech Stack
+
+- **Backend**: Node.js 20+, Hono web framework, TypeScript (ES modules)
+- **Frontend**: React 19, Vite 6, Tailwind CSS 4
+- **Package Manager**: pnpm (required)
+
+## Development Commands
+
+```bash
+pnpm install             # Install dependencies
+pnpm dev                 # Web on port 12000, API on port 12001
+pnpm dev:web             # Vite dev server only (port 12000)
+pnpm dev:server          # API server with watch mode (port 12001)
+pnpm build               # Build both server and web
+pnpm build:web           # Vite production build -> dist/web/
+pnpm build:server        # tsup build -> dist/index.js
+pnpm start               # node dist/index.js
+```
+
+No test suite exists. Use `pnpm build` to verify changes compile.
+
+## Architecture
+
+### Multi-Provider System
+
+The backend uses a provider adapter pattern to support multiple AI tool data sources:
+
+- **`api/provider-types.ts`** — `ProviderAdapter` interface and `ProviderName` type (`"claude" | "codex" | "gemini"`)
+- **`api/providers.ts`** — `ProviderManager` singleton that auto-detects available providers at startup and delegates all operations. Exported as `providerManager`.
+- **`api/storage.ts`** — Claude Code adapter (also defines shared types: `Session`, `ConversationMessage`, `ContentBlock`, `StreamResult`, `SessionMeta`, `SearchResult`)
+- **`api/codex-adapter.ts`** — Codex CLI/Desktop adapter (reads `~/.codex/sessions/` JSONL files)
+- **`api/gemini-adapter.ts`** — Gemini CLI adapter (reads `~/.gemini/tmp/*/chats/session-*.json` JSON files)
+- **`api/pricing.ts`** — Token pricing data for all providers (Claude, OpenAI/Codex, Gemini). `findPricing(modelId)` for lookup, `ModelPricing` interface for per-model prices (input, output, cacheWrite5m, cacheWrite1h, cacheRead, longContext).
+
+Each adapter implements: `init()`, `getSessions()`, `getConversation()`, `getConversationStream()`, `getSessionMeta()`, `searchConversations()`, `ownsSession()`, `resolveSessionId()`, and cache invalidation methods.
+
+**Session routing**: `providerManager.findAdapter(sessionId)` checks each adapter's `ownsSession()` (file index lookup) to route requests to the correct provider.
+
+### Data Source Differences
+
+| | Claude | Codex | Gemini |
+|---|---|---|---|
+| **Directory** | `~/.claude/` | `~/.codex/` | `~/.gemini/` |
+| **File format** | JSONL | JSONL | JSON (not JSONL) |
+| **Session index** | `history.jsonl` | `session_index.jsonl` | None (scan `tmp/*/chats/`) |
+| **Stream offset** | byte offset | byte offset | message index |
+| **Token data** | per-message usage | `token_count` events (cumulative) | per-message tokens |
+| **Rename/Delete** | supported | not supported (returns 400) | not supported (returns 400) |
+| **Resume** | `claude --resume` | `codex resume` | `gemini resume` |
+
+### Server Layer (`api/server.ts`)
+
+Hono HTTP server. All data routes go through `providerManager` except subagent endpoints (Claude-only).
+
+**Init sequence** (in `start()`, strictly ordered):
+1. `providerManager.init()` — initializes all adapters, builds file indexes
+2. `initWatcher()` + `startWatcher()` — Claude file watcher
+3. `onHistoryChange/onSessionChange` — Claude watcher listeners
+4. `addWatchTarget()` for each non-Claude adapter — separate chokidar instances
+5. HTTP `serve()`
+
+Key endpoints:
+- `GET /api/providers` — list available providers with session counts
+- `GET /api/sessions?provider=` — all sessions, optional provider filter
+- `GET /api/sessions/stream?provider=` — SSE with `sessions`, `sessionsUpdate`, `sessionsRemove` events
+- `GET /api/conversation/:id/stream?offset=` — SSE with `{messages, nextOffset}` payload
+- `GET /api/conversation/:id/meta` — combined token usage, model ID, and subagent info
+- `POST /api/search` — body: `{query, provider?}`
+- `DELETE /api/sessions/:id` — Claude only (400 for others)
+- `POST /api/sessions/:id/rename` — Claude only (400 for others)
+
+### File Watching (`api/watcher.ts`)
+
+- Claude uses the built-in watcher (`startWatcher()`)
+- Non-Claude providers use `addWatchTarget(paths, depth, callback)`
+- Callbacks call `emitSessionChange()` / `emitHistoryChange()` to trigger SSE
+- `resolveSessionId(filePath)` maps file paths back to session IDs; returns null for index files (triggers list refresh instead)
+
+### Frontend (`web/`)
+
+- **`web/app.tsx`** — Main layout, provider filter dropdown (shown when >1 provider), session header with provider-aware rename/resume
+- **`web/components/session-list.tsx`** — Virtualized list with title/content search, CLI provider badges for non-Claude sessions, delete button Claude-only
+- **`web/components/session-view.tsx`** — Conversation viewer with SSE streaming, `TokenUsageBar` (Claude, model-aware pricing), `GenericTokenUsageBar` (Gemini/Codex, with costs when pricing available). Uses `findPricing()` from `api/pricing.ts` to dynamically resolve per-model token prices.
+- **`web/components/message-block.tsx`** — Message rendering with tool icons/previews for Claude, Codex (`exec_command`), and Gemini (`read_file`, `replace`, `write_file`) tool names
+- **`web/utils.ts`** — `getProviderInfo(model)` for model badges, `getCliProviderInfo(provider)` for CLI tool badges
+
+### Key Implementation Details
+
+- **ES modules only** (`"type": "module"` in package.json)
+- **Path alias**: `@agents-run/api` resolves to `api/storage.ts` (configured in `web/vite.config.ts`). Frontend imports types from this alias.
+- **CLI entry**: `api/index.ts` uses commander.js
+- **Production**: Web assets built to `dist/web/`, served by Hono's serveStatic
+- **SSE heartbeat**: 30 seconds on all SSE connections
+- **Session deduplication**: Frontend uses `message.uuid` to deduplicate streamed messages
+- **Codex UUIDs**: Deterministic `codex-${sessionId}-${lineIndex}` since Codex messages lack native UUIDs
+- **Gemini `displayContent`**: Preferred over `content` for user messages (avoids showing embedded file contents)
+- **Lazy rescan**: Non-Claude adapters set `rescanPending` flag on cache invalidation; actual disk rescan happens on next `getSessions()` call

LICENSE

@@ -1,6 +1,7 @@
 MIT License
 
 Copyright (c) 2026 Kamran Ahmed
+Copyright (c) 2026 ZHICHAO SUN
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,13 +1,17 @@
 <div align="center">
 
-# Claude Run
+# Agents Run
 
-Browse your Claude Code conversation history in a beautiful web UI
+English | [简体中文](./README.zh-CN.md)
 
-[![npm version](https://img.shields.io/npm/v/claude-run.svg)](https://www.npmjs.com/package/claude-run)
+Browse AI coding session history from multiple tools in a unified web UI
+
+[![npm version](https://img.shields.io/npm/v/agents-run.svg)](https://www.npmjs.com/package/agents-run)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-<img src=".github/claude-run.gif" alt="Claude Run Demo" width="800" />
+<img src=".github/agents-run.gif" alt="Agents Run Demo" width="800" />
+
+<sub>The README demo is generated from synthetic sessions, not from local history.</sub>
 
 </div>
 
@@ -16,13 +20,21 @@ Browse your Claude Code conversation history in a beautiful web UI
 Run the project simply by executing
 
 ```bash
-npx claude-run
+npx agents-run
+```
+
+Or, after installing globally, use:
+
+```bash
+agents-run
 ```
 
 The browser will open automatically at http://localhost:12001.
 
 ## Features
 
+- **Multi-provider support** - Browse conversations from Claude Code, Codex CLI/Desktop, and Gemini CLI in one place
+- **Token usage & cost tracking** - Per-session cost breakdown with model-aware pricing for all providers
 - **Real-time streaming** - Watch conversations update live as Claude responds
 - **Search** - Find sessions by prompt text or project name
 - **Filter by project** - Focus on specific projects
@@ -36,19 +48,26 @@ The browser will open automatically at http://localhost:12001.
 Install globally via npm:
 
 ```bash
-npm install -g claude-run
+npm install -g agents-run
+```
+
+If you prefer Homebrew:
+
+```bash
+brew tap SunZhiC/agents-run
+brew install agents-run
 ```
 
 Then run it from any directory:
 
 ```bash
-claude-run
+agents-run
 ```
 
-The browser will open automatically at http://localhost:12001, showing all your Claude Code conversations.
+The browser will open automatically at http://localhost:12001, showing your AI coding sessions across supported providers.
 
 ```bash
-claude-run [options]
+agents-run [options]
 
 Options:
   -V, --version        Show version number
@@ -60,26 +79,35 @@ Options:
 
 ## How It Works
 
-Claude Code stores conversation history in `~/.claude/`. This tool reads that data and presents it in a web interface with:
+Agents Run reads conversation history from multiple AI coding tools and presents them in a unified web interface:
+
+| Provider | Data Directory | Features |
+|---|---|---|
+| **Claude Code** | `~/.claude/` | Full token usage with cost breakdown, session rename/delete, resume |
+| **Codex CLI/Desktop** | `~/.codex/` | Token usage with cost breakdown, resume |
+| **Gemini CLI** | `~/.gemini/` | Token usage with cost breakdown |
+
+The interface includes:
 
-- **Session list** - All your conversations, sorted by recency
+- **Session list** - All your conversations across providers, sorted by recency
 - **Project filter** - Focus on a specific project
 - **Conversation view** - Full message history with tool calls
+- **Token usage & costs** - Model-aware pricing (dynamically resolved per session)
 - **Session header** - Shows conversation title, project name, and timestamp
 - **Resume command** - Copies the command to resume the conversation
 - **Real-time updates** - SSE streaming for live conversations
 
 ## Requirements
 
 - Node.js 20+
-- Claude Code installed and used at least once
+- At least one of: Claude Code, Codex CLI, or Gemini CLI installed and used
 
 ## Development
 
 ```bash
 # Clone the repo
-git clone https://github.com/kamranahmedse/claude-run.git
-cd claude-run
+git clone https://github.com/SunZhiC/agents-run.git
+cd agents-run
 
 # Install dependencies
 pnpm install
@@ -89,8 +117,21 @@ pnpm dev
 
 # Build for production
 pnpm build
+
+# Refresh the README demo GIF with synthetic data
+pnpm demo:gif
+```
+
+## Release
+
+```bash
+# Publish a new npm release
+npm publish
+
+# Sync the Homebrew tap formula to the latest published npm version
+pnpm sync:homebrew
 ```
 
 ## License
 
-MIT © Kamran Ahmed
+MIT

README.zh-CN.md

@@ -0,0 +1,137 @@
+<div align="center">
+
+# Agents Run
+
+[English](./README.md) | 简体中文
+
+在统一的 Web UI 中浏览来自多个工具的 AI 编码会话历史
+
+[![npm version](https://img.shields.io/npm/v/agents-run.svg)](https://www.npmjs.com/package/agents-run)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+<img src=".github/agents-run.gif" alt="Agents Run Demo" width="800" />
+
+<sub>README 中的演示内容基于合成会话生成，并非来自本地历史记录。</sub>
+
+</div>
+
+<br />
+
+只需执行下面的命令即可运行项目：
+
+```bash
+npx agents-run
+```
+
+或者在全局安装后，直接使用：
+
+```bash
+agents-run
+```
+
+浏览器会自动打开 http://localhost:12001。
+
+## 功能特性
+
+- **多提供方支持** - 在同一个界面中浏览来自 Claude Code、Codex CLI/Desktop 和 Gemini CLI 的会话
+- **Token 使用量与成本统计** - 为所有提供方展示按会话统计、感知模型定价的成本拆分
+- **实时流式更新** - 在 Claude 响应时实时查看会话更新
+- **搜索** - 按提示词文本或项目名称查找会话
+- **按项目筛选** - 聚焦特定项目
+- **恢复会话** - 复制恢复命令，在终端中继续任意对话
+- **可折叠侧边栏** - 最大化可视区域
+- **深色模式** - 更护眼
+- **简洁 UI** - 熟悉的聊天界面，支持折叠工具调用
+
+## 使用方式
+
+通过 npm 全局安装：
+
+```bash
+npm install -g agents-run
+```
+
+如果你更喜欢 Homebrew：
+
+```bash
+brew tap SunZhiC/agents-run
+brew install agents-run
+```
+
+然后在任意目录运行：
+
+```bash
+agents-run
+```
+
+浏览器会自动打开 http://localhost:12001，并展示你在已支持提供方中的 AI 编码会话历史。
+
+```bash
+agents-run [options]
+
+Options:
+  -V, --version        Show version number
+  -p, --port <number>  Port to listen on (default: 12001)
+  -d, --dir <path>     Claude directory (default: ~/.claude)
+  --no-open            Do not open browser automatically
+  -h, --help           Show help
+```
+
+## 工作原理
+
+Agents Run 会读取多个 AI 编码工具的对话历史，并将它们统一展示在一个 Web 界面中：
+
+| 提供方 | 数据目录 | 功能 |
+|---|---|---|
+| **Claude Code** | `~/.claude/` | 完整 token 使用量与成本拆分、会话重命名/删除、恢复会话 |
+| **Codex CLI/Desktop** | `~/.codex/` | token 使用量与成本拆分、恢复会话 |
+| **Gemini CLI** | `~/.gemini/` | token 使用量与成本拆分 |
+
+界面包含：
+
+- **会话列表** - 展示来自各提供方的所有对话，并按最近时间排序
+- **项目筛选** - 聚焦某个特定项目
+- **会话视图** - 展示完整消息历史与工具调用
+- **Token 使用量与成本** - 基于模型定价，并按会话动态解析
+- **会话头部** - 显示对话标题、项目名称和时间戳
+- **恢复命令** - 复制命令以继续当前会话
+- **实时更新** - 通过 SSE 流式展示进行中的会话
+
+## 环境要求
+
+- Node.js 20+
+- 至少安装并使用过以下之一：Claude Code、Codex CLI 或 Gemini CLI
+
+## 开发
+
+```bash
+# 克隆仓库
+git clone https://github.com/SunZhiC/agents-run.git
+cd agents-run
+
+# 安装依赖
+pnpm install
+
+# 启动开发服务器
+pnpm dev
+
+# 构建生产版本
+pnpm build
+
+# 用合成数据刷新 README 演示 GIF
+pnpm demo:gif
+```
+
+## 发布
+
+```bash
+# 发布新的 npm 版本
+npm publish
+
+# 将 Homebrew tap formula 同步到最新发布的 npm 版本
+pnpm sync:homebrew
+```
+
+## 许可证
+
+MIT