Agent Sessions：给 AI 编程工具装一个「历史记录管理面板」

背景故事：你的 AI 编程助手今天写了什么？

深夜 11 点，你正在调试一个复杂的算法问题。Claude Code 已经跑了 30 分钟，写了上千行代码——然后突然断连了。明天要 demo，你翻遍终端记录也找不到刚才那段关键的逻辑在哪里。

或者另一种场景：你同时在用 Codex 写 Python、在 Cursor 里做代码审查、在 OpenCode 里做 Rust 重构。三个工具三个终端，各自的历史记录散落在磁盘各处，根本不知道「上次那个完美解决缓存穿透问题的会话」到底是哪个 agent 干的。

jazzyalex/agent-sessions 就是来解决这个问题的——它是一个本地优先的 macOS 应用，能把市面上主流 AI 编程工具的历史会话统一管理起来：搜索、检查、收藏、恢复，一站式搞定。

项目定位：会话考古学工具

从 GitHub 的 19 个 topics 可以看出这个项目的定位：['agentic-workflow', 'ai', 'ai-coding-agents', 'anthropic', 'claude-code', 'codex', 'codex-cli', 'copilot-cli', 'cursor-agent', 'developer-tools', 'hermes-agent', 'local-first', 'macos', 'openai', 'openclaw', 'opencode', 'session-history', 'session-management', 'transcript-search', 'usage-tracking']

核心关键词是 session-history 和 transcript-search。作者 jazzyalex 将自己定义为一个「会话考古学家」——帮助开发者从 AI agent 的磁盘输出中挖掘有价值的中间产物，避免重复劳动。

MIT 协议，完全本地化，无遥测数据，尊重用户隐私。

核心技术架构

技术栈

项目采用纯 Swift + macOS 原生开发，技术选型非常明确：

层级	技术选型	说明
语言	Swift 5.9+	要求 macOS 14+
UI框架	SwiftUI + AppKit	混用，原生 macOS 体验
构建	Xcode + Swift Package Manager	XcodeGen 可能用于工程管理
CI	GitHub Actions (macos-latest)	持续构建验证
更新	Sparkle	macOS 标准自动更新框架

代码结构（模块化插件架构）

项目代码量约 200+ 个 Swift 源文件，按功能分为以下模块：

会话发现与索引层

Services/SessionDiscovery.swift — 会话发现基类
Services/UnifiedSessionIndexer.swift — 统一索引引擎
Services/FilterEngine.swift — 过滤器引擎
每个 agent 有独立发现器和索引器：ClaudeSessionIndexer、CodexActiveSessionsModel、CursorSessionIndexer、HermesSessionIndexer、OpenCodeSessionIndexer、GeminiSessionIndexer、OpenClawSessionIndexer、PiSessionIndexer、DroidSessionIndexer、CopilotSessionIndexer

Agent 专用模块（每个 agent 独立目录）

AgentSessions/ClaudeResume/ — Claude 会话恢复
AgentSessions/CodexStatus/ — Codex 状态与用量追踪
AgentSessions/Hermes/ — Hermes 集成（读取 ~/.hermes/state.db 和 ~/.hermes/sessions）
AgentSessions/Cursor/ — Cursor Agent 会话
AgentSessions/OpenCode/ — OpenCode SQLite 历史
AgentSessions/Copilot/ — Copilot CLI
AgentSessions/GeminiResume/ — Gemini CLI
AgentSessions/Pi/ — Pi CLI
AgentSessions/Droid/ — Droid CLI
AgentSessions/GitInspector/ — Git 上下文分析

Agent Cockpit（Beta） — 实时指挥中心

AgentSessions/Views/CockpitView.swift — 实时会话监控视图
AgentSessions/CodexStatus/UsageFreshness.swift — 用量新鲜度检测
AgentSessions/ClaudeStatus/ClaudeOAuth/ — Claude API 用量 OAuth 集成
支持 iTerm2 集成，监控活跃会话状态

视图层

Views/Preferences/ — 设置面板（按 agent 分 tab）
Views/UnifiedSessionsView.swift — 统一会话列表
Views/TranscriptPlainView.swift — transcript 阅读器
Views/SessionTimelineView.swift — 时间线视图
Utilities/ImageBrowserViewModel.swift — 图片浏览器
Analytics/ — 使用分析面板（含热力图、统计卡片）

资源与脚本

Resources/ — Shell 脚本（codex_status_capture.sh、claude_usage_capture.sh 等）
docs/guides/ — 详细使用指南（每种 agent 独立文档）
scripts/ — 自动化测试脚本

核心功能详解

1. 多 Agent 会话统一管理

Agent Sessions 支持读取以下工具的本地会话数据：

