1. 项目定位与用途
Nexus 是一款本地 AI Agent 会话监控工具，旨在为开发者提供实时、统一的会话可视化界面。它自动追踪 Claude Code、Codex 和 OpenClaw 的会话活动，展示消息流、Token 消耗和 USD 成本，并支持历史数据回溯。通过 WebSocket 技术，前端可接收实时更新，无需手动刷新。项目定位为轻量级、零配置的辅助工具，帮助用户高效管理本地 AI 资源使用情况。
项目档案应用项目
Nexus - 实时监控本地 AI Agent 会话的可视化工具 | 安装与使用指南
Nexus 是一款轻量级本地监控工具，可实时追踪 Claude Code、Codex、OpenClaw 的会话活动、Token 消耗与 USD 成本。本文详细介绍其功能特性、安装步骤、使用方法、技术架构及适用场景，帮助开发者高效管理 AI 资源。
AI 总结
Nexus 是一款轻量级本地监控工具，可实时追踪 Claude Code、Codex、OpenClaw 等 AI Agent 的会话活动、Token 消耗与成本，并通过 WebSocket 推送数据至可视化界面，帮助开发者全面掌握 AI 使用情况。
中文项目介绍
Nexus 是一个专为本地 AI Agent 设计的实时会话监控与可视化工具。它自动发现并追踪 Claude Code、Codex 和 OpenClaw 的活跃会话，持续聚合 Token 使用量和 USD 成本，并提供历史数据回溯能力。
该工具解决了开发者在日常使用 AI 编程助手时无法直观查看会话状态、用量统计和历史记录的问题，将分散的日志文件转化为统一的实时监控界面。
适用场景包括：监控 AI Agent 的实时活跃度与消息流、追踪项目级或全局的 Token 消耗与成本、分析历史会话数据以优化使用策略。
技术实现上，Nexus 基于 Express 和 WebSocket 构建后端，采用状态机管理会话生命周期（active/idle/cooling/gone），通过文件监控与进程扫描差异化发现各工具会话，并增量解析 JSONL 日志以避免全量重解析。系统模块化设计清晰，解析器、监控器、用量管理器分离，便于扩展新工具。
详细信息与使用说明
2. 解决的问题
开发者在使用本地 AI Agent 工具时，往往面临会话状态不透明、用量统计分散、历史数据难以追溯等问题。Nexus 通过集中监控三大工具的会话活动，将隐性的日志文件转化为直观的实时仪表盘，解决了无法快速了解当前 AI 使用情况、成本失控风险以及缺乏历史分析手段的痛点。
3. 适用场景
Nexus 适用于以下场景：1) 日常编码中监控 Claude Code、Codex 或 OpenClaw 的实时会话状态与消息流；2) 统计当前运行会话的 Token 消耗和预估 USD 成本，控制预算；3) 回溯历史会话数据，进行用量分析与报表生成；4) 在多工具混用时，统一查看各工具的累计用量对比。
4. 安装方式
安装 Nexus 需要 Node.js 环境。具体步骤：1) 克隆仓库：`git clone https://github.com/lusya123/Nexus.git && cd Nexus`；2) 安装后端依赖：`npm install`；3) 安装前端依赖：`cd client && npm install && cd ..`。仓库中未提及其他系统依赖或环境变量配置，安装过程仅依赖 npm。
5. 使用方式
日常使用：运行 `npm start` 启动一体化服务，浏览器访问 http://localhost:7878 即可查看监控界面。服务后台运行，不占用终端。常用命令：`npm status` 查看状态，`npm stop` 停止服务。开发模式：运行 `npm run dev:all` 启动前后端开发服务器，前端访问 http://localhost:5173（支持热重载），后端 API 仍运行在 7878 端口。Nexus 自动监控默认目录：~/.claude/projects/、~/.codex/sessions/、~/.openclaw/agents/。
6. 实现特点与扩展
Nexus 的核心实现特点包括：基于状态机的会话生命周期管理，转换规则基于时间与活跃信号；针对不同工具采用差异化发现策略，如 Claude Code 结合 lsof 与最近修改文件，Codex 按日期目录追踪活跃文件集合，OpenClaw 使用锁文件标记；增量读取 JSONL 日志，通过 fileOffsets 跟踪位置避免重复解析；WebSocket 实时推送会话与用量更新；模块化架构分离解析器、监控器、用量管理器，便于贡献新工具支持。详细扩展指南见 docs/CONTRIBUTING.md。
思维导图
Nexus
后端服务 (server/)
入口: index.js
解析器 (parsers/)
监控器 (monitors/)
用量统计 (usage/)
核心模块
前端应用 (client/)
React + Vite + TypeScript
主要组件: SessionCard, UsageBreakdownPanel
WebSocket 连接: useSessionsStream 钩子
状态管理: useDisplayedSessions
脚本与工具 (scripts/)
nexusctl.sh: 服务启动/停止/状态
dev-backend.js: 开发模式后端
ensure-dev-ports.js: 端口检查
测试 (tests/)
codex-regression.js
usage-parsers-regression.js
usage-manager-regression.js
pricing-stability-deep-regression.js
e2e-test.js
文档 (docs/)
API.md: WebSocket 协议与 HTTP 接口
ARCHITECTURE.md: 架构设计与状态机
CONTRIBUTING.md: 贡献指南
TROUBLESHOOTING.md: 故障排查
常见问题
Nexus 支持哪些 AI Agent 工具？
Nexus 支持 Claude Code、Codex 和 OpenClaw 三种本地 AI Agent 工具，自动发现并监控其会话活动、消息流和用量统计。
如何启动 Nexus 服务？
日常使用运行 `npm start` 启动一体化服务，然后访问 http://localhost:7878。开发模式运行 `npm run dev:all`，前端访问 http://localhost:5173。
Nexus 如何监控会话状态？
Nexus 通过文件监控与进程扫描检测活跃会话，基于状态机管理生命周期（active/idle/cooling/gone），转换规则基于时间窗口与活跃信号，并通过 WebSocket 实时推送状态更新。
如何查看 Token 使用量和成本？
Nexus 实时聚合当前运行会话的 Token 和 USD 成本，并在前端界面展示；同时提供全历史累计统计，按工具分别汇总，并支持通过 GET /api/usage/cost-history 接口查询分页历史数据。
Nexus 的安装有什么要求？
需要 Node.js 环境，克隆仓库后依次运行 `npm install` 和 `cd client && npm install` 安装依赖即可，无需额外配置。仓库中未提及其他系统依赖。