Back to Details

claude-tracker-suite

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Claude Session Management Suite

Claude 会话管理套件

Search, browse, monitor, and manage Claude Code session history across all projects.
跨所有项目搜索、浏览、监控和管理Claude Code的会话历史。

Tools Overview

工具概述

ToolPurpose
claude-tracker-search
Search sessions by keyword (standalone script)
claude-tracker-resume
Find and resume crashed/inactive sessions
claude-tracker-alive
Check which sessions have running processes
claude-tracker-watch
Daemon: auto-summarize new sessions, update active-projects.md
claude-tracker
List recent sessions with status badges (standalone script)
resume-in-vscode.sh
Open a session in a new VS Code (or Cursor) terminal via AppleScript
detect-projects.js
Scan sessions to find all projects, check CLAUDE.md coverage
bootstrap-claude-setup.js
Generate complete ~/.claude/ config for new machine
update-active-projects.py
Regenerate active-projects.md with enriched session data
工具用途
claude-tracker-search
按关键词搜索会话（独立脚本）
claude-tracker-resume
查找并恢复崩溃/非活跃会话
claude-tracker-alive
检查哪些会话有运行中的进程
claude-tracker-watch
守护进程：自动总结新会话，更新active-projects.md
claude-tracker
显示带有状态标识的近期会话（独立脚本）
resume-in-vscode.sh
通过AppleScript在新的VS Code（或Cursor）终端中打开会话
detect-projects.js
扫描会话以查找所有项目，检查CLAUDE.md的覆盖情况
bootstrap-claude-setup.js
为新机器生成完整的~/.claude/配置
update-active-projects.py
利用丰富的会话数据重新生成active-projects.md

Standalone Scripts

独立脚本

Commands delegate to standalone Node.js scripts (avoids shell escaping issues with inline 
node -e
):
ScriptCalled ByPurpose
scripts/search-sessions.js
/claude-tracker-search
Keyword search across all sessions (8K lines/file, noise-filtered)
scripts/list-sessions.js
/claude-tracker
List recent sessions with status badges
scripts/resume-in-vscode.sh
Direct invocationOpen session in new VS Code/Cursor terminal (macOS AppleScript)
scripts/detect-projects.js
Direct invocationProject discovery and CLAUDE.md scaffolding
scripts/bootstrap-claude-setup.js
Direct invocationNew machine setup generator
All scripts use 
~/.claude/lib/tracker-utils.js
for shared utilities (path decoding, session parsing, git remote detection).
命令委托给独立的Node.js脚本（避免使用内联
node -e
导致的shell转义问题）：
脚本调用方用途
scripts/search-sessions.js
/claude-tracker-search
跨所有会话进行关键词搜索（过滤噪音，支持8000行/文件）
scripts/list-sessions.js
/claude-tracker
显示带有状态标识的近期会话
scripts/resume-in-vscode.sh
直接调用在新的VS Code/Cursor终端中打开会话（macOS AppleScript）
scripts/detect-projects.js
直接调用项目发现与CLAUDE.md框架搭建
scripts/bootstrap-claude-setup.js
直接调用新机器环境生成器
所有脚本均使用
~/.claude/lib/tracker-utils.js
作为共享工具库（包含路径解码、会话解析、Git远程仓库检测等功能）。

Quick Start

快速开始

bash
undefined
bash
undefined

Search by topic

Search by topic

claude-tracker-search "kothar mac mini"
claude-tracker-search "kothar mac mini"

Interactive search with fzf

Interactive search with fzf

claude-tracker-search "kothar" --fzf
claude-tracker-search "kothar" --fzf

Search by session ID prefix

Search by session ID prefix

claude-tracker-search --id 1da2b718
claude-tracker-search --id 1da2b718

Check what's alive

Check what's alive

claude-tracker-alive
claude-tracker-alive

Resume crashed sessions in tmux

Resume crashed sessions in tmux

claude-tracker-resume --tmux
claude-tracker-resume --tmux

Start auto-summarize daemon

Start auto-summarize daemon

claude-tracker-watch --daemon
undefined
claude-tracker-watch --daemon
undefined

Search

搜索

