Claude History

claude history 是一个查看Claude code会话并继续的Go软件, 缺省监听端口8888。

✨ 特性

• 单文件实现：所有功能集成在 main.go 一个文件中（约 900 行）
• 零依赖部署：编译后的二进制文件包含前端资源，无需额外文件
• 高性能：使用 Go 标准库，性能优异
• 跨平台：支持 Linux、macOS、Windows
• 实时流式传输：通过 SSE (Server-Sent Events) 实现实时更新
• 文件监控：使用 fsnotify 监控 Claude 会话文件变化

📦 依赖

• Go 1.21+：需要 Go 1.21 或更高版本
• fsnotify：唯一的外部依赖，用于文件监控
• Node.js（仅构建时）：用于构建前端资源

🚀 快速开始

构建

1. 构建前端资源：

npm install
npm run -s build:web

前端构建产物在 dist/web，Go 会直接嵌入该目录。

2. 编译 Go 程序：

go mod tidy
go build -o claude-history main.go

运行

直接运行编译好的二进制文件：

./claude-history

会监听在 :8888端口

用浏览器打开 http://ip:8888

命令行参数

./claude-history [选项]

选项:
  -p, -port <端口>       监听端口（默认: 8888）
  -d, -dir <路径>        Claude 目录路径（默认: ~/.claude）
  -dev                   开发模式（启用 CORS）
  -no-open               不自动打开浏览器
  -V, -version           显示版本信息

示例

# 使用默认设置运行
./claude-history

# 指定端口
./claude-history -p 8080

# 指定 Claude 目录
./claude-history -d /custom/path/.claude

# 不自动打开浏览器
./claude-history -no-open

# 开发模式（启用 CORS）
./claude-history -dev

🏗️ 架构设计

技术选型

功能	实现方案	说明
Web 框架	net/http 标准库	零依赖，性能优异
SSE 推送	http.Flusher	标准库实现
静态文件服务	embed + http.FileServer	嵌入前端资源
文件监控	fsnotify	唯一外部依赖
CLI 参数	flag 包	标准库
JSON 解析	encoding/json	标准库
并发控制	sync.Mutex + sync.Map	标准库

代码结构（900 行单文件）

main.go
├── 数据结构定义 (60 行)
│   ├── HistoryEntry
│   ├── Session
│   ├── ConversationMessage
│   └── StreamResult
│
├── 存储层实现 (350 行)
│   ├── Storage 结构体
│   ├── 文件索引构建
│   ├── 历史缓存管理
│   ├── 会话查询 (GetSessions, GetProjects)
│   ├── 对话查询 (GetConversation)
│   └── 流式读取 (GetConversationStream)
│
├── 文件监控实现 (100 行)
│   ├── Watcher 结构体
│   ├── 防抖机制 (20ms)
│   ├── 事件处理 (history.jsonl, *.jsonl)
│   └── 回调管理
│
├── HTTP 服务器实现 (350 行)
│   ├── Server 结构体
│   ├── API 路由
│   │   ├── GET /api/sessions
│   │   ├── GET /api/projects
│   │   ├── GET /api/sessions/stream (SSE)
│   │   ├── GET /api/conversation/:id
│   │   └── GET /api/conversation/:id/stream (SSE)
│   ├── 静态文件服务
│   ├── CORS 中间件
│   └── SSE 实现（心跳、增量推送）
│
└── 主函数和工具 (40 行)
    ├── CLI 参数解析
    ├── 信号处理 (SIGINT/SIGTERM)
    ├── 浏览器自动打开
    └── 优雅关闭

🔒 并发安全

• sync.RWMutex：保护历史缓存读写
• sync.Map：线程安全的文件索引和去重锁
• context.Context：管理 SSE 连接生命周期
• 防抖机制：文件变化事件防抖（20ms）

📊 性能指标

• 启动时间：< 500ms
• 内存占用：~15MB（空闲状态）
• 二进制文件大小：~9.3MB（包含前端资源）
• API 响应时间：< 50ms
• SSE 连接：支持 1000+ 并发连接

🛠️ 开发

修改前端

1. 修改 web/ 目录下的前端代码
2. 重新构建前端：npm run build:web
3. Go 会直接嵌入 dist/web（无需复制）
4. 重新编译 Go 程序：go build -o claude-run-go main.go

修改后端

1. 直接修改 main.go
2. 重新编译：go build -o claude-history main.go

📝 API 接口

1. 获取会话列表

GET /api/sessions
返回: Session[]

2. 获取项目列表

GET /api/projects
返回: string[]

3. 获取会话详情

GET /api/conversation/:id
返回: ConversationMessage[]

4. 实时会话列表（SSE）

GET /api/sessions/stream
事件: sessions, sessionsUpdate, heartbeat

5. 实时对话内容（SSE）

GET /api/conversation/:id/stream?offset=0
事件: messages, heartbeat

🚨 注意事项

1. 前端资源必须先构建：编译 Go 程序前必须先运行 npm run build:web
2. embed 路径：前端资源必须在 dist/web/ 目录下
3. 文件监控：需要 ~/.claude/ 目录存在且有读取权限
4. 端口占用：确保指定端口（默认 8888）未被占用
5. 信号处理：使用 Ctrl+C 或 SIGTERM 优雅关闭

📄 许可证

MIT