claude-tracker-suite

Claude 会话管理套件

搜索、浏览、监控和管理所有项目中的 Claude Code 会话历史记录。

工具概览

工具	用途
claude-tracker-search	按关键词或 ID 前缀搜索会话（独立脚本）
claude-tracker-pick	交互式 fzf 选择器：模糊查找近期会话、预览，并在 Ghostty 中按 Enter 恢复会话
index-transcripts.js	构建／刷新转录全文索引（对用户和助手文本使用 FTS5），并提取标题历史事件
backfill-summaries.js	生成缺失的会话摘要（使用 claude CLI 或 OpenRouter；默认禁用，使用 --enable 运行）
audit-suite.js	自审：清点、可移植性、守护进程、数据库覆盖率、搜索召回率 → AUDIT.md
search-regression.js	搜索栈的召回率回归测试用例（发生回归时退出码为 1）
open-sessions.js	列出排名前 N 的会话，并在 cmux 标签页／分屏中打开所选会话
claude-tracker-resume	查找并恢复崩溃／非活动会话
claude-tracker-alive	检查哪些会话有正在运行的进程
claude-tracker-watch	守护进程：自动为新会话生成摘要，并更新 active-projects.md
claude-tracker	列出近期会话及状态徽标（独立脚本）
new-session.sh	在 Ghostty／Cursor 中启动新会话（已禁用 VS Code），可选提示词或无头模式
resume-session.sh	在 cmux 标签页中打开会话（可选择在 Cursor 中打开项目；已禁用 VS Code）
detect-projects.js	扫描会话以查找所有项目，并检查 CLAUDE.md 覆盖情况
bootstrap-claude-setup.js	为新设备生成完整的 ~/.claude/ 配置
update-active-projects.py	使用丰富的会话数据重新生成 active-projects.md
checkpoint-session.js	在会话中创建／查询命名书签
quote-session.js	使用 FTS5 捕获／搜索重要语句
tag-session.js	手动为会话添加标签，并记录来源
claude-tracker-recent	显示最近 N 个会话及完整元数据（标题、标签、摘要、费用、模型）
claude-wrapper.sh	Shell 函数 cc，用于创建命名 Claude 会话并自动设置标签页标题
save-workspace.js	将运行中的会话快照保存到 ~/.claude/workspace-state.json
restore-workspace.sh	将已保存的会话恢复到 Ghostty 标签页
session-notify.sh	会话事件的 macOS 通知，以及 Ghostty 标签页徽标
open-file-explorer.sh	在 Ghostty 分屏中打开 yazi 文件管理器

独立脚本

命令会委托给独立的 Node.js 脚本（避免内联 node -e 时的 shell 转义问题）：