bash
claude-tracker-search "$ARGUMENTS"
Search targets (weighted ranking): Summary (3x), First prompt (2x), Project name (1x), Git branch (1x).
FlagDescription
--limit <n>
Max results (default: 20)
--id <prefix>
Lookup by session ID prefix (8+ chars)
--project <name>
Filter by project name (substring)
--since <duration>
Recent only: 
7d
, 
24h
, 
30m
, 
2w
--json
Machine-readable JSON output
--fzf
Interactive selection via fzf (outputs resume command)
bash
claude-tracker-search "$ARGUMENTS"
搜索目标（加权排序）：总结（3倍权重）、首个提示词（2倍权重）、项目名称（1倍权重）、Git分支（1倍权重）。
参数说明
--limit <n>
最大结果数（默认：20）
--id <prefix>
按会话ID前缀查找（至少8个字符）
--project <name>
按项目名称过滤（支持子串匹配）
--since <duration>
仅显示近期会话：
7d
（7天）、
24h
（24小时）、
30m
（30分钟）、
2w
（2周）
--json
输出机器可读的JSON格式
--fzf
通过fzf进行交互式选择（输出恢复命令）

Resume Crashed Sessions

恢复崩溃的会话

bash
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
Smart fallback: if 
--resume
fails on an expired session, automatically starts a fresh session in that project directory. Sessions older than 7 days show a STALE badge.
bash
claude-tracker-resume                    # 列出崩溃的会话及恢复命令
claude-tracker-resume --tmux             # 在tmux窗口中恢复所有会话
claude-tracker-resume --zsh              # 在Terminal.app标签页中恢复所有会话（macOS）
claude-tracker-resume --all              # 包含非VS Code会话
claude-tracker-resume --dry-run          # 预览操作不执行实际恢复
智能回退：如果
--resume
在会话过期时失败，会自动在该项目目录中启动一个新会话。超过7天的会话会显示STALE标识。

Alive Detection

活跃状态检测

Check which sessions have running Claude processes:
bash
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
Cross-references running 
claude
PIDs (via 
pgrep
+ 
lsof
) against recent session files. Sessions >3 days without a process show an OLD badge.
检查哪些会话有运行中的Claude进程：
bash
claude-tracker-alive                     # 运行中+过期会话概览
claude-tracker-alive --running           # 仅显示有活跃进程的会话
claude-tracker-alive --stale             # 仅显示无进程的会话
claude-tracker-alive --json              # 输出机器可读格式
通过
pgrep
+ 
lsof
获取运行中的
claude
进程ID，并与近期会话文件进行交叉比对。超过3天无进程的会话会显示OLD标识。

Auto-Summarize Daemon

自动总结守护进程

Watch for new sessions and auto-populate summary cache:
bash
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
The daemon watches 
~/.claude/projects/*/sessions-index.json
for changes. When new sessions appear, it caches summaries from Claude Code metadata and regenerates 
active-projects.md
. See 
references/daemon-setup.md
for launchd plist and lifecycle details.
监控新会话并自动填充总结缓存：
bash
claude-tracker-watch --status            # 检查守护进程是否运行
claude-tracker-watch --daemon            # 在后台启动守护进程
claude-tracker-watch --stop              # 停止运行中的守护进程
claude-tracker-watch --verbose           # 在前台运行并输出调试信息
守护进程会监控
~/.claude/projects/*/sessions-index.json
的变化。当有新会话出现时，它会从Claude Code元数据中缓存总结，并重新生成
active-projects.md
。有关launchd配置文件和生命周期的详细信息，请参阅
references/daemon-setup.md
。

Session Listing

会话列表

bash
claude-tracker                           # All recent sessions
claude-tracker vscode                    # VS Code sessions only
bash
claude-tracker                           # 所有近期会话
claude-tracker vscode                    # 仅显示VS Code会话

Detect Projects

项目检测

bash
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
bash
node ~/.claude/skills/claude-tracker-suite/scripts/detect-projects.js                # 列出所有项目
node ~/.claude/skills/claude-tracker-suite/scripts/detect-projects.js --suggest      # 建议新增项目
node ~/.claude/skills/claude-tracker-suite/scripts/detect-projects.js --scaffold     # 创建CLAUDE.md模板
node ~/.claude/skills/claude-tracker-suite/scripts/detect-projects.js --since 30d    # 仅显示近期项目（30天内）

