agent-sessions

Agent 会话

跨 Claude Code、Codex CLI、Gemini CLI、opencode、Hermes Agent 和 Cline CLI 搜索并管理 AI 编码 Agent 对话历史。

$ARGUMENTS

技能路径解析

当技能目录显示类似 r0/agent-sessions/SKILL.md 的路径时，将 r0 视为技能根目录别名，并先根据当前会话的技能根目录表解析。不要将该别名直接添加到文件系统路径前面。解析后的路径为：

<resolved-skill-root>/agent-sessions/SKILL.md

已安装的副本可能是指向源代码仓库的符号链接；编辑或重新安装技能前，请检查解析后的目标路径。

可用工具

CLI：agent-sessions

位于 /Users/vladmdgolam/Play/radar/tools/agent-sessions。这是一个 Python 3 脚本，可读取所有受支持 Agent 的会话数据。

# List all recent sessions (default 30)
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions

# Filter by agent
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --agent claude
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --agent codex
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --agent gemini
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --agent opencode
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --agent hermes
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --agent cline

# Title/prompt search first (AND logic, case-insensitive; token-efficient)
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --search "metal shader" --search-scope titles --limit 10

# Deep full-transcript search only when title/prompt search misses
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --search "metal shader" --search-scope full --limit 10

# Filter by project name or path
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --project radar

# Combine filters
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --agent claude --project aino --search "auth" --search-scope titles --limit 10

# Compact JSON output (for parsing; omits full transcript search_text)
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --json --limit 10

# Include full transcript search_text only if you need client-side full-text search
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --json --include-search-text --limit 10

# Copy compact context for one or more sessions
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --context <session-id>
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --context <id-1> <id-2>

# Build a compact evidence pack for one or more sessions
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --pack <id-1> <id-2> --max-chars 5000

# Read bounded excerpts, optionally around a topic/query
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --read <id-1> <id-2> --query "logo rotation" --max-chars 5000

# Extract only the user's messages
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --read <id-1> <id-2> --role user --max-chars 5000

# Resume a Claude Code session
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --resume <session-id>

# Control result count; prefer small limits unless the user asks for a broad scan
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --limit 10

TUI：claude-history

位于 ~/.local/bin/claude-history。这是一个基于 Rust 的模糊搜索 TUI，仅支持 Claude Code 会话。

# Interactive fuzzy search across all Claude sessions
claude-history

# Scoped to current project
claude-history --local

# View a specific session file
claude-history /path/to/session.jsonl

# Resume selected session
claude-history --resume

# Fork from a past session
claude-history --fork-session

GUI：Claude Code History Viewer (CCHV)

桌面应用位于 /Applications/Claude Code History Viewer.app。支持 7 种 Agent（Claude、Codex、Gemini、Cursor、Cline、Aider、OpenCode），提供分析、成本跟踪和全文搜索功能。

open "/Applications/Claude Code History Viewer.app"

数据来源