脚本	调用方	用途
scripts/search-sessions.js	/claude-tracker-search	在所有会话中按关键词搜索，或通过 --id 前缀查找
scripts/open-sessions.js	直接调用	列出前 N 个会话，确认后在 cmux 标签页/分屏中打开
scripts/list-sessions.js	/claude-tracker	列出最近的会话并显示状态徽章
scripts/new-session.sh	/spawn	在 Ghostty/Cursor（已禁用 VS Code）中启动新的交互式或提示词驱动会话，或以无头模式启动
scripts/resume-session.sh	直接调用	在 cmux 标签页中打开会话，可选择在 Cursor 中打开项目（已禁用 VS Code）
scripts/detect-projects.js	直接调用	发现项目并搭建 CLAUDE.md
scripts/bootstrap-claude-setup.js	直接调用	生成新机器设置
scripts/checkpoint-session.js	/checkpoint、/checkpoint-list	创建和查询会话检查点
scripts/quote-session.js	/quote、/quote-search	通过 FTS5 捕获并搜索带标签的短语
scripts/tag-session.js	/tag	手动为会话添加标签并记录来源
scripts/recent-sessions.js	/claude-tracker-recent	显示最近 N 个会话的标题、标签、摘要、模型和费用
scripts/claude-wrapper.sh	在 .zshrc 中引入	用于命名会话并设置标签页标题的 shell 函数 cc
scripts/save-workspace.js	直接调用 / launchd	将存活的会话快照保存到 workspace-state.json（会去重；绝不会用空快照覆盖有效快照）
scripts/restore-workspace.sh	直接调用	将 workspace-state.json 中的会话恢复到 Ghostty 标签页
scripts/claude-tracker-pick	直接调用	带预览的 fzf 会话选择器；Enter→Ghostty，Ctrl-O→当前终端，Ctrl-Y→复制
scripts/index-transcripts.js	直接调用 / 重量级会话后	增量式转录文本 FTS 索引器（EXTRACTOR_VERSION 4；清理已删除内容；提取标题历史事件）
scripts/backfill-summaries.js	直接调用	使用 claude 或 OpenRouter 提供方进行隔离式摘要回填（默认禁用）
scripts/audit-suite.js	直接调用	套件自审计 → AUDIT.md
scripts/search-regression.js	搜索变更后	召回测试样例，包括预期失败的语义缺口标记
scripts/session-notify.sh	直接调用 / 钩子	为会话事件发送 macOS 通知并显示 Ghostty 标签页徽章
scripts/open-file-explorer.sh	直接调用	在 Ghostty 分屏中打开 yazi
~/.claude/scripts/ghostty-resume.sh	直接调用	在新的 Ghostty 标签页中打开会话

所有脚本都使用 ~/.claude/lib/tracker-utils.js 中的共享工具（路径解码、会话解析、git 远程仓库检测），并使用 ~/.claude/lib/tracker-db.js 访问 SQLite（better-sqlite3，WAL 模式）。

快速开始

# Search by topic
claude-tracker-search "kothar mac mini"

# Lookup by session ID prefix (exact directory from JSONL ground truth)
node ~/.claude/skills/claude-tracker-suite/scripts/search-sessions.js --id d7b8f4dd

# Search by session name/slug only (fast — no JSONL body scan)
claude-tracker-search "thera" --name

# List top 10 sessions, open selected in cmux tabs
node ~/.claude/skills/claude-tracker-suite/scripts/open-sessions.js

# Open top 5 as vertical splits
node ~/.claude/skills/claude-tracker-suite/scripts/open-sessions.js --limit 5 --split right

# Check what's alive
claude-tracker-alive

# Resume crashed sessions in tmux
claude-tracker-resume --tmux

# Start auto-summarize daemon
claude-tracker-watch --daemon

搜索

claude-tracker-search "$ARGUMENTS"

搜索工作原理：默认路径会查询对话全文索引（通过 index-transcripts.js 构建，使用 FTS5 索引所有用户和助手的对话文本），并与标题、slug、摘要和首条提示词的元数据 FTS 合并（bm25 列权重：custom_title 为 3 倍，auto_title 为 2 倍，summary 为 2 倍，first_prompt 为 1.5 倍，slug 为 1 倍）。多词查询会在 会话 层级按词匹配（各词可以出现在不同消息中），通过 references/synonyms.json 中的同义词组扩展，并在 AND 搜索无结果时回退到 OR 搜索，同时显示标注的部分匹配提示。排序方式：按 IDF 加权的饱和匹配密度，并对短会话进行降权。结果包含带高亮的片段摘录。

旧标题回退：默认搜索也会检查 title_history，查找曾用标题与查询匹配、但当前标题不匹配的会话。即使会话被改成用户记忆中不同的名称，仍会在“旧标题匹配”标题下显示；结果数量设有上限，以免挤占正文结果。每条旧标题匹配结果都会显示旧名称、来源、日期，以及通过 titles 子命令查看完整时间线的链接。