Update Active Projects

更新活跃项目

bash
python3 ~/.claude/scripts/update-active-projects.py              # Regenerate active-projects.md
python3 ~/.claude/scripts/update-active-projects.py --summarize  # Show sessions needing summaries
The generated table includes Model, Turns, and Cost columns from enriched session data (extracted from JSONL transcripts). Git worktree sessions show a tree emoji badge. Sessions without summaries are auto-named via one-shot 
claude --model haiku
call.
bash
python3 ~/.claude/scripts/update-active-projects.py              # 重新生成active-projects.md
python3 ~/.claude/scripts/update-active-projects.py --summarize  # 显示需要总结的会话
生成的表格包含来自丰富会话数据的模型、轮次和成本列（从JSONL转录文件中提取）。Git工作树会话会显示树形表情标识。无总结的会话会通过单次
claude --model haiku
调用自动命名。

Bootstrap New Setup

新环境快速搭建

Generate a complete 
~/.claude/
configuration for a new machine:
bash
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"
Creates directory structure, global CLAUDE.md, userModel template, agent_docs stubs, and project CLAUDE.md scaffolds. Follow up with 
/claude-md-manager
to enrich generated files.
为新机器生成完整的
~/.claude/
配置：
bash
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
丰富生成的文件。

Resume in New Terminal

在新终端中恢复会话

Open a session in a new Ghostty tab, VS Code terminal, or Cursor terminal (macOS AppleScript):
bash
undefined
在新的Ghostty标签页、VS Code终端或Cursor终端中打开会话（macOS AppleScript）：
bash
undefined

Resume session in Ghostty (default)

Resume session in Ghostty (default)

~/.claude/skills/claude-tracker-suite/scripts/resume-in-vscode.sh <session-id>
~/.claude/skills/claude-tracker-suite/scripts/resume-in-vscode.sh <session-id>

Resume in VS Code terminal

Resume in VS Code terminal

~/.claude/skills/claude-tracker-suite/scripts/resume-in-vscode.sh <session-id> --vscode
~/.claude/skills/claude-tracker-suite/scripts/resume-in-vscode.sh <session-id> --vscode

Resume in Cursor terminal

Resume in Cursor terminal

~/.claude/skills/claude-tracker-suite/scripts/resume-in-vscode.sh <session-id> --cursor
~/.claude/skills/claude-tracker-suite/scripts/resume-in-vscode.sh <session-id> --cursor

cd to a project first, then resume

cd to a project first, then resume

~/.claude/skills/claude-tracker-suite/scripts/resume-in-vscode.sh <session-id> --project ~/Desktop/Programming

System aliases: `code` → Cursor, `vscode` → VS Code. Ghostty is the default target.
~/.claude/skills/claude-tracker-suite/scripts/resume-in-vscode.sh <session-id> --project ~/Desktop/Programming

系统别名：`code` → Cursor，`vscode` → VS Code。默认目标终端为Ghostty。

Workflow: Find and Resume

工作流：查找并恢复会话

  1. claude-tracker-search "topic"
    — find matching sessions
  2. claude --resume <session-id>
    — resume in current terminal
  3. resume-in-vscode.sh <session-id>
    — resume in new VS Code terminal
  4. Or 
    claude-tracker-resume --tmux
    — auto-resume all crashed sessions
  1. claude-tracker-search "topic"
    — 查找匹配的会话
  2. claude --resume <session-id>
    — 在当前终端中恢复会话
  3. resume-in-vscode.sh <session-id>
    — 在新的VS Code终端中恢复会话
  4. 或
    claude-tracker-resume --tmux
    — 自动恢复所有崩溃的会话

Workflow: Monitor Active Work

工作流：监控活跃工作

  1. claude-tracker-alive
    — see what's running vs stale
  2. claude-tracker-watch --daemon
    — keep summaries auto-updated
  3. Read 
    ~/.claude/agent_docs/active-projects.md
    — curated project overview
  1. claude-tracker-alive
    — 查看运行中与过期的会话
  2. claude-tracker-watch --daemon
    — 保持总结自动更新
  3. 查看
    ~/.claude/agent_docs/active-projects.md
    — 精选项目概览