Agent	位置	格式
Claude Code	~/.claude/projects/<encoded>/*.jsonl	含有 type、message、cwd、sessionId、timestamp 的 JSONL
Codex	~/.codex/state_5.sqlite + ~/.codex/thread_history_1.sqlite；较旧或跳过迁移的运行记录位于 ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl	SQLite threads 元数据和 thread_items 消息；旧版 JSONL 回退
Gemini CLI	~/.gemini/tmp/*/chats/session-*.json	含有 sessionId、startTime 和 messages[] 数组的 JSON
opencode	~/.local/share/opencode/opencode.db	SQLite 表：session、message、part、project
Hermes Agent	~/.hermes/state.db	SQLite 表：sessions、messages
Cline CLI	~/.cline/data/db/sessions.db + ~/.cline/data/sessions/*/*.messages.json	SQLite 会话索引和 JSON 消息记录

Gemini 的项目映射：~/.gemini/projects.json 将绝对路径映射到项目名称。

通过 cline --data-dir <path> 创建的 Cline 会话，可通过将 AGENT_SESSIONS_CLINE_DATA_DIRS 设置为以冒号分隔的路径列表来纳入。

Codex 通常将这些数据库存储在 ~/.codex 下。如果 Codex 使用自定义主目录，请设置 CODEX_HOME；CLI 和 Sharingan 读取器都会遵循该设置。Codex 的 legacy_to_paginated_v1 迁移将线程元数据和对话记录移入两个 SQLite 数据库，并删除已成功迁移的运行记录 JSONL。CLI 仍会扫描剩余的运行记录文件，以查找迁移时跳过的会话，并根据 SQLite 线程 ID 去重。SQLite 读取为只读；CLI 刷新缓存时也会检查 WAL 辅助文件。

工作流

首要原则：切勿手动翻查

如果用户要求读取、继续、总结、比较或检查 Agent 对话，请先使用此 CLI。不要一开始就广泛运行 find ~、手动查询 SQLite，或复制正在使用的 Agent 数据库，除非此 CLI 无法工作。

对于明确指定的会话 ID，直接生成数据包：

python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --pack <session-id> --max-chars 8000

对于“此文件夹／项目中的最新对话”：

python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --project "$PWD" --limit 5
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --pack <top-session-id> --max-chars 8000

对于“最近的消息”或“上次进展到哪里”，优先先使用 --pack；它专为包含近期摘录而设计。后续需要针对特定内容时，使用 --read --query "topic"。

Token 高效检索阶梯

先使用最精简且有用的输出：

1. 先使用表格输出，并设置较小的上限：--limit 10。
2. 只要用户提供了线索，就添加 --agent 和／或 --project。
3. 优先搜索标题／提示词：--search "query" --search-scope titles。
4. 只有标题搜索无结果时，才回退到 --search-scope full。
5. 只有在需要结构化解析时才使用 --json；默认输出精简。
6. 除非要构建 UI／客户端索引，或明确要检查对话文本，否则不要使用 --include-search-text。
7. 需要交接上下文时，优先使用 --context <id...>，而不是粘贴完整 JSON。
8. 用户提供会话引用并要求比较、推断、总结或得出结论时，先运行 --pack <id...>。
9. 如果打包内容太宽泛，或用户提供了主题，则运行 --read <id...> --query "topic" 获取聚焦摘录。
10. 如果用户只询问自己的提示词／消息，则添加 --role user。

查找过去的对话

1. 运行 agent-sessions 并使用适当的筛选条件查找会话
2. 如果需要精简的交接内容块，则使用 --context <session-id>
3. 对于 Claude 会话：使用 claude --resume <id> 继续，或使用 claude-history 浏览
4. 要查看任意 Agent 的完整对话，请打开 CCHV

阅读提供的会话引用

如果用户粘贴了如下内容块：

agent: codex
session id: 019ee05b-25d6-7153-83af-aee3a848e472
session title: ...

提取 ID 并从以下命令开始：

python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --pack 019ee05b-25d6-7153-83af-aee3a848e472 <other-id> --max-chars 5000

使用打包内容作为跨会话结论的依据。如果用户询问特定主题，请使用：

python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --read <id-1> <id-2> --query "topic terms" --max-chars 5000

如果用户只想查看自己的消息／提示词：

python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --read <id-1> <id-2> --role user --max-chars 5000

除非用户明确要求详尽审阅，否则不要输出完整对话记录。

回答“我做过什么？”

# Recent activity across all agents
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --limit 20

# Specific project
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --project bloom-metal --limit 20

# Specific agent
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --agent codex --limit 20

恢复会话

# Find the session
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --search "shader bug" --search-scope titles --agent claude --limit 10

# Resume it (Claude only)
python3 /Users/vladmdgolam/Play/radar/tools/agent-sessions --resume <session-id>
# This execs into: claude --resume <session-id>

JSON 输出架构

使用 --json 时，每个会话对象包含：

{
  "agent": "claude|codex|gemini|opencode|hermes|cline",
  "session_id": "uuid",
  "prompt": "first user message (truncated to 120 chars)",
  "timestamp": "ISO 8601",
  "project_path": "/absolute/path/to/project",
  "project_name": "project-dir-name",
  "session_file": "/path/to/session/file"
}

默认情况下，--json 会省略 search_text。只有在进行全文索引／搜索客户端开发时，才传入 --include-search-text。

上下文输出

--context <session-id> 会输出可精简粘贴的上下文：

agent: opencode
session id: n
session title: K

多个 ID 会输出包含相同字段的列表。

打包与读取输出

--pack <id...> 会为每个会话输出一个有界证据包：元数据、简介、用户的关键请求，以及近期或与查询相关的摘录。

--read <id...> 会输出有界的对话记录摘录。对于较长的对话记录，输出包含初始概览摘录和 Recent Excerpts 尾部内容，避免“最后几条消息”被挤掉。添加 --query "terms" 可返回相关匹配项周围的消息窗口，而不是宽泛的摘录。

添加 --role user 可仅输出／搜索用户消息，或添加 --role assistant 仅输出助手摘录。默认为 --role all。

实用控制选项：

--role user            # only user messages
--max-chars 5000        # approximate excerpt budget per session
--last-turns 8          # recent messages included in packs/overflow reads
--context-messages 2    # messages before/after each query match