标志 / 子命令	说明
--limit <n>	最大结果数（默认：15）
--id <prefix>	按会话 ID 前缀查找（8 个或更多字符）
--name	仅通过元数据 FTS 搜索标题、slug 和摘要（速度最快）
--deep	绕过索引：流式扫描原始 JSONL（适用于新会话或未编入索引的会话；匹配完整短语）
--open	立即在新的 Ghostty 标签页中恢复排名第一的结果
titles <id-prefix>	按时间顺序打印会话的标题/昵称时间线（包含所有重命名、slug、缓存和摘要器事件）

对话索引与摘要回填

# Incremental index refresh (skips unchanged files; run after heavy sessions)
node ~/.claude/skills/claude-tracker-suite/scripts/index-transcripts.js

# Full rebuild (also forced automatically when EXTRACTOR_VERSION bumps)
node ~/.claude/skills/claude-tracker-suite/scripts/index-transcripts.js --rebuild

# Backfill missing summaries — DISABLED BY DEFAULT, requires --enable
# (or TRACKER_SUMMARIZER=1). Hermetic when run: --safe-mode
# --no-session-persistence, no hooks fire, no synthetic sessions persist.
node ~/.claude/skills/claude-tracker-suite/scripts/backfill-summaries.js --enable
node ~/.claude/skills/claude-tracker-suite/scripts/backfill-summaries.js --enable --session <id-prefix>  # force one

# OpenRouter backend instead of claude CLI (default model moonshotai/kimi-k2;
# key from OPENROUTER_API_KEY or ~/.config/env/secrets.env)
node ~/.claude/skills/claude-tracker-suite/scripts/backfill-summaries.js --enable --provider openrouter

# Preview excerpts without any LLM calls (no gate needed)
node ~/.claude/skills/claude-tracker-suite/scripts/backfill-summaries.js --dry-run

# NOTE: the watcher-daemon auto-name path (update-active-projects.py) is also
# gated off by default; set TRACKER_AUTO_NAME=1 to re-enable it.

# Recall regression suite — run after touching search code or synonyms
node ~/.claude/skills/claude-tracker-suite/scripts/search-regression.js

# Suite self-audit → AUDIT.md (P0-P3 findings)
node ~/.claude/skills/claude-tracker-suite/scripts/audit-suite.js

增量索引会跳过大小、mtime 和提取器版本（当前为 EXTRACTOR_VERSION 4）均与 transcript_index_state 中的记录一致的文件。提高版本常量会按照新的提取规则强制完整重建索引。读取错误永远不会被记录为已编入索引——该会话仍会在下次运行时接受处理，避免部分读取永久导致搜索内容被屏蔽。仅在完整（不限量）运行中清理已删除的对话记录。

从 v4 开始，索引器还会从每份对话记录中提取标题历史事件：/rename 自定义标题行（来源为 user）、slug 变更（来源为 slug）。自定义标题行会根据该行自身的 sessionId 字段进行归属，而不是根据所在文件——/resume 后的 /rename 会写入当前活动的对话记录，但目标是上一个会话。Claude Code 自带的元数据扫描器会错误处理这种情况，用重命名目标会话的标题覆盖活动会话的标题。同一文件中连续重复的标题值会合并为一个事件。

已知的词法限制：只有会话中实际出现的词才能用于查找该会话——[expected fail] 回归测试夹具记录了这一点；未来指定用语义层（rlama）解决。

交互式选择器（重启恢复）

~/.claude/skills/claude-tracker-suite/scripts/claude-tracker-pick              # fuzzy-find recent 50
~/.claude/skills/claude-tracker-suite/scripts/claude-tracker-pick --here      # resume in current terminal
~/.claude/skills/claude-tracker-suite/scripts/claude-tracker-pick --project thera --limit 100

按 Enter 键可在 Ghostty 标签页中打开会话，按 Ctrl-O 可在当前终端中恢复会话，按 Ctrl-Y 可复制恢复命令。预览会显示标题、摘要和首条提示词。可搭配 restore-workspace.sh 使用（从 launchd 快照批量恢复）——选择器用于挑选会话，恢复脚本则用于“把所有内容都还给我”。