Related: Git Tracking

相关功能：Git追踪

Git-aware session tracking via PreToolUse/PostToolUse hooks intercepts all git commands and tags sessions with repos they touch. Enables cross-directory session discovery.
FilePurpose
~/.claude/hooks/git-track.sh
PreToolUse hook — logs git commands to JSONL
~/.claude/hooks/git-track-post.sh
PostToolUse hook — captures commit hashes
~/.claude/hooks/git-track-rebuild.py
Builds bidirectional index at SessionEnd
~/.claude/git-tracking.jsonl
Append-only event log (hot path)
~/.claude/git-tracking-index.json
Bidirectional session <-> repo index
Query functions in 
tracker-utils.js
:
  • loadGitTracking()
    — load the index
  • getSessionsForRepo(path)
    — find sessions that touched a repo
  • getReposForSession(sid)
    — find repos a session touched
  • getRecentCommits({hours, repoPath})
    — recent commits across sessions
  • getRecentGitEvents({hours})
    — raw event timeline
The 
/session-report
command generates a Markdown dashboard combining session status with git activity.
通过PreToolUse/PostToolUse钩子实现Git感知的会话追踪，拦截所有Git命令并为会话标记其涉及的仓库。支持跨目录会话发现。
文件用途
~/.claude/hooks/git-track.sh
PreToolUse钩子 — 将Git命令记录到JSONL文件
~/.claude/hooks/git-track-post.sh
PostToolUse钩子 — 捕获提交哈希
~/.claude/hooks/git-track-rebuild.py
在SessionEnd时构建双向索引
~/.claude/git-tracking.jsonl
仅追加的事件日志（热路径）
~/.claude/git-tracking-index.json
会话<->仓库双向索引
tracker-utils.js
中的查询函数：
  • loadGitTracking()
    — 加载索引
  • getSessionsForRepo(path)
    — 查找涉及指定仓库的会话
  • getReposForSession(sid)
    — 查找指定会话涉及的仓库
  • getRecentCommits({hours, repoPath})
    — 获取跨会话的近期提交
  • getRecentGitEvents({hours})
    — 获取原始事件时间线
/session-report
命令会生成一个Markdown仪表板，结合会话状态与Git活动。

Related: Soul Registry

相关功能：Soul Registry

The soul registry (
~/.claude/hooks/soul-registry.py
) tracks live sessions with heartbeats, topics, and Slack channel bindings. It complements the tracker suite:
Tracker SuiteSoul Registry
ScopeAll sessions, all timeActive sessions only
Data sourceJSONL transcripts, sessions-index.json
~/.claude/soul-sessions/registry.json
UpdatesAfter session ends (summaries)Real-time (heartbeat every turn)
PurposeSearch, resume, project detectionCross-session awareness, Slack binding
To view the live registry: 
python3 ~/.claude/hooks/soul-registry.py list --md
To activate Claudicle identity in a session: 
/ensoul
(opt-in per session). To bind a session to Slack: 
/slack-sync #channel
.
Soul Registry（
~/.claude/hooks/soul-registry.py
）通过心跳、主题和Slack频道绑定来追踪实时会话。它是追踪套件的补充：
追踪套件Soul Registry
范围所有会话，全时段仅活跃会话
数据源JSONL转录文件、sessions-index.json
~/.claude/soul-sessions/registry.json
更新方式会话结束后（总结）实时更新（每轮会话发送心跳）
用途搜索、恢复、项目检测跨会话感知、Slack绑定
查看实时注册表：
python3 ~/.claude/hooks/soul-registry.py list --md
在会话中激活Claudicle身份：
/ensoul
（每会话可选启用）。将会话绑定到Slack：
/slack-sync #channel
。

References

参考资料

For detailed schemas and infrastructure:
  • references/data-schemas.md
    — Session index, summary cache, and JSONL transcript schemas; data source locations; shared library API
  • references/daemon-setup.md
    — Watcher daemon lifecycle and launchd plist template
如需详细的 schema 和基础设施信息：
  • references/data-schemas.md
    — 会话索引、总结缓存和JSONL转录文件的schema；数据源位置；共享库API
  • references/daemon-setup.md
    — 监控守护进程的生命周期和launchd配置文件模板