Agent	数据来源	会话格式
Codex CLI	`~/.codex/sessions`	本地文件系统
Claude Code	`~/.claude/projects`	JSONL
OpenCode	`~/.local/share/opencode/opencode.db`	SQLite
Cursor Agent	`~/.cursor/projects` + `~/.cursor/chats`	Cursor 私有格式
Hermes	`~/.hermes/state.db` + `~/.hermes/sessions`	SQLite
OpenClaw	`~/.openclaw/agents`	私有格式
Gemini CLI	`~/.gemini/tmp`	文本
Copilot CLI	`~/.copilot/session-state`	状态文件
Pi CLI	`~/.pi/agent/sessions`	文本

核心亮点：对 Hermes 的支持非常深入，直接读取 ~/.hermes/state.db SQLite 数据库，这是 Hermes Agent 的核心状态存储。

2. Agent Cockpit（实时指挥中心）

这是项目最有特色的功能之一。Agent Cockpit 作为一个实时面板，可以：

显示当前所有活跃的 Codex CLI、Claude CLI、OpenCode iTerm2 会话
实时监控 API 用量（5小时/周限制）
Limits Widget：显示用量烧灼预测（burn prediction）——估算还剩多少时间用完 5 小时配额
支持 iTerm2 集成，在终端内直接看到 agent 活动状态

Limits Widget 的逻辑由 UsageFreshness.swift 和 UsageStaleCheck.swift 实现，通过 OAuth 获取 Codex/Claude 的实时用量数据。

3. 会话搜索与恢复

Unified Search：跨所有 agent 的全文搜索
In-Session Find：在单个 transcript 内快速跳转
Resume Command：右键复制恢复命令，在 Terminal.app / iTerm2 / Warp 中一键恢复会话
Saved Sessions：收藏重要会话，防止被清理覆盖

每个 agent 都有独立的 *ResumeCommandBuilder 和 *TerminalLauncher，适配不同的终端环境。

4. 隐私与安全

项目在安全和隐私方面设计非常谨慎：

完全本地化：所有数据存储在用户 Mac 本地，无任何网络上传
无遥测：README 明确声明「No telemetry, analytics, remote logging」
最小权限：读取用户指定的会话目录，支持自定义路径
Sparkle 更新：唯一网络活动是可选的自动更新检查

部署与安装

安装方式

项目仅支持 macOS 14+，两种安装途径：

DMG 下载（推荐）

# 下载最新 release
https://github.com/jazzyalex/agent-sessions/releases/download/v3.9.3/AgentSessions-3.9.3.dmg

Homebrew 安装

brew tap jazzyalex/agent-sessions
brew install --cask agent-sessions

构建开发版

xcodebuild -project AgentSessions.xcodeproj   -scheme AgentSessions   -configuration Debug   -destination 'platform=macOS' build

限制与局限

平台锁定：仅 macOS，无 Windows/Linux 支持，无服务端部署选项
Agent 支持的版本依赖：随着各 AI 工具版本迭代，需要持续更新解析逻辑（如 v3.9 版本提到需更新 Cursor Desktop 元数据监控）
非 hermes-realtime：本项目是 Hermes 会话的历史记录管理工具，与实时 Gateway 的 hook/jsonl 架构完全不同，两者用途互补
Sparkle 签名：生产环境需要代码签名和公证（codesign + notarytool）

行业意义

随着 AI 编程工具的普及，开发者面临的问题正在从「没有工具」变成「工具太多、历史太杂」。Agent Sessions 代表的趋势是 AI 工具的运维层——不是替代 AI 编程工具，而是帮助开发者更好地管理和复用 AI 的产出。

从数据上看，648 stars 且持续活跃（v3.9.3 刚发布），说明这个工具解决了真实的痛点。特别值得注意的是它对 Hermes 的深度集成——直接读取 state.db，说明作者与 Hermes 生态的联系非常紧密（甚至可能就是 Hermes 核心开发者之一）。

这个方向有潜力成为 AI coding 工具链中的「版本控制系统」——用 AI 写代码的人越多，对会话管理的需求就越强烈。

总结

维度	评分	说明
功能完整性	⭐⭐⭐⭐⭐	支持 9+ 种 AI agent，覆盖面极广
代码质量	⭐⭐⭐⭐	Swift 代码规范，完整测试套件，CI 完善
文档质量	⭐⭐⭐⭐⭐	每种 agent 有独立指南文档，CHANGELOG 详尽
隐私安全	⭐⭐⭐⭐⭐	本地优先，无遥测，MIT 协议
部署便利性	⭐⭐	仅 macOS，无容器化，需手动安装
创新性	⭐⭐⭐⭐	会话考古学概念独特，Limits Widget 实用

适合人群：深度使用多个 AI 编程工具的 macOS 开发者，特别是需要频繁回顾、复用 AI 会话产出的高级用户。