恢复崩溃的会话

claude-tracker-resume                    # List crashed sessions with resume commands
claude-tracker-resume --tmux             # Resume all in tmux windows
claude-tracker-resume --zsh              # Resume all in Terminal.app tabs (macOS)
claude-tracker-resume --all              # Include non-VS Code sessions
claude-tracker-resume --dry-run          # Preview without acting

智能回退：如果过期会话的 --resume 失败，则会在该项目目录中自动启动新会话。超过 7 天的会话会显示 STALE 标记。

活跃状态检测

检查哪些会话有正在运行的 Claude 进程：

claude-tracker-alive                     # Running + stale sessions overview
claude-tracker-alive --running           # Only sessions with active processes
claude-tracker-alive --stale             # Only sessions with no process
claude-tracker-alive --json              # Machine-readable output

将运行中的 claude PID（通过 pgrep + lsof 获取）与近期会话文件交叉比对。超过 3 天没有进程的会话会显示 OLD 标记。

自动摘要守护进程

监视新会话并自动填充摘要缓存：

claude-tracker-watch --status            # Check if daemon is running
claude-tracker-watch --daemon            # Start in background
claude-tracker-watch --stop              # Stop running daemon
claude-tracker-watch --verbose           # Foreground with debug output

守护进程监视 ~/.claude/projects/*/sessions-index.json 的变更。出现新会话时，它会从 Claude Code 元数据中缓存摘要，并重新生成 active-projects.md。有关 launchd plist 和生命周期的详细信息，请参阅 references/daemon-setup.md。

最近会话（完整元数据）

claude-tracker-recent                          # Last 10 sessions with full metadata
claude-tracker-recent --limit 20               # Last 20 sessions
claude-tracker-recent --json                   # Machine-readable JSON output
claude-tracker-recent --project myapp          # Filter by project
claude-tracker-recent --model opus             # Filter by model
claude-tracker-recent --since 7d               # Last 7 days only

每个会话显示：标题（自定义或自动生成）、摘要、所有标签（按类型使用不同颜色）、项目名称、时长、模型、费用、轮数、Git 分支、会话 ID 和恢复命令。第一个结果的恢复命令会自动复制到剪贴板。

会话列表

claude-tracker                           # All recent sessions
claude-tracker vscode                    # VS Code sessions only

speculator 运行时，会话列表包含：

• 标题栏：显示 Ghostty 标签页数和窗口数，以及运行中／非活动／VS Code 计数
• TTY 徽标：每个会话对应一个紫色的 s000–s010 徽标，显示它所在的 Ghostty 标签页

检测项目

node ~/.claude/skills/claude-tracker-suite/scripts/detect-projects.js                # List all
node ~/.claude/skills/claude-tracker-suite/scripts/detect-projects.js --suggest      # Suggest additions
node ~/.claude/skills/claude-tracker-suite/scripts/detect-projects.js --scaffold     # Create CLAUDE.md stubs
node ~/.claude/skills/claude-tracker-suite/scripts/detect-projects.js --since 30d    # Recent only

更新活跃项目

python3 ~/.claude/scripts/update-active-projects.py              # Regenerate active-projects.md
python3 ~/.claude/scripts/update-active-projects.py --summarize  # Show sessions needing summaries

生成的表格包含来自增强会话数据（从 JSONL 转录记录中提取）的 Model、Turns 和 Cost 列。Git worktree 会话会显示树形表情徽标。默认禁用自动命名路径（为没有摘要的会话单次调用 claude --model haiku）；设置 TRACKER_AUTO_NAME=1 可重新启用。Claude Code 原生会话摘要大约从 v2.1.31（2026 年 2 月）开始停止生成，因此较新会话的 sessions-index.json 摘要字段已过时；请改用 backfill-summaries.js 或转录索引。

初始化新配置

为新设备生成完整的 ~/.claude/ 配置：

node ~/.claude/skills/claude-tracker-suite/scripts/bootstrap-claude-setup.js --user "Name" --dry-run
node ~/.claude/skills/claude-tracker-suite/scripts/bootstrap-claude-setup.js --user "Name"

此操作会创建目录结构、全局 CLAUDE.md、userModel 模板、agent_docs 存根文件和项目 CLAUDE.md 脚手架。之后运行 /claude-md-manager，丰富生成的文件。

在新终端中恢复会话

在新的 cmux 标签页中打开会话，也可选择在编辑器中打开项目：

# Resume in cmux tab (default — auto-detects project directory)
~/.claude/skills/claude-tracker-suite/scripts/resume-session.sh <session-id>

# Resume in cmux + open project in Cursor
~/.claude/skills/claude-tracker-suite/scripts/resume-session.sh <session-id> --cursor

# Explicit project directory
~/.claude/skills/claude-tracker-suite/scripts/resume-session.sh <session-id> --project ~/Desktop/Programming

cmux 负责管理终端生命周期。--cursor 标志只会在编辑器中打开项目，会话始终在 cmux 中恢复。--vscode 已禁用（由 Ghostty 取代），使用时会发出警告并回退到 Ghostty。若 cmux 未运行，则回退为打印恢复命令。

在 Ghostty 标签页中恢复会话

在新的 Ghostty 标签页中打开会话（从 SQLite 或 JSONL 自动检测项目目录）：

~/.claude/scripts/ghostty-resume.sh <session-id>
~/.claude/scripts/ghostty-resume.sh <session-id> --project ~/my-project

使用 AppleScript 剪贴板粘贴模式，可靠地传递命令。如果 Ghostty 尚未运行，则会启动它。搜索结果和最近会话输出中，每个结果都包含一行 Ghostty:，其中显示可直接运行的命令。

新建会话／启动会话

在终端标签页中或以无头模式启动新的 Claude Code 会话：

# Interactive session in Ghostty (default)
~/.claude/skills/claude-tracker-suite/scripts/new-session.sh ~/my-project

# With a specific model
~/.claude/skills/claude-tracker-suite/scripts/new-session.sh ~/my-project --model opus

# Prompt-driven session in Ghostty tab
~/.claude/skills/claude-tracker-suite/scripts/new-session.sh ~/my-project --prompt "fix the login bug"

# Headless — runs in current terminal, returns JSON
~/.claude/skills/claude-tracker-suite/scripts/new-session.sh ~/my-project --headless --prompt "summarize the README"

# Headless with specific model and output format
~/.claude/skills/claude-tracker-suite/scripts/new-session.sh ~/my-project --headless --prompt "fix tests" --model haiku --output-format text

无头模式和提示词驱动模式使用 claude -p（Agent SDK CLI）。注意：-p 现已正式成为 Claude Agent SDK 的一部分，使用 SDK 计费，而非交互式会话计费。终端模式使用 AppleScript 剪贴板粘贴模式，可靠地传递命令（可处理提示词中的特殊字符）。

工作流：查找并恢复

1. claude-tracker-search "topic" — 查找匹配的会话
2. claude-tracker-recent — 浏览最近 10 个会话及其完整元数据
3. claude --resume <session-id> — 在当前终端中恢复会话
4. ~/.claude/scripts/ghostty-resume.sh <session-id> — 在新的 Ghostty 标签页中恢复会话
5. open-sessions.js — 列出热门会话，并在 cmux 标签页中打开所选会话
6. 或运行 claude-tracker-resume --tmux — 自动恢复所有崩溃的会话

工作流：在 cmux 中打开会话

列出最近的会话，并在 cmux 标签页或分屏中打开：

# List top 10, prompt for selection
node ~/.claude/skills/claude-tracker-suite/scripts/open-sessions.js

# Open as vertical splits
node ~/.claude/skills/claude-tracker-suite/scripts/open-sessions.js --split right

# Open all without confirmation
node ~/.claude/skills/claude-tracker-suite/scripts/open-sessions.js --yes

# JSON output for scripting
node ~/.claude/skills/claude-tracker-suite/scripts/open-sessions.js --json

会话目录根据 JSONL 事实来源（decodeProjectPath）解析，而非从 active-projects.md 获取。若 cmux 不可用，则回退为打印恢复命令。

完整的 cmux CLI 参考，请参阅 references/cmux-commands.md。

工作流：监控活跃工作

1. claude-tracker-alive — 查看哪些会话正在运行，哪些已过期
2. claude-tracker-watch --daemon — 持续自动更新摘要
3. 阅读 ~/.claude/agent_docs/active-projects.md — 查看整理后的项目概览

SQLite 数据库（tracker.db）

位于 ~/.claude/tracker.db 的单个 SQLite 数据库整合了所有会话元数据、Git 跟踪、标签以及三项新功能：检查点、阶段跟踪和带标签的短语。

API 模块：~/.claude/lib/tracker-db.js — 使用同步版 better-sqlite3、WAL 模式，并采用单例延迟打开。

# Query directly
sqlite3 ~/.claude/tracker.db "SELECT COUNT(*) FROM sessions;"
sqlite3 ~/.claude/tracker.db "SELECT phase, COUNT(*) FROM phases GROUP BY phase;"
sqlite3 ~/.claude/tracker.db "SELECT phrase, GROUP_CONCAT(tag) FROM tagged_phrases tp LEFT JOIN tagged_phrase_tags tpt ON tpt.phrase_id = tp.id GROUP BY tp.id ORDER BY tp.timestamp DESC LIMIT 10;"

迁移（幂等）：node ~/.claude/scripts/migrate-to-sqlite.js

标题／昵称历史记录

title_history 表记录会话曾使用过的所有名称及其来源。来源包括：user（来自 /rename 自定义标题行）、slug（Claude Code 自动生成的昵称）、cache（2026 年 5 月从 session-summaries.json 导入的元数据）、summarizer（来自 backfill-summaries.js）。

# Print the title timeline for a session
node ~/.claude/skills/claude-tracker-suite/scripts/search-sessions.js titles <id-prefix>

# Query raw history
sqlite3 ~/.claude/tracker.db "SELECT title, source, observed_at FROM title_history WHERE session_id LIKE 'abc%' ORDER BY observed_at;"

在转录记录索引期间（index-transcripts.js v4+）提取标题事件。/rename 条目根据该行自身的 sessionId 路由——在 /resume 后发出的重命名针对的是上一个会话，而非写入该条目的文件所属会话。这修正了一个已知的上游问题：Claude Code 的元数据扫描器会将重命名分配给错误的会话。

默认搜索会自动在“曾用标题匹配”标题下显示只能通过先前标题找到的会话。titles 子命令会打印完整的时间顺序记录：时间戳、来源、标题值以及跨会话重命名来源信息。

检查点

会话中的命名书签，记录标签、Git 状态、工作流阶段和已修改文件。

# Manual checkpoint
node ~/.claude/skills/claude-tracker-suite/scripts/checkpoint-session.js create "finished auth module"
node ~/.claude/skills/claude-tracker-suite/scripts/checkpoint-session.js create "pre-deploy" --summary "about to push"

# List checkpoints
node ~/.claude/skills/claude-tracker-suite/scripts/checkpoint-session.js list
node ~/.claude/skills/claude-tracker-suite/scripts/checkpoint-session.js list --phase implementing
node ~/.claude/skills/claude-tracker-suite/scripts/checkpoint-session.js list --limit 10

Git 提交（git-track-post.sh）和阶段转换（phase-detect.py）时会创建自动检查点。

阶段跟踪

通过 PostToolUse 钩子（phase-detect.py）自动检测工作流阶段。采用最近 10 次工具调用的滚动窗口，并通过滞后机制防止阶段来回切换。

阶段包括：exploring、planning、implementing、testing、reviewing、debugging、committing、deploying。

# Query current phase for a session
sqlite3 ~/.claude/tracker.db "SELECT phase, started_at FROM phases WHERE session_id = 'abc...' AND ended_at IS NULL;"

# Phase history
sqlite3 ~/.claude/tracker.db "SELECT phase, started_at, ended_at, duration_ms FROM phases WHERE session_id = 'abc...' ORDER BY started_at;"

# Phase analytics
sqlite3 ~/.claude/tracker.db "SELECT phase, COUNT(*) as transitions, AVG(duration_ms)/1000 as avg_seconds FROM phases GROUP BY phase;"

带标签的短语

从会话中摘录值得注意的内容并添加标签，可通过 FTS5 搜索。

# Capture a phrase
node ~/.claude/skills/claude-tracker-suite/scripts/quote-session.js capture "assumptions are the enemy" --tags principle,design

# Search phrases (FTS5)
node ~/.claude/skills/claude-tracker-suite/scripts/quote-session.js search "assumptions"

# List by tag
node ~/.claude/skills/claude-tracker-suite/scripts/quote-session.js tag principle

# List recent phrases
node ~/.claude/skills/claude-tracker-suite/scripts/quote-session.js list --limit 20

LLM 推理期间，Stop 钩子 session-tags-infer.py 也会自动提取短语。

命名会话（cc 包装器）

一个 shell 函数，用于包装 claude，自动为 Ghostty 标签页命名并添加跟踪器标签。

# Source in .zshrc (one-time setup)
source ~/.claude/skills/claude-tracker-suite/scripts/claude-wrapper.sh

# Start a named session
cc --name "kothar-refactor"

# Resume with a name
cc --resume abc12345 --name "auth-fix"

# Default: tab title = basename of cwd
cc

cc 函数会在启动 claude 前，通过 OSC 1 转义序列设置 Ghostty 标签页标题，然后在退出时将会话名称标记到 tracker.db 中。会话结束后，标签页标题会重置为目录基本名称。

标签页自动命名

new-session.sh、resume-session.sh 和 ghostty-resume.sh 均接受 --name，用于在启动时设置 Ghostty 标签页标题。如果未提供名称，默认格式为 {project-basename}—{session-id-prefix}。

# Named new session
~/.claude/skills/claude-tracker-suite/scripts/new-session.sh ~/my-project --name "auth-rewrite"

# Named resume
~/.claude/scripts/ghostty-resume.sh abc12345 --project ~/my-project --name "auth-rewrite"

标签页标题使用 VT 转义序列（\e]1;Title\a），在 claude 处于交互状态时会保持不变——shell 提示符不会重置它们。

工作区保存／恢复

为正在运行的 Claude 会话创建快照，并在 Ghostty 重启后恢复。

保存

# Snapshot current sessions
node ~/.claude/skills/claude-tracker-suite/scripts/save-workspace.js

# Preview without writing
node ~/.claude/skills/claude-tracker-suite/scripts/save-workspace.js --dry-run

通过 pgrep／lsof 检测存活会话（逻辑与 claude-tracker-alive 相同），将其与跟踪器数据库条目匹配，并将会话 ID、项目目录和标签页标题写入 ~/.claude/workspace-state.json。按 sessionId 去重（来自派生进程和 MCP 子进程的多个 PID 会合并为一个条目）。绝不会用空快照覆盖有效快照——崩溃或注销后若没有存活会话，会保留之前的快照，供 restore-workspace.sh 使用。

恢复

# Restore all saved sessions into Ghostty tabs
~/.claude/skills/claude-tracker-suite/scripts/restore-workspace.sh

# Preview what would be restored
~/.claude/skills/claude-tracker-suite/scripts/restore-workspace.sh --dry-run

# Restore at most 3 sessions
~/.claude/skills/claude-tracker-suite/scripts/restore-workspace.sh --limit 3

通过 ghostty-resume.sh 在新的 Ghostty 标签页中打开每个会话，并恢复保存的标签页标题。每次打开标签页之间间隔 2 秒。

自动快照（launchd）

位于 scripts/com.claude.workspace-snapshot.plist 的 launchd plist 每隔 300 秒运行一次 save-workspace.js。安装方法：

cp ~/.claude/skills/claude-tracker-suite/scripts/com.claude.workspace-snapshot.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.claude.workspace-snapshot.plist

会话通知

当 Claude 会话需要处理时发送 macOS 通知，并在 Ghostty 标签页标题上显示徽标。

# Custom notification
~/.claude/skills/claude-tracker-suite/scripts/session-notify.sh --title "Done" --message "Build complete"

# Preset: session completed
~/.claude/skills/claude-tracker-suite/scripts/session-notify.sh --session-done --project "my-app"

# Preset: needs user input
~/.claude/skills/claude-tracker-suite/scripts/session-notify.sh --needs-input --project "my-app"

# Tab badge only (no notification)
~/.claude/skills/claude-tracker-suite/scripts/session-notify.sh --tab-badge "✓" --tab-title "my-app"

# Silent notification (no sound)
~/.claude/skills/claude-tracker-suite/scripts/session-notify.sh --needs-input --no-sound

位于 ~/.claude/hooks/session-notify-hook.sh 的 Stop 钩子会在 Claude 停止时自动发送“需要输入”通知。它在 settings.json 中注册为异步钩子。

Yazi 文件浏览器

在 Ghostty 分屏中打开 yazi 文件管理器，以便浏览项目。

# Open yazi in a left split (default, sidebar-style)
~/.claude/skills/claude-tracker-suite/scripts/open-file-explorer.sh

# Open at a specific directory
~/.claude/skills/claude-tracker-suite/scripts/open-file-explorer.sh ~/my-project

# Split to the right instead
~/.claude/skills/claude-tracker-suite/scripts/open-file-explorer.sh --right

使用 System Events 剪贴板粘贴模式（按 Cmd+D 分屏，然后粘贴 yazi 命令）。需要安装 yazi：brew install yazi ffmpegthumbnailer unar jq poppler fd ripgrep fzf zoxide。

相关系统

• Git 跟踪 — PreToolUse/PostToolUse 钩子会拦截 git 命令，并为涉及的仓库标记会话。可通过 tracker-utils.js 函数（getSessionsForRepo、getReposForSession、getRecentCommits）查询。钩子文件和索引格式见 references/data-schemas.md。
• Speculator — 位于 ~/.claude/scripts/speculator/ 的守护进程每 5 分钟将 Ghostty 标签页映射到会话。list-sessions.js 使用 loadSpeculatorData() 和 getSessionTTY() 显示 TTY 徽标。健康检查：bash ~/.claude/scripts/speculator/status.sh
• Soul Registry — 在 ~/.claude/soul-sessions/registry.json 中通过心跳和 Slack 绑定实时跟踪会话。查看：python3 ~/.claude/hooks/soul-registry.py list --md。激活：/ensoul。绑定到 Slack：/slack-sync #channel。
• 会话报告 — /session-report 会生成 Markdown 仪表板，将会话状态与 git 活动汇总在一起。

参考资料

详细架构和基础设施信息：

• references/data-schemas.md — 会话索引、摘要缓存、JSONL 转录记录架构、title_history 架构；数据源位置；共享库 API
• references/search-mechanics.md — 转录记录 FTS 索引流水线、搜索查询解析、同义词扩展、AND 到 OR 的回退、曾用标题回退、排序算法
• references/daemon-setup.md — 监视器守护进程生命周期和 launchd plist 模板
• references/synonyms.json — 用于扩展搜索查询的双向同义词组（词干提取由 Porter 算法处理词形变化；组内列出不同词汇）
• references/cmux-commands.md — 完整的 cmux CLI 参考：层级结构、分屏、标签页、输入、浏览器、侧边栏、通知、键盘快捷键