claude-tracker-suite

Claude Session Management Suite

すべてのプロジェクトにわたって、Claude Code のセッション履歴を検索、閲覧、監視、管理します。

ツールの概要

ツール	目的
claude-tracker-search	キーワードまたは ID の接頭辞でセッションを検索します（スタンドアロンスクリプト）
claude-tracker-pick	インタラクティブな fzf ピッカーです。最近のセッションをあいまい検索してプレビューでき、Enter キーで Ghostty で再開します
index-transcripts.js	トランスクリプトの全文検索インデックス（ユーザーとアシスタントのテキストを対象とする FTS5）を作成／更新し、タイトル履歴イベントを抽出します
backfill-summaries.js	セッションの要約がない場合に生成します（claude CLI または OpenRouter を使用します。デフォルトでは無効で、実行するには --enable を指定します）
audit-suite.js	自己監査を行います。インベントリ、移植性、デーモン、DB の網羅状況、検索の再現率を調査し、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	名前付き Claude セッションとタブタイトルの自動設定に対応するシェル関数 cc です
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 によるシェルのエスケープ問題を回避します）。

スクリプト	呼び出し元	目的
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 で読み込み	名前付きセッションとタブタイトルに対応するシェル関数 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 タブでセッションを開く

すべてのスクリプトは、共通ユーティリティ（パスのデコード、セッションの解析、git リモートの検出）に ~/.claude/lib/tracker-utils.js を、SQLite アクセス（better-sqlite3、WAL モード）に ~/.claude/lib/tracker-db.js を使用します。

クイックスタート

# 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 によるカスタムタイトル行（source user）、slug の変更（source slug）。カスタムタイトル行は、格納先ファイルではなく、その行自身の sessionId フィールドに基づいて振り分けられます。/resume の後に実行された /rename は、アクティブなトランスクリプトに書き込まれますが、対象は前のセッションです。Claude Code 自身のメタデータスキャナーはこの処理を誤り、アクティブなセッションのタイトルを、変更対象のセッションのタイトルで上書きします。同一ファイル内で連続して重複するタイトル値は、1 つのイベントにまとめられます。

既知の語彙上の制限：セッションは、その中に実際に含まれる語でしか見つけられません。この制限は [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 の実行中は、セッション一覧に次の情報が含まれます。

• ヘッダー：実行中／非アクティブ／VS Code の数とともに、Ghostty のタブ数とウィンドウ数を表示します
• 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

セッションディレクトリは、active-projects.md ではなく JSONL の正確なデータ（decodeProjectPath）から解決されます。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）

単一の SQLite データベース ~/.claude/tracker.db に、すべてのセッションメタデータ、Git の追跡情報、タグ、および新たに追加された 3 つの機能（チェックポイント、フェーズ追跡、タグ付きフレーズ）が集約されます。

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（session-summaries.json からの 2026 年 5 月のメタデータインポート）、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 ラッパー）

Ghostty のタブ名設定とトラッカーへのタグ付けを自動化する、claude をラップするシェル関数です。

# 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 はすべて、起動時に Ghostty のタブタイトルを設定する --name を受け付けます。名前が指定されていない場合のデフォルト形式は {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 が対話状態にある間はタイトルが維持され、シェルのプロンプトによってリセットされることはありません。

ワークスペースの保存／復元

実行中の 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 を 1 つのエントリにまとめます。クラッシュやログアウトによって稼働中のセッションが 0 件でも、正常なスナップショットを空の内容で上書きすることはありません。以前のスナップショットは 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 セッションで対応が必要になったときに、Ghostty のタブタイトルバッジとともに macOS 通知を表示します。

# 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 は、TTY バッジに loadSpeculatorData() と getSessionTTY() を使用します。ヘルスチェック：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 — /session-report は、セッションの状態と git のアクティビティをまとめた Markdown ダッシュボードを生成します。

リファレンス

スキーマとインフラストラクチャの詳細については、以下を参照してください。

• 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 の完全なリファレンス：階層、分割、タブ、入力、ブラウザー、サイドバー、通知、キーボードショートカット